concurrent_queue Class
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.
Syntax
template<typename T, class _Ax>
class concurrent_queue: public ::Concurrency::details::_Concurrent_queue_base_v4;
Parameters
T
The data type of the elements to be stored in the queue.
_Ax
The 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>.
Members
Public Typedefs
| Name | Description |
|---|---|
allocator_type |
A type that represents the allocator class for the concurrent queue. |
const_iterator |
A type that represents a non-thread-safe const iterator over elements in a concurrent queue. |
const_reference |
A type that provides a reference to a const element stored in a concurrent queue for reading and performing const operations. |
difference_type |
A type that provides the signed distance between two elements in a concurrent queue. |
iterator |
A type that represents a non-thread-safe iterator over the elements in a concurrent queue. |
reference |
A type that provides a reference to an element stored in a concurrent queue. |
size_type |
A type that counts the number of elements in a concurrent queue. |
value_type |
A type that represents the data type stored in a concurrent queue. |
Public Constructors
| Name | Description |
|---|---|
| concurrent_queue | Overloaded. Constructs a concurrent queue. |
| ~concurrent_queue Destructor | Destroys the concurrent queue. |
Public Methods
| Name | Description |
|---|---|
| clear | Clears the concurrent queue, destroying any currently enqueued elements. This method is not concurrency-safe. |
| empty | Tests if the concurrent queue is empty at the moment this method is called. This method is concurrency-safe. |
| get_allocator | Returns a copy of the allocator used to construct the concurrent queue. This method is concurrency-safe. |
| push | Overloaded. Enqueues an item at tail end of the concurrent queue. This method is concurrency-safe. |
| try_pop | Dequeues an item from the queue if one is available. This method is concurrency-safe. |
| unsafe_begin | Overloaded. Returns an iterator of type iterator or const_iterator to the beginning of the concurrent queue. This method is not concurrency-safe. |
| unsafe_end | Overloaded. Returns an iterator of type iterator or const_iterator to the end of the concurrent queue. This method is not concurrency-safe. |
| unsafe_size | Returns the number of items in the queue. This method is not concurrency-safe. |
Remarks
For more information, see Parallel Containers and Objects.
Inheritance Hierarchy
concurrent_queue
Requirements
Header: concurrent_queue.h
Namespace: concurrency
clear
Clears the concurrent queue, destroying any currently enqueued elements. This method is not concurrency-safe.
void clear();
concurrent_queue
Constructs a concurrent queue.
explicit concurrent_queue(
const allocator_type& _Al = allocator_type());
concurrent_queue(
const concurrent_queue& _OtherQ,
const allocator_type& _Al = allocator_type());
concurrent_queue(
concurrent_queue&& _OtherQ,
const allocator_type& _Al = allocator_type());
template<typename _InputIterator>
concurrent_queue(_InputIterator _Begin,
_InputIterator _End);
Parameters
_InputIterator
The type of the input iterator that specifies a range of values.
_Al
The allocator class to use with this object.
_OtherQ
The source concurrent_queue object to copy or move elements from.
_Begin
Position of the first element in the range of elements to be copied.
_End
Position of the first element beyond the range of elements to be copied.
Remarks
All constructors store an allocator object _Al and initialize the queue.
The first constructor specifies an empty initial queue and explicitly specifies the allocator type to be used.
The second constructor specifies a copy of the concurrent queue _OtherQ.
The third constructor specifies a move of the concurrent queue _OtherQ.
The fourth constructor specifies values supplied by the iterator range [ _Begin, _End).
~concurrent_queue
Destroys the concurrent queue.
~concurrent_queue();
empty
Tests if the concurrent queue is empty at the moment this method is called. This method is concurrency-safe.
bool empty() const;
Return Value
true if the concurrent queue was empty at the moment we looked, false otherwise.
Remarks
While this method is concurrency-safe with respect to calls to the methods push, try_pop, and empty, the value returned might be incorrect by the time it is inspected by the calling thread.
get_allocator
Returns a copy of the allocator used to construct the concurrent queue. This method is concurrency-safe.
allocator_type get_allocator() const;
Return Value
A copy of the allocator used to construct the concurrent queue.
push
Enqueues an item at tail end of the concurrent queue. This method is concurrency-safe.
void push(const T& _Src);
void push(T&& _Src);
Parameters
_Src
The item to be added to the queue.
Remarks
push is concurrency-safe with respect to calls to the methods push, try_pop, and empty.
try_pop
Dequeues an item from the queue if one is available. This method is concurrency-safe.
bool try_pop(T& _Dest);
Parameters
_Dest
A reference to a location to store the dequeued item.
Return Value
true if an item was successfully dequeued, false otherwise.
Remarks
If an item was successfully dequeued, the parameter _Dest 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 _Dest parameter are undefined.
try_pop is concurrency-safe with respect to calls to the methods push, try_pop, and empty.
unsafe_begin
Returns an iterator of type iterator or const_iterator to the beginning of the concurrent queue. This method is not concurrency-safe.
iterator unsafe_begin();
const_iterator unsafe_begin() const;
Return Value
An iterator of type iterator or const_iterator to the beginning of the concurrent queue object.
Remarks
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.
unsafe_end
Returns an iterator of type iterator or const_iterator to the end of the concurrent queue. This method is not concurrency-safe.
iterator unsafe_end();
const_iterator unsafe_end() const;
Return Value
An iterator of type iterator or const_iterator to the end of the concurrent queue.
Remarks
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.
unsafe_size
Returns the number of items in the queue. This method is not concurrency-safe.
size_type unsafe_size() const;
Return Value
The size of the concurrent queue.
Remarks
unsafe_size is not concurrency-safe and can produce incorrect results if called concurrently with calls to the methods push, try_pop, and empty.
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for