The concurrent_queue class is a sequence container class that allows first-in, first-out access to its elements. More...

#include <concurrent_queue.h>

Public Types
typedef T	value_type
	A type that represents the data type stored in a concurrent queue.

typedef Alloc	allocator_type
	A type that represents the allocator class for the concurrent queue.

typedef value_type &	reference
	A type that provides a reference to an element stored in a concurrent queue.

typedef std::condition_variable_any	condition_type
	A type that provides a waitable condition of the concurrent queue.

typedef std::allocator_traits< allocator_type >::pointer	pointer
	A type that provides a pointer to an element stored in a concurrent queue.

typedef std::allocator_traits< allocator_type >::const_pointer	const_pointer
	A type that provides a const pointer to an element stored in a concurrent queue.

typedef Queue< T, Alloc >	queue_type
	A type that represents the underlying non-thread-safe data structure for the concurrent queue.

typedef queue_type::iterator	iterator
	A type that represents a non-thread-safe iterator over the elements in a concurrent queue.

typedef queue_type::const_iterator	const_iterator
	A type that represents a non-thread-safe const iterator over elements in a concurrent queue.

typedef std::reverse_iterator< iterator >	reverse_iterator
	A type that represents a reverse non-thread-safe iterator over the elements in a concurrent queue.

typedef std::reverse_iterator< const_iterator >	const_reverse_iterator
	A type that represents a reverse non-thread-safe const iterator over elements in a concurrent queue.

typedef std::shared_timed_mutex	mutex_type
	A type that represents the mutex protecting the concurrent queue.

typedef std::shared_lock< mutex_type >	read_lock_type
	A type representing a lock on the concurrent queue's mutex which is sufficient to read data in a thread-safe manner.

typedef std::unique_lock< mutex_type >	write_lock_type
	A type representing a lock on the concurrent queue's mutex which is sufficient to write data in a thread-safe manner.

typedef std::iterator_traits< iterator >::difference_type	difference_type
	A type that provides the signed distance between two elements in a concurrent queue.

typedef size_t	size_type
	A type that counts the number of elements in a concurrent queue.

Public Member Functions
Constructors
	concurrent_queue ()=default
	Default Constructor. More...

	concurrent_queue (const allocator_type &alloc)
	Default Constructor. More...

	concurrent_queue (size_type n, const allocator_type &alloc=allocator_type())
	Fill Constructor. More...

	concurrent_queue (size_type n, const value_type &val, const allocator_type &alloc=allocator_type())
	Fill Constructor. More...

template<typename InputIterator >
	concurrent_queue (InputIterator first, InputIterator last, const allocator_type &alloc=allocator_type())
	Range Constructor. More...

	concurrent_queue (const concurrent_queue &other)
	Copy Constructor. More...

	concurrent_queue (const concurrent_queue &other, const allocator_type &alloc)
	Copy Constructor with allocator. More...

	concurrent_queue (concurrent_queue &&other) noexcept
	Move Constructor. More...

	concurrent_queue (concurrent_queue &&other, const allocator_type &alloc) noexcept
	Move Constructor. More...

	concurrent_queue (std::initializer_list< T > init, const allocator_type &alloc=allocator_type())
	Initializer List Constructor. More...

Destructor
	~concurrent_queue ()=default
	Destructor. More...

Assignment Operators
concurrent_queue &	operator= (const concurrent_queue &other)
	Copy Assignment Operator. More...

concurrent_queue &	operator= (concurrent_queue &&other) noexcept
	Move Assignment Operator. More...

Thread-safe Public Members
These methods are safe for use in situations where the queue will be concurrently accessed by multiple threads.
void	clear () noexcept
	Clears the concurrent queue, destroying any currently enqueued elements. More...

template<class... Args>
void	emplace (Args &&... args)
	Constructs a new element in place at the end of the concurrent queue. More...

bool	empty () const noexcept
	Tests if the concurrent queue is empty at the moment this method is called. More...

allocator_type	get_allocator () const noexcept
	Returns a copy of the allocator used to construct the concurrent queue. More...

void	push (const T &value)
	Enqueues an item at tail end of the concurrent queue. More...

void	push (T &&value)
	Enqueues an item at tail end of the concurrent queue. More...

size_t	size () const
	Returns the number of items in the queue. More...

bool	try_pop (T &destination)
	Dequeues an item from the queue if one is available. More...

template<class Rep , class Period >
bool	try_pop_for (T &destination, const std::chrono::duration< Rep, Period > &timeout_duration)
	Dequeues an item from the queue if one is available within the specified timeout. More...

Thread-unsafe Public Members
These methods are not recommended for use in production code and will generate warnings when used. That said, they're helpful for testing and debug, which is why they are included.
iterator	begin ()
	Returns an iterator of type iterator to the beginning of the concurrent queue. More...

const_iterator	begin () const
	Returns an iterator of type const_iterator to the beginning of the concurrent queue. More...

const_iterator	cbegin () const
	Returns an iterator of type const_iterator to the beginning of the concurrent queue. More...

iterator	end ()
	Returns an iterator of type iterator to the end of the concurrent queue. More...

const_iterator	end () const
	Returns an iterator of type const_iterator to the end of the concurrent queue. More...

const_iterator	cend () const
	Returns an iterator of type const_iterator to the end of the concurrent queue. More...

Access Control
These methods provide the ability to lock the concurrent_queue for thread-safe iteration. They are primarily intended for test and debug use, and care must be taken when explicitely locking the queue to avoid deadlock. These methods are NOT recommended for production code, and will produce warnings when used.
read_lock_type	acquire_read_lock () const
	Lock the queue in a manner in which it is safe for multiple threads to read-iterate over it. More...

write_lock_type	acquire_write_lock ()
	Lock the queue in a manner in which it is safe for multiple threads to write-iterate over it. More...

Public Attributes
const typedef value_type &	const_reference
	A type that provides a reference to a const element stored in a concurrent queue for reading and performing const operations.

Friends
Equality Operators
template<class Ty , template< class, class > class Q, class A >
bool	operator== (const concurrent_queue< Ty, Q, A > &lhs, const concurrent_queue< Ty, Q, A > &rhs)
	Equality Operator. More...

template<class Ty , template< class, class > class Q, class A >
bool	operator!= (const concurrent_queue< Ty, Q, A > &lhs, const concurrent_queue< Ty, Q, A > &rhs)
	Inequality Operator. More...

Swap Operator
template<class Ty , template< class, class > class Q, class A >
void	std::swap (concurrent_queue< Ty, Q, A > &lhs, concurrent_queue< Ty, Q, A > &rhs)
	Swap Operator. More...

Detailed Description

template<class T, template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>
class concurrent_queue< T, Queue, Alloc >

The concurrent_queue class is a sequence container class that allows first-in, first-out access to its elements.

It enables a limited set of concurrency-safe operations, such as push and try_pop. Here, concurrency-safe means pointers or iterators are always valid. It's not a guarantee of element initialization, or of a particular traversal order.

Template Parameters

T	The data type of the elements to be stored in the queue.
Queue	Underlying concurrent queue data structure. Defaults to `std::deque`.
AllocThe	type that represents the stored allocator object that encapsulates details about the allocation and deallocation of memory for this concurrent queue. This argument is optional and the default value is allocator<T>.

Constructor & Destructor Documentation

◆ concurrent_queue() [1/10]

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

concurrent_queue< T, Queue, Alloc >::concurrent_queue ( )

inlinedefault

Default Constructor.

Constructs an empty container, with no elements.

Parameters

[in] alloc optional memory allocator.

◆ concurrent_queue() [2/10]

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

concurrent_queue< T, Queue, Alloc >::concurrent_queue ( const allocator_type & alloc )

inlineexplicit

Default Constructor.

Constructs an empty container, with no elements.

Parameters

[in] alloc optional memory allocator.

◆ concurrent_queue() [3/10]

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

concurrent_queue< T, Queue, Alloc >::concurrent_queue	(	size_type	n,
		const allocator_type &	alloc = `allocator_type()`
	)

inlineexplicit

Fill Constructor.

Constructs a container with n elements. Each element is a copy of val (if provided).

Parameters

[in]	n	number of elements
[in]	alloc	optional memory allocator.

◆ concurrent_queue() [4/10]

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

concurrent_queue< T, Queue, Alloc >::concurrent_queue	(	size_type	n,
		const value_type &	val,
		const allocator_type &	alloc = `allocator_type()`
	)

inline

Fill Constructor.

Constructs a container with n elements. Each element is a copy of val (if provided).

Parameters

[in]	n	number of elements
[in]	val	value to fill the concurrent queue with
[in]	alloc	optional memory allocator.

◆ concurrent_queue() [5/10]

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

template<typename InputIterator >

concurrent_queue< T, Queue, Alloc >::concurrent_queue	(	InputIterator	first,
		InputIterator	last,
		const allocator_type &	alloc = `allocator_type()`
	)

