MPMC thread-safe wait queue with shutdown semantics. More...

#include <wait_queue.hpp>

Public Types
using	size_type = typename Container::size_type

using	value_type = T

Public Member Functions
	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

Detailed Description

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.

Constructor & Destructor Documentation

◆ wait_queue() [1/6]

template<typename T , typename Container = std::deque<T>>

chops::wait_queue< T, Container >::wait_queue ( )

inline

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>>

chops::wait_queue< T, Container >::wait_queue ( std::stop_token stop_tok )

inline

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>>

chops::wait_queue< T, Container >::wait_queue ( Container && container )

inline

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>>

chops::wait_queue< T, Container >::wait_queue ( size_type sz )

inline

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.

Member Function Documentation

◆ apply()

template<typename T , typename Container = std::deque<T>>

template<typename F >
requires std::is_invocable_v<F, T>

auto chops::wait_queue< T, Container >::apply ( F && func ) const -> void

inline

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: void (const T&); 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...>

auto chops::wait_queue< T, Container >::emplace_push ( Args &&... args ) -> bool

inline

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>>

auto chops::wait_queue< T, Container >::empty ( ) const -> bool

inlinenodiscard

Query whether the wait_queue is empty or not.

Returns: true if the wait_queue is empty.

◆ push() [1/2]

template<typename T , typename Container = std::deque<T>>

auto chops::wait_queue< T, Container >::push ( const T & val ) -> bool

inline

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>>

auto chops::wait_queue< T, Container >::push ( T && val ) -> bool

inline

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>>

auto chops::wait_queue< T, Container >::request_stop ( ) -> bool

inlinenoexcept

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>>

auto chops::wait_queue< T, Container >::size ( ) const -> size_type

inlinenodiscard

Get the number of elements in the wait_queue.

Returns: Number of elements in the wait_queue.

◆ stop_requested()

template<typename T , typename Container = std::deque<T>>

auto chops::wait_queue< T, Container >::stop_requested ( ) const -> bool

inlinenodiscardnoexcept

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>>

auto chops::wait_queue< T, Container >::try_pop ( ) -> std::optional<T>

inlinenodiscard

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>>

auto chops::wait_queue< T, Container >::wait_and_pop ( ) -> std::optional<T>

inlinenodiscard

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:

/github/workspace/include/queue/wait_queue.hpp

Public Types

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ wait_queue() [1/6]

◆ wait_queue() [2/6]

◆ wait_queue() [3/6]

◆ wait_queue() [4/6]

◆ wait_queue() [5/6]

◆ wait_queue() [6/6]

Member Function Documentation

◆ apply()

◆ emplace_push()

◆ empty()

◆ push() [1/2]

◆ push() [2/2]

◆ request_stop()

◆ size()

◆ stop_requested()

◆ try_pop()

◆ wait_and_pop()