MPMC thread-safe wait queue with shutdown semantics.
More...
#include <wait_queue.hpp>
|
|
using | size_type = typename Container::size_type |
| |
|
using | value_type = T |
| |
|
| | wait_queue () |
| | Default construct a wait_queue.
|
| |
| | wait_queue (std::stop_token stop_tok) |
| | Construct a wait_queue with an externally provided std::stop_token.
|
| |
| | wait_queue (Container &&container) |
| | Construct a wait_queue by moving in an already constructed container.
|
| |
| | wait_queue (std::stop_token stop_tok, Container &&container) |
| |
| | wait_queue (size_type sz) |
| | Construct a wait_queue with an initial size or capacity.
|
| |
| | wait_queue (std::stop_token stop_tok, size_type sz) |
| | Construct a wait_queue with an initial size or capacity along with a std::stop_token.
|
| |
|
| wait_queue (const wait_queue &)=delete |
| |
|
| wait_queue (wait_queue &&)=delete |
| |
|
wait_queue & | operator= (const wait_queue &)=delete |
| |
|
wait_queue & | operator= (wait_queue &&)=delete |
| |
| auto | request_stop () noexcept -> bool |
| | Request the wait_queue to stop processing, unless a std::stop_token was passed in to a constructor.
|
| |
| auto | push (const T &val) -> bool |
| | Push a value, by copying, to the wait_queue.
|
| |
| auto | push (T &&val) -> bool |
| | Push a value, either by moving or copying, to the wait_queue.
|
| |
template<typename ... Args>
requires supports_emplace_back<Container, Args...> |
| auto | emplace_push (Args &&... args) -> bool |
| | Directly construct an object in the underlying container (using the container's emplace_back method) by forwarding the supplied arguments (can be more than one).
|
| |
| auto | wait_and_pop () -> std::optional< T > |
| | Pop and return a value from the wait_queue, blocking and waiting for a writer thread to push a value if one is not immediately available.
|
| |
| auto | try_pop () -> std::optional< T > |
| | Pop and return a value from the wait_queue if an element is immediately available, otherwise return an empty std::optional.
|
| |
template<typename F >
requires std::is_invocable_v<F, T> |
| auto | apply (F &&func) const -> void |
| | Apply a non-modifying function object to all elements of the queue.
|
| |
| auto | stop_requested () const noexcept -> bool |
| |
| auto | empty () const -> bool |
| |
| auto | size () const -> size_type |
| |
template<typename T, typename Container = std::deque<T>>
requires std::is_copy_constructible_v<T> || std::is_move_constructible_v<T>
class chops::wait_queue< T, Container >
MPMC thread-safe wait queue with shutdown semantics.
- Template Parameters
-
| T | Type of value that will be passed through the queue. |
| Container | Type of container that is used as the underlying data queue. |
- Precondition
- The value type must be either copy constructible or move constructible. It does not have to be both, and in particular a default constructor is not required.
-
The container type must support certain operations depending on which ones are called. The constraints are specified on each particular operation.
◆ wait_queue() [1/6]
template<typename T , typename Container = std::deque<T>>
Default construct a wait_queue.
An internal stop_source is used to provide a std::stop_token for coordinating shutdown.
- Note
- A default constructed
boost circular_buffer cannot do anything, so a different wait_queue constructor must be used if instantiated with a boost circular_buffer.
- Postcondition
empty returns true. -
size returns 0.
-
stop_requested returns false.
◆ wait_queue() [2/6]
template<typename T , typename Container = std::deque<T>>
Construct a wait_queue with an externally provided std::stop_token.
- Parameters
-
| stop_tok | A std::stop_token which can be used to shutdown wait_queue processing. |
- Postcondition
empty returns true. -
size returns 0.
◆ wait_queue() [3/6]
template<typename T , typename Container = std::deque<T>>
Construct a wait_queue by moving in an already constructed container.
This constructor allows a container view to be used for the wait_queue container. Typically a container view is initialized with an underlying object, for example a statically allocated array. This allows wait_queue to be used where dynamic memory is not allowed.
This constructor also allows arbitrary initialization of the data inside the container before it is managed by the wait_queue.
An internal std::stop_source is used to provide a std::stop_token for coordinating shutdown.
- Parameters
-
| container | Container object to be moved from (or copied from if not movable). |
- Postcondition
empty and size match moved (or copied) in container.
◆ wait_queue() [4/6]
template<typename T , typename Container = std::deque<T>>
| chops::wait_queue< T, Container >::wait_queue |
( |
std::stop_token |
stop_tok, |
|
|
Container && |
container |
|
) |
| |
|
inline |
This constructor allows a container view to be used for the wait_queue container. It also takes a std::stop_token for external shutdown.
- Parameters
-
| stop_tok | A std::stop_token which can be used to shutdown wait_queue processing. |
| container | Container object to be moved from (or copied from if not movable). |
- Postcondition
empty and size match moved (or copied) in container.
◆ wait_queue() [5/6]
template<typename T , typename Container = std::deque<T>>
Construct a wait_queue with an initial size or capacity.
Construct the container (or container view) with an initial size of default inserted elements or with an initial capacity, depending on the container type.
An internal std::stop_source is used to provide a std::stop_token for coordinating shutdown.
- Note
- This constructor cannot be used with a
ring_span container type.
-
Using this constructor with a
boost circular_buffer creates a container with the specified capacity, but an initial empty size.
-
Using this constructor with most standard library container types creates a container initialized with default inserted elements.
- Parameters
-
| sz | Capacity or initial size, depending on container type. |
- Postcondition
- If
sz is 0 empty returns true, else behavior depends on container used.
-
size returns 0 or sz depending on container used.
◆ wait_queue() [6/6]
template<typename T , typename Container = std::deque<T>>
| chops::wait_queue< T, Container >::wait_queue |
( |
std::stop_token |
stop_tok, |
|
|
size_type |
sz |
|
) |
| |
|
inline |
Construct a wait_queue with an initial size or capacity along with a std::stop_token.
- Parameters
-
| stop_tok | A std::stop_token which can be used to shutdown wait_queue processing. |
| sz | Capacity or initial size, depending on container type. |
- Postcondition
- If
sz is 0 empty returns true, else behavior depends on container used.
-
size returns 0 or sz depending on container used.
◆ apply()
template<typename T , typename Container = std::deque<T>>
template<typename F >
requires std::is_invocable_v<F, T>
Apply a non-modifying function object to all elements of the queue.
The function object is not allowed to modify any of the elements. The supplied function object is passed a const reference to the element type.
This method can be used when an iteration of the elements is needed, such as to print the elements, or copy them to another container, or to interrogate values of the elements.
- Parameters
-
| func | Function object to be invoked on each element. The function object should have the signature: where T is the type of element in the queue. |
- Note
- The entire
wait_queue is locked while apply is in process, so passing in a function object that blocks or takes a lot of processing time may result in slow performance.
-
It is undefined behavior if the function object calls into the same
wait_queue since it results in recursive mutex locks.
◆ emplace_push()
template<typename T , typename Container = std::deque<T>>
template<typename ... Args>
requires supports_emplace_back<Container, Args...>
Directly construct an object in the underlying container (using the container's emplace_back method) by forwarding the supplied arguments (can be more than one).
- Parameters
-
| args | Arguments to be used in constructing an element at the end of the queue. |
- Note
- The
std containers return a reference to the newly constructed element from emplace method calls. emplace_push for a wait_queue does not follow this convention and instead has the same return as the push methods.
- Returns
true if successful, false if the wait_queue is has been requested to stop.
- Postcondition
- If
true is returned and empty is false, one of any threads waiting for a value will be unblocked.
◆ empty()
template<typename T , typename Container = std::deque<T>>
◆ push() [1/2]
template<typename T , typename Container = std::deque<T>>
Push a value, by copying, to the wait_queue.
When a value is pushed, one waiting reader thread (if any) will be notified that a value has been added.
- Parameters
-
| val | Val to copy into the queue. |
- Returns
true if successful, false if the wait_queue has been requested to stop.
- Postcondition
- If
true is returned and empty is false, one of any threads waiting for a value will be unblocked.
◆ push() [2/2]
template<typename T , typename Container = std::deque<T>>
Push a value, either by moving or copying, to the wait_queue.
This method has the same semantics as the other push, except that the value will be moved (if possible) instead of copied.
- Postcondition
- If
true is returned and empty is false, one of any threads waiting for a value will be unblocked.
◆ request_stop()
template<typename T , typename Container = std::deque<T>>
Request the wait_queue to stop processing, unless a std::stop_token was passed in to a constructor.
If a std::stop_token was passed into a constructor, a request_stop must be performed external to the wait_queue and this method has no effect.
For an internal std::stop_token, all waiting reader threaders will be notified. Subsequent push operations will return false.
- Returns
true if an internal stop_source was used (versus a std::stop_token passed in to the constructor) and the request returns true, false if an external std::stop_token was passed in.
◆ size()
template<typename T , typename Container = std::deque<T>>
◆ stop_requested()
template<typename T , typename Container = std::deque<T>>
Query whether a @ request_stop method has been called on the wait_queue.
- Returns
true if the stop_requested has been called.
◆ try_pop()
template<typename T , typename Container = std::deque<T>>
Pop and return a value from the wait_queue if an element is immediately available, otherwise return an empty std::optional.
- Returns
- A value from the
wait_queue or an empty std::optional if no values are available in the wait_queue or if the wait_queue has been requested to be stopped .
- Postcondition
- If a non empty value is returned, until a push function is called,
size is one less than before this function was called.
◆ wait_and_pop()
template<typename T , typename Container = std::deque<T>>
Pop and return a value from the wait_queue, blocking and waiting for a writer thread to push a value if one is not immediately available.
If this method is called after a wait_queue has been requested to stop, an empty std::optional is returned. If a wait_queue needs to be flushed after it is stopped, try_pop should be called instead.
- Returns
- A value from the
wait_queue (if non-empty). If the std::optional is empty, the wait_queue has been requested to be stopped.
- Postcondition
- If a non empty value is returned, until a push function is called,
size is one less than before this function was called.
The documentation for this class was generated from the following file:
