Thread-safe FIFO queue with optional capacity limit. More...

#include <thread_safe_queue.h>

Public Member Functions
	ThreadSafeQueue (size_t capacity=0)
	Construct a queue with an optional capacity limit.
	ThreadSafeQueue (const ThreadSafeQueue &)=delete
ThreadSafeQueue &	operator= (const ThreadSafeQueue &)=delete
void	abort ()
	Abort the queue and unblock all waiting threads.
bool	aborted () const
	Check whether the queue has been aborted.
bool	push (T value)
	Push an element into the queue, blocking if necessary.
bool	try_push (T value)
	Attempt to push an element into the queue without blocking.
void	wait_for_data ()
	Block until the queue contains at least one element or is aborted.
void	notify_all ()
	Wake all threads currently waiting on the queue.
std::optional< T >	wait_and_pop ()
	Wait for and remove the front element from the queue.
std::optional< T >	try_pop ()
	Attempt to remove and return the front element without blocking.
bool	empty () const
	Check whether the queue is empty.
size_t	size () const
	Get the current number of elements in the queue.
size_t	capacity () const
	Get the maximum number of elements the queue can hold.
void	enqueue (T value)
	Enqueue an element into the queue (blocking if necessary).
bool	try_enqueue (T value)
	Attempt to enqueue an element into the queue without blocking.
template<typename... Args>
bool	emplace (Args &&... args)
	Construct and insert an element into the queue in place.
template<typename... Args>
bool	try_emplace (Args &&... args)
	Attempt to construct and insert an element into the queue without blocking.
std::optional< T >	wait_dequeue ()
	Wait for and dequeue an element from the queue.
bool	try_dequeue (T &out)
	Attempt to dequeue an element without blocking.
std::optional< T >	try_dequeue ()
	Attempt to dequeue an element without blocking.
bool	peek (T &out) const
	Peek at the front element without removing it.
std::optional< T >	peek () const
	Peek at the front element without removing it.
template<typename Predicate>
void	removeIf (Predicate pred)
	Remove all elements that satisfy a given predicate.

Detailed Description

template<typename T>
class mm::core::containers::ThreadSafeQueue< T >

Thread-safe FIFO queue with optional capacity limit.

Compatible with moodycamel::ReaderWriterQueue (refactored so that ThreadSafeQueue is used by default). Multi-producer / multi-consumer safe via a mutex, but all operations are serialized. Use lock-free queues only if very high throughput is needed.

If capacity == 0, the queue is unbounded.

Template Parameters

T	Type of elements stored in the queue.

Constructor & Destructor Documentation

◆ ThreadSafeQueue() [1/2]

template<typename T>

mm::core::containers::ThreadSafeQueue< T >::ThreadSafeQueue ( size_t capacity = 0 )

inlineexplicit

Construct a queue with an optional capacity limit.

◆ ThreadSafeQueue() [2/2]

template<typename T>

mm::core::containers::ThreadSafeQueue< T >::ThreadSafeQueue ( const ThreadSafeQueue< T > & )

delete

Member Function Documentation

◆ abort()

template<typename T>

void mm::core::containers::ThreadSafeQueue< T >::abort ( )

inline

Abort the queue and unblock all waiting threads.

Sets the queue into an aborted (shutdown) state and wakes all threads currently blocked in:

wait_for_data()
wait_and_pop() / wait_dequeue()
push() / emplace() (for bounded queues)

After calling abort():

Blocking operations return immediately.
No new elements can be pushed or emplaced.
Existing queued elements may still be popped ("drain-after-abort").

This function is idempotent and may be called multiple times safely. It does not clear or modify the contents of the queue.

Note: Intended for coordinated shutdown to allow worker threads to exit gracefully without deadlocks.

◆ aborted()

template<typename T>

bool mm::core::containers::ThreadSafeQueue< T >::aborted ( ) const

inline

Check whether the queue has been aborted.

Returns true if abort() has been called on this queue.

