- Adding lazy initialization for offsets_ in read-only buffers.

- Moving to use flag for initialization of write buffer for efficiency.

Author: avalerio-tkd

src/processing/byte_buffer.cpp

@@ -42,26 +42,27 @@ ByteBuffer::ByteBuffer(
     tcb::span<const uint8_t> elements_span,
     size_t element_size)
     : elements_span_(elements_span),
+      num_elements_(0),
       has_fixed_sized_elements_(true),
-      element_size_(element_size) {
-    InitializeFromSpan();
-}
+      element_size_(element_size),
+      is_initialized_from_span_(false) {}
 
 // Constructor for read-only buffer with variable-size elements.
 ByteBuffer::ByteBuffer(
     tcb::span<const uint8_t> elements_span)
     : elements_span_(elements_span),
+      num_elements_(0),
       has_fixed_sized_elements_(false),
-      element_size_(0) {
-    InitializeFromSpan();
-}
+      element_size_(0),
+      is_initialized_from_span_(false) {}
 
 // Initializes `num_elements_` and `offsets_` from the span.
-void ByteBuffer::InitializeFromSpan() {
+void ByteBuffer::InitializeFromSpan() const {
     // No elements to index. Initialize with empty values.
     if (elements_span_.empty()) {
         num_elements_ = 0;
         offsets_.clear();
+        is_initialized_from_span_ = true;
         return;
     }
 
@@ -76,6 +77,7 @@ void ByteBuffer::InitializeFromSpan() {
         }
         num_elements_ = elements_span_.size() / element_size_;
         offsets_.clear();
+        is_initialized_from_span_ = true;
         return;
     }
 
@@ -96,9 +98,20 @@ void ByteBuffer::InitializeFromSpan() {
         }
         cursor += current_element_size;
     }
-
-    // Set the number of elements from parsed offsets.
     num_elements_ = offsets_.size();
