1.. _module-pw_ring_buffer: 2 3============== 4pw_ring_buffer 5============== 6.. pigweed-module:: 7 :name: pw_ring_buffer 8 9The ``pw_ring_buffer`` module will eventually provide several ring buffer 10implementations, each with different tradeoffs. 11 12This documentation is incomplete :) 13 14----------------------- 15PrefixedEntryRingBuffer 16----------------------- 17:cpp:class:`pw::ring_buffer::PrefixedEntryRingBuffer` is a circular buffer for 18arbitrary length data entries with an optional user-defined preamble byte. It 19supports multiple independent readers. 20 21Iterator 22======== 23In crash contexts, it may be useful to scan through a ring buffer that may 24have a mix of valid (yet to be read), stale (read), and invalid entries. The 25``PrefixedEntryRingBufferMulti::iterator`` class can be used to walk through 26entries in the provided buffer. 27 28.. code-block:: cpp 29 30 // A test string to push into the buffer. 31 constexpr char kExampleEntry[] = "Example!"; 32 33 // Setting up buffers and attaching a reader. 34 std::byte buffer[1024]; 35 std::byte read_buffer[256]; 36 PrefixedEntryRingBuffer ring_buffer; 37 PrefixedEntryRingBuffer::Reader reader; 38 ring_buffer.SetBuffer(buffer); 39 ring_buffer.AttachReader(reader); 40 41 // Insert some entries and process some entries. 42 ring_buffer.PushBack(kExampleEntry); 43 ring_buffer.PushBack(kExampleEntry); 44 reader.PopFront(); 45 46 // !! A function causes a crash before we've read out all entries. 47 FunctionThatCrashes(); 48 49 // ... Crash Context ... 50 51 // You can use a range-based for-loop to walk through all entries. 52 for (auto entry : ring_buffer) { 53 PW_LOG_WARN("Read entry of size: %u", 54 static_cast<unsigned>(entry.buffer.size())); 55 } 56 57In cases where a crash has caused the ring buffer to have corrupted data, the 58iterator will progress until it sees the corrupted section and instead move to 59``iterator::end()``. The ``iterator::status()`` function returns a 60:cpp:class:`pw::Status` indicating the reason the iterator reached it's end. 61 62.. code-block:: cpp 63 64 // ... Crash Context ... 65 66 using iterator = PrefixedEntryRingBufferMulti::iterator; 67 68 // Hold the iterator outside any loops to inspect it later. 69 iterator it = ring_buffer.begin(); 70 for (; it != it.end(); ++it) { 71 PW_LOG_WARN("Read entry of size: %u", 72 static_cast<unsigned>(it->buffer.size())); 73 } 74 75 // Warn if there was a failure during iteration. 76 if (!it.status().ok()) { 77 PW_LOG_WARN("Iterator failed to read some entries!"); 78 } 79 80Data corruption 81=============== 82``PrefixedEntryRingBufferMulti`` offers a circular ring buffer for arbitrary 83length data entries. Some metadata bytes are added at the beginning of each 84entry to delimit the size of the entry. Unlike the iterator, the methods in 85``PrefixedEntryRingBufferMulti`` require that data in the buffer is not corrupt. 86When these methods encounter data corruption, there is no generic way to 87recover, and thus, the application crashes. Data corruption is indicative of 88other issues. 89