Scoped RAII producer transaction for staging and committing multiple elements with a single atomic release store.
WriteTransaction loads tail_ (relaxed) and head_ (acquire) once upon construction, caching the available capacity for the lifetime of the transaction. Elements constructed via emplace(), try_emplace(), push(), or try_push()—or written directly into contiguous_space() / write_space() and marked with advance()—are not visible to the consumer until Commit() is called or the WriteTransaction is destroyed.
Calling Abort() destroys any staged, uncommitted elements in reverse construction order and leaves the queue's tail_ unchanged.
WriteTransaction may be active on a queue at any time, and no direct producer methods (push(), try_push(), emplace(), try_emplace(), push_some(), move_push_some(), try_push_all(), try_move_push_all()) may be called on the queue while a WriteTransaction is active.Public Member Functions | |
| constexpr | WriteTransaction () noexcept=default |
Constructs an inactive, empty WriteTransaction. | |
| WriteTransaction (const WriteTransaction &)=delete | |
| WriteTransaction & | operator= (const WriteTransaction &)=delete |
| constexpr | WriteTransaction (WriteTransaction &&other) noexcept |
| WriteTransaction & | operator= (WriteTransaction &&other) noexcept |
| ~WriteTransaction () | |
| constexpr size_type | staged_count () const noexcept |
| constexpr size_type | remaining_capacity () const noexcept |
| constexpr bool | full () const noexcept |
Returns true if no more elements can be staged in this transaction. | |
| template<typename... Args> | |
| void | emplace (Args &&... args) |
| template<typename... Args> | |
| bool | try_emplace (Args &&... args) |
| void | push (const value_type &value) |
| void | push (value_type &&value) |
| bool | try_push (const value_type &value) |
| bool | try_push (value_type &&value) |
| size_type | push_some (span< const value_type > items) |
| size_type | move_push_some (span< value_type > items) |
| template<typename U = value_type, typename = std::enable_if_t< std::is_same_v<U, value_type> && std::is_trivially_default_constructible_v<U> && std::is_trivially_copyable_v<U>>> | |
| span< value_type > | contiguous_space () noexcept |
| template<typename U = value_type, typename = std::enable_if_t< std::is_same_v<U, value_type> && std::is_trivially_default_constructible_v<U> && std::is_trivially_copyable_v<U>>> | |
| std::pair< span< value_type >, span< value_type > > | write_space () noexcept |
| template<typename U = value_type, typename = std::enable_if_t< std::is_same_v<U, value_type> && std::is_trivially_default_constructible_v<U> && std::is_trivially_copyable_v<U>>> | |
| void | advance (size_type count) noexcept |
| size_type | Commit () noexcept |
| void | Abort () noexcept |
|
inlineconstexprnoexcept |
Moves an active WriteTransaction, transferring ownership of any uncommitted staged elements.
|
inline |
Automatically commits any staged elements when the transaction goes out of scope.
|
inlinenoexcept |
Destroys all uncommitted staged elements and rolls back the transaction without modifying the queue's atomic tail_.
|
inlinenoexcept |
Marks count elements written into contiguous_space() or write_space() as staged in this transaction.
Only available when T is trivially default constructible and trivially copyable.
count <= remaining_capacity(). Crashes via PW_ASSERT if count exceeds remaining_capacity().| [in] | count | Number of elements written into the writable span(s). |
|
inlinenoexcept |
Publishes all staged elements to the consumer with a single std::memory_order_release store to tail_.
After Commit(), staged_count() is reset to 0 and additional elements may still be staged up to the remaining remaining_capacity().
|
inlinenoexcept |
Returns the first contiguous span of writable slots starting at the current uncommitted producer position.
Only available when T is trivially default constructible and trivially copyable (such as std::byte, uint8_t, or POD structs), so writing directly into the returned span without placement new is well-defined. After writing n elements into the returned span, call advance(n) to mark them as staged.
remaining_capacity() contiguous elements before the end of the underlying ring buffer.
|
inline |
Constructs an element in-place at the next uncommitted producer slot without updating the queue's atomic tail_.
!full(). Crashes via PW_ASSERT if no space remains in this transaction.| [in] | args | Arguments forwarded to T's constructor. |
|
inline |
Stages as many elements from items as fit in remaining_capacity() by move.
| [in,out] | items | Span of elements to move into the transaction. |
|
inlinenoexcept |
Move-assigns a WriteTransaction, committing any elements staged in *this before transferring ownership from other.
|
inline |
Stages a copy of value at the next uncommitted producer slot.
!full(). Crashes via PW_ASSERT if full().| [in] | value | The value to copy into the queue. |
|
inline |
Stages value at the next uncommitted producer slot by move.
!full(). Crashes via PW_ASSERT if full().| [in] | value | The value to move into the queue. |
|
inline |
Stages as many elements from items as fit in remaining_capacity() by copy.
| [in] | items | Span of elements to copy into the transaction. |
|
inlineconstexprnoexcept |
Returns the number of additional elements that can be staged in this transaction without refreshing head_.
|
inlineconstexprnoexcept |
Returns the number of elements staged since the start of the transaction or the last Commit().
|
inline |
Attempts to construct an element in-place at the next uncommitted producer slot without updating the queue's atomic tail_.
| [in] | args | Arguments forwarded to T's constructor. |
true if the element was staged, or false if full().
|
inline |
Attempts to stage a copy of value at the next uncommitted producer slot.
| [in] | value | The value to copy into the queue. |
true if the element was staged, or false if full().
|
inline |
Attempts to stage value at the next uncommitted producer slot by move.
| [in] | value | The value to move into the queue. Left unmodified if false is returned. |
true if the element was staged, or false if full().
|
inlinenoexcept |
Returns both contiguous writable segments covering all remaining_capacity() slots in the transaction (handling ring buffer wrap-around).
Only available when T is trivially default constructible and trivially copyable. To preserve FIFO order, write elements sequentially into first from index 0 to first.size() - 1 before writing into second from index 0 to second.size() - 1 (second is empty if the available space does not wrap around the end of the ring buffer). After writing n total elements across first and second, call advance(n) to mark them as staged.
{first, second} in FIFO write order whose combined size equals remaining_capacity().