dfx::Utils::SpscFixedQueue< T, Capacity > Class Template Reference

A high-performance, lock-free, Single-Producer Single-Consumer (SPSC) bounded queue. More...

#include <dfx-utilities/sync-queues/SpscFixedQueue.hpp>

Public Types
using	container_type = std::array<std::byte, (Capacity + 1) * sizeof(T)>
using	value_type = T
using	size_type = typename container_type::size_type
using	reference = value_type &
using	const_reference = value_type const &

Public Member Functions
	SpscFixedQueue ()
	Default constructor.
	~SpscFixedQueue ()
	Destructor.
	DFX_DISABLE_COPY_AND_MOVE (SpscFixedQueue)
bool	empty () const noexcept
	Checks if the queue contains no elements.
bool	full () const noexcept
	Checks if the queue has reached its fixed capacity.
size_type	size () const noexcept
	Returns the approximate number of elements currently in the queue.
constexpr size_type	capacity () const noexcept
	Returns the maximum capacity of the queue.
template<typename U> requires std::is_same_v<std::decay_t<U>, T>
bool	tryPush (U &&value)
	Attempts to push an element into the queue.
std::optional< T >	tryPop ()
	Attempts to pop an element from the queue.

Detailed Description

template<typename T, std::size_t Capacity>
class dfx::Utils::SpscFixedQueue< T, Capacity >

A high-performance, lock-free, Single-Producer Single-Consumer (SPSC) bounded queue.

This queue is designed for low-latency message passing between two threads. It uses a fixed-size buffer allocated at compile-time to avoid dynamic memory allocation during operations.

Template Parameters

T	The type of elements stored in the queue.
Capacity	The maximum number of elements the queue can hold.

Thread Safety

This class is thread-safe ONLY for a Single-Producer and a Single-Consumer:

• One thread may safely call tryPush().
• One thread may safely call tryPop(), empty(), full(), and size().

Performance

• Operations are lock-free and wait-free.
• Internal structures are aligned to 64 bytes (or whatever the destructive interference size is) to prevent false sharing between producer and consumer threads.
• Uses C++ placement new and manual lifetime management to avoid default-constructing elements in the internal buffer.

Constructor & Destructor Documentation

SpscFixedQueue()

template<typename T, std::size_t Capacity>

dfx::Utils::SpscFixedQueue< T, Capacity >::SpscFixedQueue ( )

inline

Default constructor.

~SpscFixedQueue()

template<typename T, std::size_t Capacity>

dfx::Utils::SpscFixedQueue< T, Capacity >::~SpscFixedQueue ( )

inline

Destructor.

Member Function Documentation

capacity()

template<typename T, std::size_t Capacity>

size_type dfx::Utils::SpscFixedQueue< T, Capacity >::capacity ( ) const

inlinenodiscardconstexprnoexcept

Returns the maximum capacity of the queue.

empty()

template<typename T, std::size_t Capacity>

bool dfx::Utils::SpscFixedQueue< T, Capacity >::empty ( ) const

inlinenodiscardnoexcept

Checks if the queue contains no elements.

full()

template<typename T, std::size_t Capacity>

bool dfx::Utils::SpscFixedQueue< T, Capacity >::full ( ) const

inlinenodiscardnoexcept

Checks if the queue has reached its fixed capacity.

size()

template<typename T, std::size_t Capacity>

SpscFixedQueue< T, Capacity >::size_type dfx::Utils::SpscFixedQueue< T, Capacity >::size ( ) const

inlinenodiscardnoexcept

Returns the approximate number of elements currently in the queue.

Note

In a multi-threaded context, this value is a snapshot and may change immediately after the call.

Returns

The current number of elements.

tryPop()

template<typename T, std::size_t Capacity>

std::optional< T > dfx::Utils::SpscFixedQueue< T, Capacity >::tryPop ( )

inline

Attempts to pop an element from the queue.

If the queue is empty, returns std::nullopt. Otherwise, moves the oldest element out of the queue and returns it.

Returns

An std::optional containing the popped element, or std::nullopt if empty.

tryPush()

template<typename T, std::size_t Capacity>
requires std::is_same_v<std::decay_t<U>, T>

template<typename U>
requires std::is_same_v<std::decay_t<U>, T>

bool dfx::Utils::SpscFixedQueue< T, Capacity >::tryPush ( U && value )

inline

Attempts to push an element into the queue.

If the queue is full, the function returns false immediately and ownership of value remains with the caller.

Template Parameters

U	The type (either lvalue or rvalue) of the item to push

Parameters

value

The element to move into the queue.

Returns

true if the element was successfully pushed; false if the queue was full.

---

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

• lib/dfx-utilities/sync-queues/SpscFixedQueue.hpp