inline

Range Constructor.

Constructs a container with as many elements as the range [first,last), with each element emplace-constructed from its corresponding element in that range, in the same order.

Template Parameters

InputIterator Input Iterator to value_type

Parameters

[in]	first	Iterator to the first element of the range
[in]	last	Iterator to the one-past-last element of the range

◆ concurrent_queue() [6/10]

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

concurrent_queue< T, Queue, Alloc >::concurrent_queue ( const concurrent_queue< T, Queue, Alloc > & other )

inline

Copy Constructor.

Constructs a container with a copy of each of the elements in x, in the same order. Thread-safe.

Parameters

[in] other queue to copy

◆ concurrent_queue() [7/10]

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

concurrent_queue< T, Queue, Alloc >::concurrent_queue	(	const concurrent_queue< T, Queue, Alloc > &	other,
		const allocator_type &	alloc
	)

inline

Copy Constructor with allocator.

Constructs a container with a copy of each of the elements in x, in the same order. Thread-safe.

Parameters

[in]	other	queue to copy
[in]	alloc	optional memory allocator.

◆ concurrent_queue() [8/10]

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

concurrent_queue< T, Queue, Alloc >::concurrent_queue ( concurrent_queue< T, Queue, Alloc > && other )

inlinenoexcept

Move Constructor.

Constructs a container that acquires the elements of other. Ownership of the contained elements is directly transferred. other is left in an unspecified but valid state.

Parameters

[in] other container to move from

◆ concurrent_queue() [9/10]

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

concurrent_queue< T, Queue, Alloc >::concurrent_queue	(	concurrent_queue< T, Queue, Alloc > &&	other,
		const allocator_type &	alloc
	)

inlinenoexcept

Move Constructor.

Constructs a container that acquires the elements of other. Ownership of the contained elements is directly transferred. other is left in an unspecified but valid state.

Parameters

[in] other container to move from

◆ concurrent_queue() [10/10]

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

concurrent_queue< T, Queue, Alloc >::concurrent_queue	(	std::initializer_list< T >	init,
		const allocator_type &	alloc = `allocator_type()`
	)

inline

Initializer List Constructor.

Parameters

[in]	init	initializer list to initialize the elements of the container with
[in]	alloc	allocator to use for all memory allocations of this container

◆ ~concurrent_queue()

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

concurrent_queue< T, Queue, Alloc >::~concurrent_queue ( )

inlinedefault

Destructor.

Destructs the concurrent queue. The destructors of the elements are called and the used storage is deallocated. Note, that if the elements are pointers, the pointed-to objects are not destroyed.

Member Function Documentation

◆ acquire_read_lock()

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

read_lock_type concurrent_queue< T, Queue, Alloc >::acquire_read_lock ( ) const

inline

Lock the queue in a manner in which it is safe for multiple threads to read-iterate over it.

Allows concurrency-safe iteration.

Remarks: Intended for test and debug use only.

Returns: RAII lock suitable for safe read-iteration. Note that failure to move from or bind to the return value will invoke the locks destructor at the end of the call, instantly unlocking the concurrent queue.

◆ acquire_write_lock()

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

write_lock_type concurrent_queue< T, Queue, Alloc >::acquire_write_lock ( )

inline

Lock the queue in a manner in which it is safe for multiple threads to write-iterate over it.

Allows concurrency-safe iteration.

Remarks: Intended for test and debug use only.

Returns: RAII lock suitable for safe write-iteration. Note that failure to move from or bind to the return value will invoke the locks destructor at the end of the call, instantly unlocking the concurrent queue.

◆ begin() [1/2]

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

iterator concurrent_queue< T, Queue, Alloc >::begin ( )

inline

Returns an iterator of type iterator to the beginning of the concurrent queue.

This method is not concurrency-safe. The iterators for the concurrent_queue class are primarily intended for debugging, as they are slow, and iteration is not concurrency-safe with respect to other queue operations.

Returns: An iterator of type iterator to the beginning of the concurrent queue.

◆ begin() [2/2]

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

const_iterator concurrent_queue< T, Queue, Alloc >::begin ( ) const

inline

Returns an iterator of type const_iterator to the beginning of the concurrent queue.

This method is not concurrency-safe. The iterators for the concurrent_queue class are primarily intended for debugging, as they are slow, and iteration is not concurrency-safe with respect to other queue operations.

Returns: An iterator of type const_iterator to the beginning of the concurrent queue.

