Skip to main content
Pigweed's logo Pigweed
code_xml
  1. Home
  2. Reference
  3. C/C++
  4. pw::LockFreeSpscQueue< T, SizeType >::WriteTransaction Class Reference
pw::LockFreeSpscQueue< T, SizeType >::WriteTransaction Class Reference

Overview

template<typename T, typename SizeType = size_t>
class pw::LockFreeSpscQueue< T, SizeType >::WriteTransaction

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.

Precondition
At most one 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.

thread safemaybe isr safemaybe nmi safemaybe

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
 

Constructor & Destructor Documentation

◆ WriteTransaction()

template<typename T , typename SizeType = size_t>
constexpr pw::LockFreeSpscQueue< T, SizeType >::WriteTransaction::WriteTransaction ( WriteTransaction &&  other)
inlineconstexprnoexcept

Moves an active WriteTransaction, transferring ownership of any uncommitted staged elements.

◆ ~WriteTransaction()

template<typename T , typename SizeType = size_t>
pw::LockFreeSpscQueue< T, SizeType >::WriteTransaction::~WriteTransaction ( )
inline

Automatically commits any staged elements when the transaction goes out of scope.

Member Function Documentation

◆ Abort()

template<typename T , typename SizeType = size_t>
void pw::LockFreeSpscQueue< T, SizeType >::WriteTransaction::Abort ( )
inlinenoexcept

Destroys all uncommitted staged elements and rolls back the transaction without modifying the queue's atomic tail_.

◆ advance()

template<typename T , typename SizeType = size_t>
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 pw::LockFreeSpscQueue< T, SizeType >::WriteTransaction::advance ( size_type  count)
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.

Precondition
count <= remaining_capacity(). Crashes via PW_ASSERT if count exceeds remaining_capacity().
Parameters
[in]countNumber of elements written into the writable span(s).

◆ Commit()

template<typename T , typename SizeType = size_t>
size_type pw::LockFreeSpscQueue< T, SizeType >::WriteTransaction::Commit ( )
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().

Returns
The number of elements committed by this call.

◆ contiguous_space()

template<typename T , typename SizeType = size_t>
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 > pw::LockFreeSpscQueue< T, SizeType >::WriteTransaction::contiguous_space ( )
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.

Returns
A writable span of up to remaining_capacity() contiguous elements before the end of the underlying ring buffer.

◆ emplace()

template<typename T , typename SizeType = size_t>
template<typename... Args>
void pw::LockFreeSpscQueue< T, SizeType >::WriteTransaction::emplace ( Args &&...  args)
inline

Constructs an element in-place at the next uncommitted producer slot without updating the queue's atomic tail_.

Precondition
!full(). Crashes via PW_ASSERT if no space remains in this transaction.
Parameters
[in]argsArguments forwarded to T's constructor.

◆ move_push_some()

template<typename T , typename SizeType = size_t>
size_type pw::LockFreeSpscQueue< T, SizeType >::WriteTransaction::move_push_some ( span< value_type >  items)
inline

Stages as many elements from items as fit in remaining_capacity() by move.

Parameters
[in,out]itemsSpan of elements to move into the transaction.
Returns
The number of elements staged.

◆ operator=()

template<typename T , typename SizeType = size_t>
WriteTransaction & pw::LockFreeSpscQueue< T, SizeType >::WriteTransaction::operator= ( WriteTransaction &&  other)
inlinenoexcept

Move-assigns a WriteTransaction, committing any elements staged in *this before transferring ownership from other.

◆ push() [1/2]

template<typename T , typename SizeType = size_t>
void pw::LockFreeSpscQueue< T, SizeType >::WriteTransaction::push ( const value_type &  value)
inline

Stages a copy of value at the next uncommitted producer slot.

Precondition
!full(). Crashes via PW_ASSERT if full().
Parameters
[in]valueThe value to copy into the queue.

◆ push() [2/2]

template<typename T , typename SizeType = size_t>
void pw::LockFreeSpscQueue< T, SizeType >::WriteTransaction::push ( value_type &&  value)
inline

Stages value at the next uncommitted producer slot by move.

Precondition
!full(). Crashes via PW_ASSERT if full().
Parameters
[in]valueThe value to move into the queue.

◆ push_some()

template<typename T , typename SizeType = size_t>
size_type pw::LockFreeSpscQueue< T, SizeType >::WriteTransaction::push_some ( span< const value_type >  items)
inline

Stages as many elements from items as fit in remaining_capacity() by copy.

Parameters
[in]itemsSpan of elements to copy into the transaction.
Returns
The number of elements staged.

◆ remaining_capacity()

template<typename T , typename SizeType = size_t>
constexpr size_type pw::LockFreeSpscQueue< T, SizeType >::WriteTransaction::remaining_capacity ( ) const
inlineconstexprnoexcept

Returns the number of additional elements that can be staged in this transaction without refreshing head_.

◆ staged_count()

template<typename T , typename SizeType = size_t>
constexpr size_type pw::LockFreeSpscQueue< T, SizeType >::WriteTransaction::staged_count ( ) const
inlineconstexprnoexcept

Returns the number of elements staged since the start of the transaction or the last Commit().

◆ try_emplace()

template<typename T , typename SizeType = size_t>
template<typename... Args>
bool pw::LockFreeSpscQueue< T, SizeType >::WriteTransaction::try_emplace ( Args &&...  args)
inline

Attempts to construct an element in-place at the next uncommitted producer slot without updating the queue's atomic tail_.

Parameters
[in]argsArguments forwarded to T's constructor.
Returns
true if the element was staged, or false if full().

◆ try_push() [1/2]

template<typename T , typename SizeType = size_t>
bool pw::LockFreeSpscQueue< T, SizeType >::WriteTransaction::try_push ( const value_type &  value)
inline

Attempts to stage a copy of value at the next uncommitted producer slot.

Parameters
[in]valueThe value to copy into the queue.
Returns
true if the element was staged, or false if full().

◆ try_push() [2/2]

template<typename T , typename SizeType = size_t>
bool pw::LockFreeSpscQueue< T, SizeType >::WriteTransaction::try_push ( value_type &&  value)
inline

Attempts to stage value at the next uncommitted producer slot by move.

Parameters
[in]valueThe value to move into the queue. Left unmodified if false is returned.
Returns
true if the element was staged, or false if full().

◆ write_space()

template<typename T , typename SizeType = size_t>
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 > > pw::LockFreeSpscQueue< T, SizeType >::WriteTransaction::write_space ( )
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.

Returns
A pair of writable spans {first, second} in FIFO write order whose combined size equals remaining_capacity().

The documentation for this class was generated from the following file: