Bounded single-producer/single-consumer queue. More...

#include <concurrency_utils.H>

Collaboration diagram for Aleph::SpscQueue< T >:

Public Member Functions
	SpscQueue (size_t capacity)
	Construct a queue with the specified capacity.

	SpscQueue (const SpscQueue &)=delete
	Deleted copy constructor.

SpscQueue &	operator= (const SpscQueue &)=delete
	Deleted copy assignment operator.

size_t	capacity () const noexcept
	Return the queue's capacity.

bool	empty () const noexcept
	Check if the queue is empty.

bool	full () const noexcept
	Check if the queue is full.

size_t	size () const noexcept
	Return the number of items currently in the queue.

bool	try_push (const T &value)
	Attempt to push an item (copy) into the queue.

bool	try_push (T &&value)
	Attempt to push an item (move) into the queue.

template<typename... Args>
bool	emplace (Args &&... args)
	Construct an item in-place at the tail of the queue.

bool	try_pop (T &out)
	Attempt to pop an item from the queue into `out`.

std::optional< T >	try_pop ()
	Attempt to pop an item from the queue.

Private Member Functions
size_t	advance (size_t idx) const noexcept
	Compute the next index in the circular buffer.

template<typename... Args>
bool	emplace_impl (Args &&... args)
	Internal implementation for push/emplace.

Private Attributes
std::vector< std::optional< T > >	slots_

size_t	storage_size_

std::atomic< size_t >	head_ {0}

std::atomic< size_t >	tail_ {0}

Detailed Description

template<typename T>
class Aleph::SpscQueue< T >

Bounded single-producer/single-consumer queue.

This queue is a lock-free, bounded circular buffer designed for high- performance handoff between exactly one producer thread and one consumer thread. It is thread-safe only for that single-producer / single-consumer usage pattern. Concurrent calls from multiple producers or multiple consumers are not supported.

Warning: This class is NOT thread-safe for multiple producers or multiple consumers. Use Aleph::BoundedChannel for MPMC scenarios.

Operations are non-blocking and never close. Producers observe failure by receiving false when the ring is full; consumers observe emptiness by receiving false or std::nullopt. If element extraction throws, the slot remains occupied until extraction succeeds.

Template Parameters

T	The type of elements stored in the queue.

Definition at line 1101 of file concurrency_utils.H.

Constructor & Destructor Documentation

◆ SpscQueue() [1/2]

template<typename T >

Aleph::SpscQueue< T >::SpscQueue ( size_t capacity )

inlineexplicit

Construct a queue with the specified capacity.

Parameters

capacity Maximum number of items the queue can hold.

Exceptions

std::invalid_argument if capacity is zero.

Note: This constructor does not block and is not thread-safe against concurrent access to the object being constructed.

Definition at line 1134 of file concurrency_utils.H.

References Aleph::SpscQueue< T >::capacity().

◆ SpscQueue() [2/2]

template<typename T >

Aleph::SpscQueue< T >::SpscQueue ( const SpscQueue< T > & )

delete

Deleted copy constructor.

Member Function Documentation

◆ advance()

template<typename T >

size_t Aleph::SpscQueue< T >::advance ( size_t idx ) const

inlineprivatenoexcept

Compute the next index in the circular buffer.

Definition at line 1109 of file concurrency_utils.H.

References Aleph::SpscQueue< T >::storage_size_.

Referenced by Aleph::SpscQueue< T >::emplace_impl(), Aleph::SpscQueue< T >::full(), Aleph::SpscQueue< T >::try_pop(), and Aleph::SpscQueue< T >::try_pop().

◆ capacity()

template<typename T >

size_t Aleph::SpscQueue< T >::capacity ( ) const

inlinenoexcept

Return the queue's capacity.

Returns: The maximum number of user-visible items.

Exceptions

Nothing.

Note: Safe to call from either the producer or consumer thread, non-blocking, reentrant, and noexcept.

Definition at line 1152 of file concurrency_utils.H.

References Aleph::SpscQueue< T >::storage_size_.

Referenced by Aleph::SpscQueue< T >::SpscQueue().

◆ emplace()

template<typename T >

template<typename... Args>

bool Aleph::SpscQueue< T >::emplace ( Args &&... args )

inline

Construct an item in-place at the tail of the queue.

Template Parameters

Args	Constructor argument types.

Parameters

args	Constructor arguments.

Returns: true if the item was enqueued, false if the queue is full.

Exceptions

Any	exception thrown while constructing `T` in-place.

Note: Non-blocking and only safe to call from the single producer thread.

Definition at line 1217 of file concurrency_utils.H.

References Aleph::divide_and_conquer_partition_dp(), and Aleph::SpscQueue< T >::emplace_impl().

◆ emplace_impl()

template<typename T >

template<typename... Args>

bool Aleph::SpscQueue< T >::emplace_impl ( Args &&... args )

inlineprivate

Internal implementation for push/emplace.

Definition at line 1116 of file concurrency_utils.H.

References Aleph::SpscQueue< T >::advance(), Aleph::divide_and_conquer_partition_dp(), Aleph::SpscQueue< T >::head_, Aleph::next(), Aleph::SpscQueue< T >::slots_, and Aleph::SpscQueue< T >::tail_.

Referenced by Aleph::SpscQueue< T >::emplace(), Aleph::SpscQueue< T >::try_push(), and Aleph::SpscQueue< T >::try_push().

◆ empty()

template<typename T >

bool Aleph::SpscQueue< T >::empty ( ) const

inlinenoexcept

Check if the queue is empty.

Returns: true if the queue currently contains no items.

Exceptions

Nothing.

Note: Safe to call from either the producer or consumer thread.

Definition at line 1159 of file concurrency_utils.H.

References Aleph::SpscQueue< T >::head_, and Aleph::SpscQueue< T >::tail_.

Referenced by TEST().

◆ full()

template<typename T >

bool Aleph::SpscQueue< T >::full ( ) const

inlinenoexcept

Check if the queue is full.

Returns: true if the queue currently has no free slots.

Exceptions

Nothing.

Note: Safe to call from either the producer or consumer thread.

Definition at line 1170 of file concurrency_utils.H.

References Aleph::SpscQueue< T >::advance(), Aleph::SpscQueue< T >::head_, and Aleph::SpscQueue< T >::tail_.

Referenced by TEST().

◆ operator=()

template<typename T >

SpscQueue & Aleph::SpscQueue< T >::operator= ( const SpscQueue< T > & )

delete

Deleted copy assignment operator.

◆ size()

template<typename T >

size_t Aleph::SpscQueue< T >::size ( ) const

inlinenoexcept

Return the number of items currently in the queue.

Returns: The current number of queued items.

Exceptions

Nothing.

Note: Safe to call from either the producer or consumer thread.

Definition at line 1181 of file concurrency_utils.H.

References Aleph::SpscQueue< T >::head_, Aleph::SpscQueue< T >::storage_size_, and Aleph::SpscQueue< T >::tail_.

◆ try_pop() [1/2]

template<typename T >

std::optional< T > Aleph::SpscQueue< T >::try_pop ( )

inline

Attempt to pop an item from the queue.

Returns: The next item wrapped in std::optional, or std::nullopt if the queue is empty.

Exceptions

Any	exception thrown while copying or moving the queued value into the returned optional.

Note: Non-blocking and only safe to call from the single consumer thread. If optional construction throws, the slot remains occupied.

Definition at line 1251 of file concurrency_utils.H.

References Aleph::SpscQueue< T >::advance(), Aleph::divide_and_conquer_partition_dp(), Aleph::SpscQueue< T >::head_, Aleph::SpscQueue< T >::slots_, and Aleph::SpscQueue< T >::tail_.

◆ try_pop() [2/2]

template<typename T >

bool Aleph::SpscQueue< T >::try_pop ( T & out )

inline

Attempt to pop an item from the queue into out.

Parameters

out	Reference where the popped item will be moved.

Returns: true if an item was extracted, false if the queue is empty.

Exceptions

Any	exception thrown while copying or moving the queued value into a temporary or assigning into `out`.

Note: Non-blocking and only safe to call from the single consumer thread. If extraction throws, the slot remains occupied.

Definition at line 1230 of file concurrency_utils.H.

References Aleph::SpscQueue< T >::advance(), Aleph::divide_and_conquer_partition_dp(), Aleph::SpscQueue< T >::head_, Aleph::SpscQueue< T >::slots_, and Aleph::SpscQueue< T >::tail_.

Referenced by TEST(), TEST(), and TEST().

◆ try_push() [1/2]

template<typename T >

bool Aleph::SpscQueue< T >::try_push ( const T & value )

inline

Attempt to push an item (copy) into the queue.

Parameters

value The item to push.

Returns: true if the item was enqueued, false if the queue is full.

Exceptions

Any	exception thrown while copying `T` into the ring buffer.

Note: Non-blocking and only safe to call from the single producer thread.

Definition at line 1197 of file concurrency_utils.H.

References Aleph::SpscQueue< T >::emplace_impl().

Referenced by TEST(), TEST(), TEST(), and TEST().

◆ try_push() [2/2]

template<typename T >

bool Aleph::SpscQueue< T >::try_push ( T && value )

inline

Attempt to push an item (move) into the queue.

Parameters

value The item to push.

Returns: true if the item was enqueued, false if the queue is full.

Exceptions

Any	exception thrown while moving `T` into the ring buffer.

Note: Non-blocking and only safe to call from the single producer thread.

Definition at line 1206 of file concurrency_utils.H.

References Aleph::SpscQueue< T >::emplace_impl().

Member Data Documentation

◆ head_

template<typename T >

std::atomic<size_t> Aleph::SpscQueue< T >::head_ {0}

private

Definition at line 1105 of file concurrency_utils.H.

Referenced by Aleph::SpscQueue< T >::emplace_impl(), Aleph::SpscQueue< T >::empty(), Aleph::SpscQueue< T >::full(), Aleph::SpscQueue< T >::size(), Aleph::SpscQueue< T >::try_pop(), and Aleph::SpscQueue< T >::try_pop().

◆ slots_

template<typename T >

std::vector<std::optional<T> > Aleph::SpscQueue< T >::slots_

private

Definition at line 1103 of file concurrency_utils.H.

Referenced by Aleph::SpscQueue< T >::emplace_impl(), Aleph::SpscQueue< T >::try_pop(), and Aleph::SpscQueue< T >::try_pop().

◆ storage_size_

template<typename T >

size_t Aleph::SpscQueue< T >::storage_size_

private

Definition at line 1104 of file concurrency_utils.H.

Referenced by Aleph::SpscQueue< T >::advance(), Aleph::SpscQueue< T >::capacity(), and Aleph::SpscQueue< T >::size().

◆ tail_

template<typename T >

std::atomic<size_t> Aleph::SpscQueue< T >::tail_ {0}

private

Definition at line 1106 of file concurrency_utils.H.

Referenced by Aleph::SpscQueue< T >::emplace_impl(), Aleph::SpscQueue< T >::empty(), Aleph::SpscQueue< T >::full(), Aleph::SpscQueue< T >::size(), Aleph::SpscQueue< T >::try_pop(), and Aleph::SpscQueue< T >::try_pop().

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

concurrency_utils.H

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ SpscQueue() [1/2]

◆ SpscQueue() [2/2]

Member Function Documentation

◆ advance()

◆ capacity()

◆ emplace()

◆ emplace_impl()

◆ empty()

◆ full()

◆ operator=()

◆ size()

◆ try_pop() [1/2]

◆ try_pop() [2/2]

◆ try_push() [1/2]

◆ try_push() [2/2]

Member Data Documentation

◆ head_

◆ slots_

◆ storage_size_

◆ tail_