Getting Started

You may want to consult the tutorial.

Queues supported

basic_unbounded_queue

template<typename Container>
struct basic_unbounded_queue;

template<typename T, typename Allocator = std::allocator<T>>
using unbounded_queue = basic_unbounded_queue<std::vector<T, Allocator>>;

basic_unbounded_queue is the simplest queue: it does not have the concept of being full. It allows the user to continue to add elements until the underlying container is unable to allocate any more space.

basic_blocking_queue

template<typename Container>
struct basic_blocking_queue;

template<typename T, typename Allocator = std::allocator<T>>
using blocking_queue = basic_blocking_queue<std::vector<T, Allocator>>;

basic_blocking_queue accepts a size parameter in its constructor. If the queue already has at least max_size elements when the user attempts to add data (by calling append, emplace, or push), that call will block until the queue is reduced in size to have fewer than max_size elements.

Reference

Template Parameters

Parameter	Definition
Container	The underlying container that the queue uses to store its data. The requirements and exception guarantees for any operation on the queue exactly match the documented call to the underlying container, except where noted otherwise. `Container` must be DefaultConstructible

Member Types

Type	Definition
container_type	`Container` template parameter
value_type	`container_type::value_type`

General Behavior

Except where noted otherwise, all operations are thread-safe.

Some definitions refer to "container" as though it were a data member. This value is for exposition only, and can be assumed to be a value of type container_type that contains all current values in the queue.

The behavior of any function which accepts a time_point or duration parameter is undefined if any operations on the time_point or duration calls any member functions of the queue object.

Special Member Functions

Function	Definition
constructor	`basic_unbounded_queue` is default constructible. This constructs an empty queue. `basic_blocking_queue` is constructible from `container_type::size_type`. This constructs an empty queue and sets the `max_size` to that value.
move constructor	Moves the contents of the queue and the `max_size` (if present) from the old queue to the new queue. Not thread safe, as the assumption is that the source of the move is a temporary. Only defined if `container_type` is MoveConstructible
copy constructor	Deleted
move assignment	Deleted
copy assignment	Deleted
destructor	Destroys the underlying container. The behavior is undefined if any threads are accessing the queue when the destructor is called.

append

`auto append(Iterator first, Sentinel last)`

Definition

Adds elements to the underlying container by calling container.insert(container.end(), first, last).

This should be preferred over emplace or push where possible, as it typically leads to better performance.

Returns void.

Elements added to the queue by this operation are guaranteed to be added atomically. No other elements will be added in the middle, and if a consumer pops everything off the queue, they will either see all of the elements in the range or none of them.

Requirements

container.insert(container.end(), first, last) must be a valid expression that adds all elements in the range [first, last) to the end of the container. The behavior is undefined if calling container.insert(container.end(), first, last) would call any member functions on this queue object.

emplace

`auto emplace(Args && ... args)`

Definition

Adds an element to the underlying container by calling container.emplace_back(std::forward<Args>(args)...). Returns void.

Requirements

container.emplace_back(std::forward<Args>(args)...) must be a valid expression that adds a single item into the container. For std::vector as the container_type, this requires that value_type is MoveInsertable and EmplaceConstructible. The behavior is undefined if calling container.emplace_back(std::forward<Args>(args)...) would call any member functions on this queue object.

push

`auto push(value_type && value)`

Equivalent to emplace(std::move(value))

`auto push(value_type const & value)`

Equivalent to emplace(value)

pop_all

`container_type pop_all(container_type storage = container_type{})`

Definition

Blocks until there is data in the queue. Returns all messages in the queue. After this call, the queue's internal container is equal to the original value of storage. This overload will never return an empty container.