Note: An aborted queue may still contain elements. Non-blocking pop operations can still retrieve queued elements ("drain-after-abort" semantics).

Returns: true if the queue is in an aborted (shutdown) state, false otherwise.

◆ capacity()

template<typename T>

size_t mm::core::containers::ThreadSafeQueue< T >::capacity ( ) const

inline

Get the maximum number of elements the queue can hold.

Returns: The maximum number of elements allowed in the queue. Returns 0 if the queue is unbounded.

Note: For bounded queues, pushing or emplacing elements may block or fail if the queue reaches this capacity.

◆ emplace()

template<typename T>

template<typename... Args>

bool mm::core::containers::ThreadSafeQueue< T >::emplace ( Args &&... args )

inline

Construct and insert an element into the queue in place.

This function forwards the given arguments to construct the element directly in the queue, avoiding unnecessary copies or moves.

If the queue is bounded and currently full, this call blocks until space becomes available or the queue is aborted.

After successfully inserting the element, one waiting consumer (if any) is notified.

The operation fails and returns false if the queue has been aborted before insertion.

Template Parameters

Args	Types of arguments to forward to T's constructor.

Parameters

args	Arguments forwarded to construct the element in place.

Returns: true if the element was successfully inserted, false if the queue was aborted before insertion.

Note: This function may block if the queue is bounded and full.

◆ empty()

template<typename T>

bool mm::core::containers::ThreadSafeQueue< T >::empty ( ) const

inline

Check whether the queue is empty.

This function is thread-safe and returns immediately.

Returns: true if the queue contains no elements, false otherwise.

Note: Even if this function returns false, the queue state may change immediately after due to concurrent operations by other threads.

◆ enqueue()

template<typename T>

void mm::core::containers::ThreadSafeQueue< T >::enqueue ( T value )

inline

Enqueue an element into the queue (blocking if necessary).

This is a Moodycamel-compatible alias for push(). If the queue is bounded and full, this call will block until space becomes available or the queue is aborted.

After the element is successfully enqueued, one waiting consumer (if any) is notified.

Parameters

value The element to enqueue. It will be moved into the queue.

Returns: true if the element was successfully inserted, false if the queue was aborted before insertion.

◆ notify_all()

template<typename T>

void mm::core::containers::ThreadSafeQueue< T >::notify_all ( )

inline

Wake all threads currently waiting on the queue.

Notifies all threads blocked on:

wait_for_data() or wait_and_pop() (waiting for the queue to be non-empty)
push() / emplace() (waiting for the queue to become non-full, if bounded)

This function does not modify the contents of the queue. It is typically used during shutdown or coordination to unblock threads.

Note: Calling this function without holding the mutex is safe because the mutex is acquired internally.; Does not affect the aborted state of the queue.

◆ operator=()

template<typename T>

ThreadSafeQueue & mm::core::containers::ThreadSafeQueue< T >::operator= ( const ThreadSafeQueue< T > & )

delete

◆ peek() [1/2]

template<typename T>

std::optional< T > mm::core::containers::ThreadSafeQueue< T >::peek ( ) const

inline

Peek at the front element without removing it.

This function allows you to inspect the front element of the queue without modifying the queue.

The operation returns immediately:

If the queue is empty, it returns std::nullopt.
Otherwise, it returns a copy of the front element.

Returns: An std::optional<T> containing the front element if available, or std::nullopt if the queue is empty.

Note: This function does not block and does not modify the queue.; The returned element is a copy; modifying it does not affect the queue.

◆ peek() [2/2]

template<typename T>

bool mm::core::containers::ThreadSafeQueue< T >::peek ( T & out ) const

inline

Peek at the front element without removing it.

This function allows you to inspect the front element of the queue without modifying the queue.

The operation returns immediately:

If the queue is empty, it returns false.
Otherwise, it copies (or moves if T supports it) the front element into out and returns true.

Parameters

[out] out Reference where the front element will be stored if available.