+    is_initialized_from_span_ = true;
+}
+
+void ByteBuffer::EnsureInitializedFromSpan() const {
+    // If the span is already initialized, skip it.
+    if (is_initialized_from_span_) {
+        return;
+    }
+    // If the write buffer is initialized, we don't need to initialize from the span.
+    if (is_write_buffer_initialized_) {
+        return;
+    }
+    InitializeFromSpan();
 }
 
 size_t ByteBuffer::EstimateOffsetsReserveCountFromSample(tcb::span<const uint8_t> bytes) {
@@ -146,6 +159,7 @@ size_t ByteBuffer::EstimateOffsetsReserveCountFromSample(tcb::span<const uint8_t
 // -----------------------------------------------------------------------------
 
 size_t ByteBuffer::CalculateOffsetOfElement(size_t position) const {
+    EnsureInitializedFromSpan();
     if (position >= num_elements_) {
         throw InvalidInputException("Element position out of range during CalculateOffsetOfElement");
     }
@@ -156,6 +170,7 @@ size_t ByteBuffer::CalculateOffsetOfElement(size_t position) const {
 }
 
 tcb::span<const uint8_t> ByteBuffer::GetElement(size_t position) const {
+    EnsureInitializedFromSpan();
     if (position >= num_elements_) {
         throw InvalidInputException("Element position out of range during GetElement");
     }
@@ -213,6 +228,7 @@ void ByteBuffer::InitializeForWriteBuffer(size_t variable_size_reserved_bytes_hi
         const size_t fixed_size_total_bytes = num_elements_ * element_size_;
         write_buffer_.clear();
         write_buffer_.resize(fixed_size_total_bytes, static_cast<uint8_t>(0));
+        is_write_buffer_initialized_ = true;
 
         // offsets_ are not used for fixed-size elements.
         offsets_.clear();
@@ -231,13 +247,14 @@ void ByteBuffer::InitializeForWriteBuffer(size_t variable_size_reserved_bytes_hi
     const size_t variable_size_reserved_bytes = std::max(variable_size_reserved_bytes_hint, min_required_prefix_bytes);
     write_buffer_.clear();
     write_buffer_.reserve(variable_size_reserved_bytes);
+    is_write_buffer_initialized_ = true;
 
     // offsets_ is initialized so the vector is fully allocated and have random-ish access during writes.
     offsets_.clear();
     offsets_.resize(num_elements_, kUnsetVariableElementOffset);
 
     // next_expected_sequential_position_ is initialized to 0 for sequential write checking.
-    next_expected_sequential_position_ = 0;
+    next_expected_write_position_ = 0;
 
     // elements_span_ is re-bound to the write buffer.
     RebindSpanToWriteBuffer();
@@ -248,16 +265,16 @@ void ByteBuffer::InitializeForWriteBuffer(size_t variable_size_reserved_bytes_hi
 // -----------------------------------------------------------------------------
 
 void ByteBuffer::SetElement(size_t position, tcb::span<const uint8_t> element) {
-    if (write_buffer_finalized_) {
+    if (is_write_buffer_finalized_) {
         throw InvalidInputException("Cannot SetElement: write buffer has been finalized");
     }
 
     if (position >= num_elements_) {
         throw InvalidInputException("Element position out of range during SetElement");
     }
 
-    if (write_buffer_.empty() && write_buffer_.capacity() == 0) {
-        throw InvalidInputException("Cannot SetElement: write buffer is not initialized");
+    if (!is_write_buffer_initialized_) {
+        throw InvalidInputException("Cannot SetElement: write buffer is not initialized.");
     }
 
     // For fixed-size elements, we write the element to buffer at the offset. No need to re-bind the span.
@@ -285,37 +302,37 @@ void ByteBuffer::SetElement(size_t position, tcb::span<const uint8_t> element) {
     append_u32_le(write_buffer_, static_cast<uint32_t>(element.size()));
     write_buffer_.insert(write_buffer_.end(), element.begin(), element.end());  // Appends at the end of the buffer.
 
-    // Update next_expected_sequential_position_ for sequential write checking.
-    if (next_expected_sequential_position_ != kUnsetVariableElementOffset) {
-        if (position == next_expected_sequential_position_) {
-            next_expected_sequential_position_ += 1;
+    // Update next_expected_write_position_ for sequential write checking.
+    if (next_expected_write_position_ != kUnsetVariableElementOffset) {
+        if (position == next_expected_write_position_) {
+            next_expected_write_position_ += 1;
         } else {
-            next_expected_sequential_position_ = kUnsetVariableElementOffset;
+            next_expected_write_position_ = kUnsetVariableElementOffset;
         }
     }
 
     RebindSpanToWriteBuffer();
 }
 
 std::vector<uint8_t> ByteBuffer::FinalizeAndTakeBuffer() {
-    if (write_buffer_finalized_) {
+    if (is_write_buffer_finalized_) {
         throw InvalidInputException("FinalizeAndTakeBuffer: write buffer has already been finalized");
     }
 
-    if (write_buffer_.empty() && write_buffer_.capacity() == 0) {
+    if (!is_write_buffer_initialized_) {
         throw InvalidInputException("FinalizeAndTakeBuffer: write buffer is not initialized");
     }
 
     // Fixed-size: write_buffer_ is always in element order, transfer ownership directly.
     if (has_fixed_sized_elements_) {
-        write_buffer_finalized_ = true;
+        is_write_buffer_finalized_ = true;
         return std::move(write_buffer_);
     }
 
     // For variable-size when all elements were written exactly once and in sequential order,
     // we can skip out-of-order or fragmentation checks.  This is the fast path.
     // This is the most common behavior when writing elements in single threaded mode.
-    if (next_expected_sequential_position_ == num_elements_) {
+    if (next_expected_write_position_ == num_elements_) {
         if (num_elements_ > 0) {
             const size_t last_element_offset = offsets_[num_elements_ - 1];
             const size_t last_element_size = ReadSizeAt(elements_span_, last_element_offset);
@@ -324,12 +341,12 @@ std::vector<uint8_t> ByteBuffer::FinalizeAndTakeBuffer() {
                 throw InvalidInputException("FinalizeAndTakeBuffer: trailing bytes detected beyond last element");
             }
         }
-        write_buffer_finalized_ = true;
+        is_write_buffer_finalized_ = true;
         return std::move(write_buffer_);
     }
 
     // For variable-size, when elements are written out of order, assume the buffer is fragmented and potentially with orphaned bytes
-    // The buffer is validated and rebuilt into a compact buffer in one pass.
+    // The buffer is validated and rebuilt into an ordered compact buffer in one pass.
     std::vector<uint8_t> result;
     result.reserve(write_buffer_.size());
     for (size_t i = 0; i < num_elements_; ++i) {
@@ -356,8 +373,9 @@ std::vector<uint8_t> ByteBuffer::FinalizeAndTakeBuffer() {
     // Defrag path returns a new buffer; release the original fragmented write buffer.
     write_buffer_.clear();
     write_buffer_.shrink_to_fit();
-
-    write_buffer_finalized_ = true;
+    is_write_buffer_initialized_ = false;
+    is_write_buffer_finalized_ = true;
+    
     return result;
 }
 

src/processing/byte_buffer.h

@@ -66,29 +66,32 @@ class ByteBuffer {
 
     // Variables for span elements reading
     tcb::span<const uint8_t> elements_span_;
-    size_t num_elements_;
+    mutable size_t num_elements_;
     bool has_fixed_sized_elements_;
 
     // Variables for determining offset of elements.
-    size_t element_size_;           // for fixed-size elements
-    std::vector<size_t> offsets_;   // for variable-size elements
+    size_t element_size_;                   // for fixed-size elements
+    mutable std::vector<size_t> offsets_;   // for variable-size elements
 
     // Variables for write buffer.
     std::vector<uint8_t> write_buffer_;
-    bool write_buffer_finalized_ = false;
 
     // Variable for sequential variable-size writes.
     // Tracks next expected position for sequential variable-size writes.
     // Value is invalidated to kUnsetVariableElementOffset once order is violated.
-    size_t next_expected_sequential_position_ = 0;
+    size_t next_expected_write_position_ = 0;
 
 private:
-    // Initialization methods for read-only buffer
-    void InitializeFromSpan();
+    // Initialization methods and flags for read-only buffer
+    void InitializeFromSpan() const;
+    void EnsureInitializedFromSpan() const;
+    mutable bool is_initialized_from_span_ = false;
 
-    // Initialization methods for write buffer
+    // Initialization methods and flags for write buffer
     void InitializeForWriteBuffer(size_t variable_size_reserved_bytes_hint);
     void RebindSpanToWriteBuffer();
+    bool is_write_buffer_initialized_ = false;
+    bool is_write_buffer_finalized_ = false;    
 };
 
 inline constexpr size_t kUnsetVariableElementOffset = std::numeric_limits<size_t>::max();

src/processing/byte_buffer_test.cpp

@@ -82,6 +82,8 @@ std::vector<uint8_t> MakePayload(size_t size, uint8_t seed) {
 TEST(ByteBufferTest, ConstructFixedSize_ValidBuffer_InitializesExpectedState) {
     std::vector<uint8_t> bytes = {0x01, 0x02, 0x03, 0x04, 0x05, 0x06};
     ByteBufferTestProxy buffer(tcb::span<const uint8_t>(bytes), 2);
+    // Trigger lazy span initialization.
+    EXPECT_NO_THROW((void)buffer.GetElement(0));
     ExpectCommonState(buffer, 3u, true, 2u);
     EXPECT_TRUE(buffer.GetOffsets().empty());
 }
@@ -107,12 +109,14 @@ TEST(ByteBufferTest, GetElement_FixedSize_ReturnsExpectedSlices) {
 
 TEST(ByteBufferTest, ConstructFixedSize_ZeroElementSize_Throws) {
     std::vector<uint8_t> bytes = {0x01, 0x02, 0x03, 0x04};
-    EXPECT_THROW((void)ByteBufferTestProxy(tcb::span<const uint8_t>(bytes), 0), InvalidInputException);
+    ByteBufferTestProxy buffer(tcb::span<const uint8_t>(bytes), 0);
+    EXPECT_THROW((void)buffer.GetElement(0), InvalidInputException);
 }
 
 TEST(ByteBufferTest, ConstructFixedSize_NonDivisibleSize_Throws) {
     std::vector<uint8_t> bytes = {0x01, 0x02, 0x03};
-    EXPECT_THROW((void)ByteBufferTestProxy(tcb::span<const uint8_t>(bytes), 2), InvalidInputException);
+    ByteBufferTestProxy buffer(tcb::span<const uint8_t>(bytes), 2);
+    EXPECT_THROW((void)buffer.GetElement(0), InvalidInputException);
 }
 
 TEST(ByteBufferTest, ConstructVariableSize_ValidEncodedBuffer_InitializesExpectedState) {
@@ -122,6 +126,8 @@ TEST(ByteBufferTest, ConstructVariableSize_ValidEncodedBuffer_InitializesExpecte
         0x07, 0x00, 0x00, 0x00, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37
     };
     ByteBufferTestProxy buffer{tcb::span<const uint8_t>(bytes)};
+    // Trigger lazy variable-size index parsing.
+    EXPECT_NO_THROW((void)buffer.GetElement(0));
     ExpectCommonState(buffer, 2u, false, 0u);
     ASSERT_EQ(buffer.GetOffsets().size(), 2u);
     EXPECT_EQ(buffer.GetOffsets()[0], 0u);
@@ -603,13 +609,15 @@ TEST(ByteBufferTest, ConstructVariableSize_EmptyBuffer_InitializesEmptyState) {
 
 TEST(ByteBufferTest, ConstructVariableSize_TruncatedLengthPrefix_Throws) {
     std::vector<uint8_t> bytes = {0x01, 0x00, 0x00}; // only 3 bytes
-    EXPECT_THROW((void)ByteBufferTestProxy(tcb::span<const uint8_t>(bytes)), InvalidInputException);
+    ByteBufferTestProxy buffer{tcb::span<const uint8_t>(bytes)};
+    EXPECT_THROW((void)buffer.GetElement(0), InvalidInputException);
 }
 
 TEST(ByteBufferTest, ConstructVariableSize_TruncatedPayload_Throws) {
     // Declares payload length 5, but provides only 2 bytes.
     std::vector<uint8_t> bytes = {
         0x05, 0x00, 0x00, 0x00, 0xAA, 0xBB
     };
-    EXPECT_THROW((void)ByteBufferTestProxy(tcb::span<const uint8_t>(bytes)), InvalidInputException);
+    ByteBufferTestProxy buffer{tcb::span<const uint8_t>(bytes)};
+    EXPECT_THROW((void)buffer.GetElement(0), InvalidInputException);
 }