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

Overview

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

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.

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

thread safemaybe isr safemaybe nmi safemaybe

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
 

Constructor & Destructor Documentation

◆ ReadTransaction()

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

Moves an active ReadTransaction, transferring ownership of any uncommitted consumption progress.

◆ ~ReadTransaction()

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

Automatically commits all consumed elements when the transaction goes out of scope.

Member Function Documentation

◆ Commit()

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

Returns
The number of elements committed by this call.

◆ consume()

template<typename T , typename SizeType = size_t>
void pw::LockFreeSpscQueue< T, SizeType >::ReadTransaction::consume ( size_type  count)
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_.

Warning
Calling consume() immediately destroys consumed elements. Do not access consumed elements in a previously returned span from contiguous_data() or read_space() after calling consume().
Precondition
count <= remaining(). Crashes via PW_ASSERT if count exceeds remaining().
Parameters
[in]countNumber of elements to consume and destroy.

◆ consumed_count()

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

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

◆ contiguous_data() [1/2]

template<typename T , typename SizeType = size_t>
span< const value_type > pw::LockFreeSpscQueue< T, SizeType >::ReadTransaction::contiguous_data ( ) const
inlinenoexcept

Returns the first contiguous const span of unconsumed elements starting at the current consumer position.

Warning
Calling consume() immediately destroys consumed elements. Do not access consumed elements in a previously returned span after calling consume().

◆ contiguous_data() [2/2]

template<typename T , typename SizeType = size_t>
span< value_type > pw::LockFreeSpscQueue< T, SizeType >::ReadTransaction::contiguous_data ( )
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.

Warning
Calling consume() immediately destroys consumed elements. Do not access consumed elements in a previously returned span after calling consume().
Returns
A span of up to remaining() contiguous elements before the end of the underlying ring buffer.

◆ front() [1/2]

template<typename T , typename SizeType = size_t>
reference pw::LockFreeSpscQueue< T, SizeType >::ReadTransaction::front ( )
inline

Returns a mutable reference to the next unconsumed element in the transaction.

Precondition
!empty(). Crashes via PW_ASSERT if empty().

◆ front() [2/2]

template<typename T , typename SizeType = size_t>
const_reference pw::LockFreeSpscQueue< T, SizeType >::ReadTransaction::front ( ) const
inline

Returns a const reference to the next unconsumed element in the transaction.

Precondition
!empty(). Crashes via PW_ASSERT if empty().

◆ operator=()

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

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

◆ pop()

template<typename T , typename SizeType = size_t>
void pw::LockFreeSpscQueue< T, SizeType >::ReadTransaction::pop ( )
inline

Removes and destroys the next unconsumed element in the transaction without updating the queue's atomic head_.

Precondition
!empty(). Crashes via PW_ASSERT if empty().

◆ pop_some()

template<typename T , typename SizeType = size_t>
size_type pw::LockFreeSpscQueue< T, SizeType >::ReadTransaction::pop_some ( span< value_type >  dest)
inline

Moves (or copies if not move-assignable) up to dest.size() unconsumed elements into dest and destroys their slots in the queue.

Parameters
[out]destDestination span to receive the popped elements.
Returns
The number of elements popped into dest.

◆ read_space() [1/2]

template<typename T , typename SizeType = size_t>
std::pair< span< const value_type >, span< const value_type > > pw::LockFreeSpscQueue< T, SizeType >::ReadTransaction::read_space ( ) const
inlinenoexcept

Returns both contiguous const readable segments covering all remaining() unconsumed elements in the transaction in FIFO order (first followed by second).

Warning
Calling consume() immediately destroys consumed elements. Do not access consumed elements in a previously returned span after calling consume().

◆ read_space() [2/2]

template<typename T , typename SizeType = size_t>
std::pair< span< value_type >, span< value_type > > pw::LockFreeSpscQueue< T, SizeType >::ReadTransaction::read_space ( )
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.

Warning
Calling consume() immediately destroys consumed elements. Do not access consumed elements in a previously returned span after calling consume().
Returns
A pair of spans {first, second} in FIFO read order whose combined size equals remaining().

◆ try_peek() [1/2]

template<typename T , typename SizeType = size_t>
const_pointer pw::LockFreeSpscQueue< T, SizeType >::ReadTransaction::try_peek ( ) const
inlinenoexcept

Returns a const pointer to the next unconsumed element in the transaction, or nullptr if empty().

◆ try_peek() [2/2]

template<typename T , typename SizeType = size_t>
pointer pw::LockFreeSpscQueue< T, SizeType >::ReadTransaction::try_peek ( )
inlinenoexcept

Returns a pointer to the next unconsumed element in the transaction, or nullptr if empty().

◆ try_pop() [1/2]

template<typename T , typename SizeType = size_t>
std::optional< value_type > pw::LockFreeSpscQueue< T, SizeType >::ReadTransaction::try_pop ( )
inline

Removes and returns the next unconsumed element in the transaction, or std::nullopt if empty().

◆ try_pop() [2/2]

template<typename T , typename SizeType = size_t>
bool pw::LockFreeSpscQueue< T, SizeType >::ReadTransaction::try_pop ( value_type &  out)
inline

Removes the next unconsumed element in the transaction and assigns it to out if available.

Parameters
[out]outDestination object to receive the popped element. Left unmodified if false is returned.
Returns
true if an element was popped into out, or false if empty().

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