Returns: true if an element was available, false if the queue is empty.

Note: This function does not block and does not modify the queue.; The element stored in out is a copy (or move) and further modifications to it do not affect the queue.

◆ push()

template<typename T>

bool mm::core::containers::ThreadSafeQueue< T >::push ( T value )

inline

Push an element into the queue, blocking if necessary.

If the queue is bounded and currently full, this call will block until space becomes available or the queue is aborted.

After the element is successfully pushed, one waiting consumer (if any) is notified.

The operation fails and returns false if the queue has been aborted via abort() before insertion.

Parameters

value The value to push into the queue. It will be moved.

Returns: true if the element was successfully inserted, false if the queue was aborted before insertion.

Note: This function may block if the queue is bounded and full.

◆ removeIf()

template<typename T>

template<typename Predicate>

void mm::core::containers::ThreadSafeQueue< T >::removeIf ( Predicate pred )

inline

Remove all elements that satisfy a given predicate.

Iterates over all elements in the queue and removes those for which the predicate returns true. Elements that do not satisfy the predicate are kept in the same order.

Template Parameters

Predicate A callable type that takes a reference to an element of type T and returns bool. Elements for which the predicate returns true are removed.

Parameters

pred	Predicate function used to determine which elements to remove.

Note: The operation is thread-safe and locks the queue during execution.; The relative order of remaining elements is preserved.

Warning: This operation involves moving all elements and may be expensive for large queues.

◆ size()

template<typename T>

size_t mm::core::containers::ThreadSafeQueue< T >::size ( ) const

inline

Get the current number of elements in the queue.

This function is thread-safe and returns immediately.

Returns: The number of elements currently stored in the queue.

Note: The returned size is a snapshot; concurrent operations may change the queue immediately after this call.

◆ try_dequeue() [1/2]

template<typename T>

std::optional< T > mm::core::containers::ThreadSafeQueue< T >::try_dequeue ( )

inline

Attempt to dequeue an element without blocking.

This is a Moodycamel-compatible alias for try_pop(). The operation does not block. If the queue is empty, the function returns immediately with std::nullopt.

After a successful dequeue, one waiting producer (if any) is notified in case the queue is bounded.

Returns: An std::optional<T> containing the front element if available, or std::nullopt if the queue is empty.

Note: This function never blocks.

◆ try_dequeue() [2/2]

template<typename T>

bool mm::core::containers::ThreadSafeQueue< T >::try_dequeue ( T & out )

inline

Attempt to dequeue an element without blocking.

This is a Moodycamel-compatible alias for try_pop(). The operation does not block. If the queue is empty, the function returns immediately with false.

If an element is successfully dequeued, it is stored in out. After removal, one waiting producer (if any) is notified in case the queue is bounded.

Parameters

[out] out Reference where the dequeued element will be stored if available.

Returns: true if an element was successfully dequeued, false if the queue was empty.

Note: This function never blocks.

◆ try_emplace()

template<typename T>

template<typename... Args>

bool mm::core::containers::ThreadSafeQueue< T >::try_emplace ( Args &&... args )

inline

Attempt to construct and insert an element into the queue without blocking.

Constructs the element in place using the provided arguments. The operation does not block under any circumstances.

The operation fails and returns false if:

the queue is bounded and currently full, or
the queue has been aborted via abort().

After successfully inserting the element, one waiting consumer (if any) is notified.

Template Parameters

Args	Types of arguments to forward to T's constructor.

Parameters

args	Arguments forwarded to construct the element in place.

Returns: true if the element was successfully inserted, false if the queue was full or aborted.

Note: This function never blocks.

◆ try_enqueue()

template<typename T>

bool mm::core::containers::ThreadSafeQueue< T >::try_enqueue ( T value )

inline

Attempt to enqueue an element into the queue without blocking.

This is a Moodycamel-compatible alias for try_push(). The operation fails and returns false if:

the queue is bounded and currently full, or
the queue has been aborted via abort().

