Scoped RAII consumer transaction for inspecting and popping multiple elements with a single atomic release store.
ReadTransaction loads head_ (relaxed) and tail_ (acquire) once upon construction, caching the number of available elements. Elements popped or consumed through the transaction are destroyed immediately, and head_ is updated with a single std::memory_order_release store when Commit() is called or when the ReadTransaction is destroyed.
ReadTransaction may be active on a queue at any time, and no direct consumer methods (front(), try_peek(), pop(), try_pop(), pop_some(), pop_n()) may be called on the queue while a ReadTransaction is active.Public Member Functions | |
| constexpr | ReadTransaction () noexcept=default |
Constructs an inactive, empty ReadTransaction. | |
| ReadTransaction (const ReadTransaction &)=delete | |
| ReadTransaction & | operator= (const ReadTransaction &)=delete |
| constexpr | ReadTransaction (ReadTransaction &&other) noexcept |
| ReadTransaction & | operator= (ReadTransaction &&other) noexcept |
| ~ReadTransaction () | |
| constexpr size_type | consumed_count () const noexcept |
| constexpr size_type | remaining () const noexcept |
| Returns the number of unconsumed elements remaining in this transaction. | |
| constexpr bool | empty () const noexcept |
Returns true if no unconsumed elements remain in this transaction. | |
| reference | front () |
| const_reference | front () const |
| pointer | try_peek () noexcept |
| const_pointer | try_peek () const noexcept |
| void | pop () |
| std::optional< value_type > | try_pop () |
| bool | try_pop (value_type &out) |
| size_type | pop_some (span< value_type > dest) |
| span< value_type > | contiguous_data () noexcept |
| span< const value_type > | contiguous_data () const noexcept |
| std::pair< span< value_type >, span< value_type > > | read_space () noexcept |
| std::pair< span< const value_type >, span< const value_type > > | read_space () const noexcept |
| void | consume (size_type count) noexcept |
| size_type | Commit () noexcept |
|
inlineconstexprnoexcept |
Moves an active ReadTransaction, transferring ownership of any uncommitted consumption progress.
|
inline |
Automatically commits all consumed elements when the transaction goes out of scope.
|
inlinenoexcept |
Publishes all consumed elements to the producer with a single std::memory_order_release store to head_.
After Commit(), consumed_count() is reset to 0 and any remaining unconsumed elements in remaining() may still be read and consumed.
|
inlinenoexcept |
Destroys count unconsumed elements from the front of the transaction and advances the transaction's read cursor without updating the queue's atomic head_.
consume() immediately destroys consumed elements. Do not access consumed elements in a previously returned span from contiguous_data() or read_space() after calling consume().count <= remaining(). Crashes via PW_ASSERT if count exceeds remaining().| [in] | count | Number of elements to consume and destroy. |
|
inlineconstexprnoexcept |
Returns the number of elements consumed since the start of the transaction or the last Commit().
|
inlinenoexcept |
|
inlinenoexcept |
Returns the first contiguous span of unconsumed elements starting at the current consumer position.
After inspecting or reading n elements from the returned span, call consume(n) to destroy them and advance the transaction's read cursor.
consume() immediately destroys consumed elements. Do not access consumed elements in a previously returned span after calling consume().remaining() contiguous elements before the end of the underlying ring buffer.
|
inline |
Returns a mutable reference to the next unconsumed element in the transaction.
!empty(). Crashes via PW_ASSERT if empty().
|
inline |
Returns a const reference to the next unconsumed element in the transaction.
!empty(). Crashes via PW_ASSERT if empty().
|
inlinenoexcept |
Move-assigns a ReadTransaction, committing any elements consumed in *this before transferring ownership from other.
|
inline |
Removes and destroys the next unconsumed element in the transaction without updating the queue's atomic head_.
!empty(). Crashes via PW_ASSERT if empty().
|
inline |
Moves (or copies if not move-assignable) up to dest.size() unconsumed elements into dest and destroys their slots in the queue.
| [out] | dest | Destination span to receive the popped elements. |
dest.
|
inlinenoexcept |
Returns both contiguous const readable segments covering all remaining() unconsumed elements in the transaction in FIFO order (first followed by second).
|
inlinenoexcept |
Returns both contiguous readable segments covering all remaining() unconsumed elements in the transaction (handling ring buffer wrap-around).
To read elements in FIFO order (oldest to newest), read first sequentially from index 0 to first.size() - 1, followed by second from index 0 to second.size() - 1 (second is empty if the unconsumed elements do not wrap around the end of the ring buffer). After reading n total elements across first and second, call consume(n) to destroy them and advance the transaction's read cursor.
consume() immediately destroys consumed elements. Do not access consumed elements in a previously returned span after calling consume().{first, second} in FIFO read order whose combined size equals remaining().
|
inlinenoexcept |
Returns a const pointer to the next unconsumed element in the transaction, or nullptr if empty().
|
inlinenoexcept |
Returns a pointer to the next unconsumed element in the transaction, or nullptr if empty().
|
inline |
Removes and returns the next unconsumed element in the transaction, or std::nullopt if empty().
|
inline |
Removes the next unconsumed element in the transaction and assigns it to out if available.
| [out] | out | Destination object to receive the popped element. Left unmodified if false is returned. |
true if an element was popped into out, or false if empty().