◆ cbegin()

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

const_iterator concurrent_queue< T, Queue, Alloc >::cbegin ( ) const

inline

Returns an iterator of type const_iterator to the beginning of the concurrent queue.

This method is not concurrency-safe. The iterators for the concurrent_queue class are primarily intended for debugging, as they are slow, and iteration is not concurrency-safe with respect to other queue operations.

Returns: An iterator of type const_iterator to the beginning of the concurrent queue.

◆ cend()

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

const_iterator concurrent_queue< T, Queue, Alloc >::cend ( ) const

inline

Returns an iterator of type const_iterator to the end of the concurrent queue.

This method is not concurrency-safe. The iterators for the concurrent_queue class are primarily intended for debugging, as they are slow, and iteration is not concurrency-safe with respect to other queue operations.

Returns: An iterator of type const_iterator to the end of the concurrent queue.

◆ clear()

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

void concurrent_queue< T, Queue, Alloc >::clear ( )

inlinenoexcept

Clears the concurrent queue, destroying any currently enqueued elements.

This method is not concurrency-safe, and invalidates all iterators.

◆ emplace()

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

template<class... Args>

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

inline

Constructs a new element in place at the end of the concurrent queue.

This method is concurrency-safe. This method is concurrency-safe with respect to calls to the methods push, emplace, pop, and empty.

Template Parameters

Args	Types of args, generally deduced automatically.

Parameters

[in] args Arguments to forward to the constructor of the element.

◆ empty()

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

bool concurrent_queue< T, Queue, Alloc >::empty ( ) const

inlinenoexcept

Tests if the concurrent queue is empty at the moment this method is called.

This method is concurrency-safe. While this method is concurrency-safe with respect to calls to the methods push, emplace, pop, and empty, the value returned might be incorrect by the time it is inspected by the calling thread.

Returns: true if the concurrent queue was empty at the moment we looked, false otherwise.

◆ end() [1/2]

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

iterator concurrent_queue< T, Queue, Alloc >::end ( )

inline

Returns an iterator of type iterator to the end of the concurrent queue.

This method is not concurrency-safe. The iterators for the concurrent_queue class are primarily intended for debugging, as they are slow, and iteration is not concurrency-safe with respect to other queue operations.

Returns: An iterator of type iterator to the end of the concurrent queue.

◆ end() [2/2]

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

const_iterator concurrent_queue< T, Queue, Alloc >::end ( ) const

inline

Returns an iterator of type const_iterator to the end of the concurrent queue.

This method is not concurrency-safe. The iterators for the concurrent_queue class are primarily intended for debugging, as they are slow, and iteration is not concurrency-safe with respect to other queue operations.

Returns: An iterator of type const_iterator to the end of the concurrent queue.

◆ get_allocator()

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

allocator_type concurrent_queue< T, Queue, Alloc >::get_allocator ( ) const

inlinenoexcept

Returns a copy of the allocator used to construct the concurrent queue.

This method is concurrency-safe.

Returns: A copy of the allocator used to construct the concurrent queue.

◆ operator=() [1/2]

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

concurrent_queue& concurrent_queue< T, Queue, Alloc >::operator= ( concurrent_queue< T, Queue, Alloc > && other )

inlinenoexcept

Move Assignment Operator.

Parameters

[in] other concurrent queue whose elements are to be moved.

Returns: A reference to this concurrent queue.

◆ operator=() [2/2]

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

concurrent_queue& concurrent_queue< T, Queue, Alloc >::operator= ( const concurrent_queue< T, Queue, Alloc > & other )

inline

Copy Assignment Operator.

Parameters

[in] other concurrent queue whose elements are to be copied.

Returns: A reference to this concurrent queue.

◆ push() [1/2]

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

void concurrent_queue< T, Queue, Alloc >::push ( const T & value )

inline

Enqueues an item at tail end of the concurrent queue.

This method is concurrency-safe. push is concurrency-safe with respect to calls to the methods push emplace, pop, and empty.

Parameters

[in] value The item to be added to the queue.

◆ push() [2/2]

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

void concurrent_queue< T, Queue, Alloc >::push ( T && value )

inline

Enqueues an item at tail end of the concurrent queue.

This method is concurrency-safe. push is concurrency-safe with respect to calls to the methods push emplace, pop, and empty.

Parameters

[in] value The item to be added to the queue.

◆ size()

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

size_t concurrent_queue< T, Queue, Alloc >::size ( ) const

inline

Returns the number of items in the queue.