If the element is successfully enqueued, one waiting consumer (if any) is notified.

Parameters

value The element to enqueue. It will be moved into the queue.

Returns: true if the element was successfully inserted, false if the queue was full or aborted.

Note: This function never blocks.

◆ try_pop()

template<typename T>

std::optional< T > mm::core::containers::ThreadSafeQueue< T >::try_pop ( )

inline

Attempt to remove and return the front element without blocking.

This function checks the queue immediately:

If the queue is empty, it returns std::nullopt.
Otherwise, it removes and returns the front element.

After a successful pop, one waiting producer (if any) is notified in case the queue is bounded.

Returns: An std::optional<T> containing the front element if available, or std::nullopt if the queue is empty.

Note: This function never blocks, even if the queue is empty.; Unlike wait_and_pop(), it does not consider the aborted state.

◆ try_push()

template<typename T>

bool mm::core::containers::ThreadSafeQueue< T >::try_push ( T value )

inline

Attempt to push an element into the queue without blocking.

This function tries to insert the given element immediately. It does not block under any circumstances.

The operation fails and returns false if:

the queue has been aborted via abort(), or
the queue is bounded and currently full.

If the element is successfully inserted, one waiting consumer (if any) is notified.

Parameters

value The value to push into the queue. It will be moved.

Returns: true if the element was successfully inserted, false if the queue was full or aborted.

Note: This function never blocks.

◆ wait_and_pop()

template<typename T>

std::optional< T > mm::core::containers::ThreadSafeQueue< T >::wait_and_pop ( )

inline

Wait for and remove the front element from the queue.

This function blocks until:

the queue contains at least one element, or
the queue has been aborted via abort().

If the queue is aborted and empty, this function returns std::nullopt. Otherwise, it removes and returns the front element. After removal, one waiting producer (if any) is notified in case the queue was bounded.

Returns: An std::optional<T> containing the front element if available, or std::nullopt if the queue was aborted and empty.

Note: This function may block indefinitely if the queue is empty and not aborted. Use abort() to unblock waiting threads.

◆ wait_dequeue()

template<typename T>

std::optional< T > mm::core::containers::ThreadSafeQueue< T >::wait_dequeue ( )

inline

Wait for and dequeue an element from the queue.

This is a Moodycamel-compatible alias for wait_and_pop(). The function blocks until:

the queue contains at least one element, or
the queue has been aborted via abort().

If the queue is aborted and empty, this function returns std::nullopt. Otherwise, it removes and returns the front element. After removal, one waiting producer (if any) is notified in case the queue is bounded.

Returns: An std::optional<T> containing the front element if available, or std::nullopt if the queue was aborted and empty.

Note: This function may block indefinitely if the queue is empty and not aborted. Use abort() to unblock waiting threads.

◆ wait_for_data()

template<typename T>

void mm::core::containers::ThreadSafeQueue< T >::wait_for_data ( )

inline

Block until the queue contains at least one element or is aborted.

This function acquires the internal mutex and waits on the condition variable until either:

the queue is non-empty, or
the queue has been aborted via abort().

After returning, the caller can safely check the queue for available data.

Note: This function may block indefinitely if the queue is empty and not aborted. Use abort() to unblock all waiting threads.

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

libs/core/containers/thread_safe_queue.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ThreadSafeQueue() [1/2]

◆ ThreadSafeQueue() [2/2]

Member Function Documentation

◆ abort()

◆ aborted()

◆ capacity()

◆ emplace()

◆ empty()

◆ enqueue()

◆ notify_all()

◆ operator=()

◆ peek() [1/2]

◆ peek() [2/2]

◆ push()

◆ removeIf()

◆ size()

◆ try_dequeue() [1/2]

◆ try_dequeue() [2/2]

◆ try_emplace()

◆ try_enqueue()

◆ try_pop()

◆ try_push()

◆ wait_and_pop()

◆ wait_dequeue()

◆ wait_for_data()