Queue< T > Class Template Reference

Thread-safe FIFO queue. More...

#include <queue.h>

Public Member Functions
void	push (const T &val)
	Pushes a copy of val onto the back of the queue.
void	push (T &&val)
	Moves val onto the back of the queue.
template<typename... Args>
void	emplace (Args &&... args)
	Constructs an element in-place at the back of the queue.
void	push (const List< T > &list)
	Pushes every element in list onto the back of the queue.
std::pair< T, Error >	pop (unsigned int timeoutMs=0)
	Removes and returns the front element, blocking until one is available or the timeout expires.
bool	popOrFail (T &val)
	Tries to pop the front element without blocking.
std::pair< T, Error >	peek (unsigned int timeoutMs=0)
	Returns a copy of the front element without removing it, blocking until one is available or the timeout expires.
bool	peekOrFail (T &val)
	Tries to copy the front element without blocking or removing it.
Error	waitForEmpty (unsigned int timeoutMs=0)
	Blocks until the queue is empty.
bool	isEmpty () const
	Returns true if the queue has no elements.
size_t	size () const
	Returns the number of elements currently in the queue.
void	clear ()
	Removes all elements from the queue.

Detailed Description

template<typename T>
class Queue< T >

Thread-safe FIFO queue.

All public methods are safe to call concurrently from multiple threads.

Example

Queue<String> q;
q.emplace("first");
q.emplace("second");
String val = q.dequeue();  // "first"
bool empty = q.isEmpty();  // false

Internally synchronized with a Mutex and WaitCondition. Blocking methods (pop(), peek(), waitForEmpty()) will sleep until their condition is met rather than spinning or polling.

Note

waitForEmpty() indicates that all items have been removed from the queue, not that they have been fully processed by the consumer. If you need a "processing complete" guarantee, use an out-of-band mechanism such as a promise/future handshake.

Template Parameters

T	The element type stored in the queue.

Member Function Documentation

emplace()

template<typename T >

template<typename... Args>

void Queue< T >::emplace ( Args &&...  args )

inline

Constructs an element in-place at the back of the queue.

Template Parameters

Args	Constructor argument types.

Parameters

args	Arguments forwarded to the T constructor.

isEmpty()

template<typename T >

bool Queue< T >::isEmpty ( ) const

inline

Returns true if the queue has no elements.

Returns

True if empty.

peek()

template<typename T >

std::pair< T, Error > Queue< T >::peek ( unsigned int  timeoutMs = 0 )

inline

Returns a copy of the front element without removing it, blocking until one is available or the timeout expires.

Parameters

timeoutMs

Maximum time to wait in milliseconds. A value of zero (the default) waits indefinitely.

Returns

A pair of the front element (default-constructed on timeout) and Error::Ok or Error::Timeout.

peekOrFail()

template<typename T >

bool Queue< T >::peekOrFail ( T &  val )

inline

Tries to copy the front element without blocking or removing it.

Parameters

[out]

val

Receives a copy of the front element on success.

Returns

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

pop()

template<typename T >

std::pair< T, Error > Queue< T >::pop ( unsigned int  timeoutMs = 0 )

inline

Removes and returns the front element, blocking until one is available or the timeout expires.

Parameters

timeoutMs

Maximum time to wait in milliseconds. A value of zero (the default) waits indefinitely.

Returns

A pair of the dequeued element (default-constructed on timeout) and Error::Ok or Error::Timeout.

popOrFail()

template<typename T >

bool Queue< T >::popOrFail ( T &  val )

inline

Tries to pop the front element without blocking.

Parameters

[out]

val

Receives the dequeued element on success.

Returns

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

push() [1/3]

template<typename T >

void Queue< T >::push ( const List< T > &  list )

inline

Pushes every element in list onto the back of the queue.

Parameters

list	List of values to enqueue.

push() [2/3]

template<typename T >

void Queue< T >::push ( const T &  val )

inline

Pushes a copy of val onto the back of the queue.

Parameters

val	Value to enqueue.

push() [3/3]

template<typename T >

void Queue< T >::push ( T &&  val )

inline

Moves val onto the back of the queue.

Parameters

val	Rvalue reference to enqueue.

size()

template<typename T >

size_t Queue< T >::size ( ) const

inline

Returns the number of elements currently in the queue.

Returns

Current queue depth.

waitForEmpty()

template<typename T >

Error Queue< T >::waitForEmpty ( unsigned int  timeoutMs = 0 )

inline

Blocks until the queue is empty.

Useful for backpressure: a producer can wait until the consumer has drained the queue before pushing more work. Note that this only guarantees the items have been popped, not that the consumer has finished processing them.

Parameters

timeoutMs

Maximum time to wait in milliseconds. A value of zero (the default) waits indefinitely.

Returns

Error::Ok if the queue drained, Error::Timeout if the timeout elapsed first.

---

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

• include/promeki/core/queue.h