This method is concurrency-safe. push is concurrency-safe with respect to calls to the methods push emplace, try_pop, and empty.

Remarks: While calls to size are concurrency-safe in that they cannot damage the internal state of the concurrent queue, it is unwise to use the results as a condition of a for loop or for iteration, because the size of the container could change between the call to size and the invocation of the loop's methods.

Returns: The size of the concurrent queue.

◆ try_pop()

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

bool concurrent_queue< T, Queue, Alloc >::try_pop ( T & destination )

inline

Dequeues an item from the queue if one is available.

This method is concurrency-safe. If an item was successfully dequeued, the parameter destination receives the dequeued value, the original value held in the queue is destroyed, and this function returns true. If there was no item to dequeue, this function returns false without blocking, and the contents of the destination parameter are undefined. A false return value does not necessarily mean the queue is empty. try_pop is concurrency-safe with respect to calls to the methods emplace, push, try_pop, and empty.

Parameters

[out] destination A reference to a location to store the dequeued item.

Returns: true if an item was successfully dequeued, false otherwise.

◆ try_pop_for()

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

template<class Rep , class Period >

bool concurrent_queue< T, Queue, Alloc >::try_pop_for	(	T &	destination,
		const std::chrono::duration< Rep, Period > &	timeout_duration
	)

inline

Dequeues an item from the queue if one is available within the specified timeout.

This method is concurrency-safe. If an item was successfully dequeued, the parameter destination receives the dequeued value, the original value held in the queue is destroyed, and this function returns true. If there was no item to dequeue, this function returns false without blocking, and the contents of the destination parameter are undefined. A false return value does not necessarily mean the queue is empty. try_pop is concurrency-safe with respect to calls to the methods emplace, push, try_pop, and empty.

Parameters

[out]	destination	A reference to a location to store the dequeued item.
[in]	timeout_duration	The maximum length of time `try_pop_for` will attempt to pop the queue before declaring failure.

Returns: true if an item was successfully dequeued, false otherwise.

Friends And Related Function Documentation

◆ operator!=

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

template<class Ty , template< class, class > class Q, class A >

bool operator!=	(	const concurrent_queue< Ty, Q, A > &	lhs,
		const concurrent_queue< Ty, Q, A > &	rhs
	)

friend

Inequality Operator.

Parameters

rhs	Right-hand side of the comparison

Returns: false if the contents of the queues are equivalent, true otherwise.

◆ operator==

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

template<class Ty , template< class, class > class Q, class A >

bool operator==	(	const concurrent_queue< Ty, Q, A > &	lhs,
		const concurrent_queue< Ty, Q, A > &	rhs
	)

friend

Equality Operator.

Parameters

rhs	Right-hand side of the comparison

Returns: true if the contents of the queues are equivalent, false otherwise.

◆ std::swap

template<class T , template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>

template<class Ty , template< class, class > class Q, class A >

void std::swap	(	concurrent_queue< Ty, Q, A > &	lhs,
		concurrent_queue< Ty, Q, A > &	rhs
	)

friend

Swap Operator.

Parameters

lhs	container to swap with rhs
rhs	container to swap with lhs

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

include/concurrent_queue.h

Public Types

Public Member Functions

Public Attributes

Friends

Detailed Description

template<class T, template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>> class concurrent_queue< T, Queue, Alloc >

Constructor & Destructor Documentation

◆ concurrent_queue() [1/10]

◆ concurrent_queue() [2/10]

◆ concurrent_queue() [3/10]

◆ concurrent_queue() [4/10]

◆ concurrent_queue() [5/10]

◆ concurrent_queue() [6/10]

◆ concurrent_queue() [7/10]

◆ concurrent_queue() [8/10]

◆ concurrent_queue() [9/10]

◆ concurrent_queue() [10/10]

◆ ~concurrent_queue()

Member Function Documentation

◆ acquire_read_lock()

◆ acquire_write_lock()

◆ begin() [1/2]

◆ begin() [2/2]

◆ cbegin()

◆ cend()

◆ clear()

◆ emplace()

◆ empty()

◆ end() [1/2]

◆ end() [2/2]

◆ get_allocator()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ push() [1/2]

◆ push() [2/2]

◆ size()

◆ try_pop()

◆ try_pop_for()

Friends And Related Function Documentation

◆ operator!=

◆ operator==

◆ std::swap

template<class T, template< class, class > class Queue = std::deque, class Alloc = std::allocator<T>>
class concurrent_queue< T, Queue, Alloc >