aboutsummaryrefslogtreecommitdiff
path: root/pw_ring_buffer/docs.rst
diff options
context:
space:
mode:
authorXin Li <delphij@google.com>2024-01-17 22:13:58 -0800
committerXin Li <delphij@google.com>2024-01-17 22:13:58 -0800
commit28d03a2a1cabbe01d7bcb6cf5166c10e50d3c2c6 (patch)
treec1643be8ab17fc607cea748a8bb1d621a5964873 /pw_ring_buffer/docs.rst
parentec2628a6ba2d0ecbe3ac10c8c772f6fc6acc345d (diff)
parentf054515492af5132f685cb23fe11891ee77104c9 (diff)
downloadpigweed-temp_319669529.tar.gz
Merge Android 24Q1 Release (ab/11220357)temp_319669529
Bug: 319669529 Merged-In: Iba357b308a79d0c8b560acd4f72b5423c9c83294 Change-Id: Icdf552029fb97a34e83c6dd7799433fc473a2506
Diffstat (limited to 'pw_ring_buffer/docs.rst')
-rw-r--r--pw_ring_buffer/docs.rst24
1 files changed, 11 insertions, 13 deletions
diff --git a/pw_ring_buffer/docs.rst b/pw_ring_buffer/docs.rst
index 673861042..dba41cecb 100644
--- a/pw_ring_buffer/docs.rst
+++ b/pw_ring_buffer/docs.rst
@@ -1,22 +1,25 @@
.. _module-pw_ring_buffer:
---------------
+==============
pw_ring_buffer
---------------
+==============
The ``pw_ring_buffer`` module will eventually provide several ring buffer
implementations, each with different tradeoffs.
This documentation is incomplete :)
-Compatibility
-=============
-* C++14
+-----------------------
+PrefixedEntryRingBuffer
+-----------------------
+:cpp:class:`pw::ring_buffer::PrefixedEntryRingBuffer` is a circular buffer for
+arbitrary length data entries with an optional user-defined preamble byte. It
+supports multiple independent readers.
Iterator
========
In crash contexts, it may be useful to scan through a ring buffer that may
have a mix of valid (yet to be read), stale (read), and invalid entries. The
-`PrefixedEntryRingBufferMulti::iterator` class can be used to walk through
+``PrefixedEntryRingBufferMulti::iterator`` class can be used to walk through
entries in the provided buffer.
.. code-block:: cpp
@@ -50,8 +53,8 @@ entries in the provided buffer.
In cases where a crash has caused the ring buffer to have corrupted data, the
iterator will progress until it sees the corrupted section and instead move to
-`iterator::end()`. The `iterator::status()` function returns a `pw::Status`
-indicating the reason the iterator reached it's end.
+``iterator::end()``. The ``iterator::status()`` function returns a
+:cpp:class:`pw::Status` indicating the reason the iterator reached it's end.
.. code-block:: cpp
@@ -80,8 +83,3 @@ entry to delimit the size of the entry. Unlike the iterator, the methods in
When these methods encounter data corruption, there is no generic way to
recover, and thus, the application crashes. Data corruption is indicative of
other issues.
-
-Dependencies
-============
-* ``pw_span``
-* ``pw_containers`` - for tests only