mqtt::thread_queue< T, Container > Class Template Reference

A thread-safe queue for inter-thread communication. More...

#include <thread_queue.h>

Public Types
using	container_type = Container
	The underlying container type to use for the queue. More...
using	value_type = T
	The type of items to be held in the queue. More...
using	size_type = typename Container::size_type
	The type used to specify number of items in the container. More...

Public Member Functions
	thread_queue ()
	Constructs a queue with the maximum capacity.
	thread_queue (size_t cap)
	Constructs a queue with the specified capacity. More...
bool	empty () const
	Determine if the queue is empty. More...
size_type	capacity () const
	Gets the capacity of the queue. More...
void	capacity (size_type cap)
	Sets the capacity of the queue. More...
size_type	size () const
	Gets the number of items in the queue. More...
void	put (value_type val)
	Put an item into the queue. More...
bool	try_put (value_type val)
	Non-blocking attempt to place an item into the queue. More...
template<typename Rep , class Period >
bool	try_put_for (value_type *val, const std::chrono::duration< Rep, Period > &relTime)
	Attempt to place an item in the queue with a bounded wait. More...
template<class Clock , class Duration >
bool	try_put_until (value_type *val, const std::chrono::time_point< Clock, Duration > &absTime)
	Attempt to place an item in the queue with a bounded wait to an absolute time point. More...
void	get (value_type *val)
	Retrieve a value from the queue. More...
value_type	get ()
	Retrieve a value from the queue. More...
bool	try_get (value_type *val)
	Attempts to remove a value from the queue without blocking. More...
template<typename Rep , class Period >
bool	try_get_for (value_type *val, const std::chrono::duration< Rep, Period > &relTime)
	Attempt to remove an item from the queue for a bounded amout of time. More...
template<class Clock , class Duration >
bool	try_get_until (value_type *val, const std::chrono::time_point< Clock, Duration > &absTime)
	Attempt to remove an item from the queue for a bounded amout of time. More...

Static Public Attributes
static constexpr size_type	MAX_CAPACITY = std::numeric_limits<size_type>::max()
	The maximum capacity of the queue. More...

Detailed Description

template<typename T, class Container = std::deque<T>>
class mqtt::thread_queue< T, Container >

A thread-safe queue for inter-thread communication.

This is a lockinq queue with blocking operations. The get() operations can always block on an empty queue, but have variations for non-blocking (try_get) and bounded-time blocking (try_get_for, try_get_until).

The default queue has a capacity that is unbounded in the practical sense, limited by available memory. In this mode the object will not block when placing values into the queue. A capacity can bet set with the construtor or, at any time later by calling the capacity(size_type) method. Using this latter method, the capacity can be set to an amount smaller than the current size of the queue. In that case all put's to the queue will block until the number of items are removed from the queue to bring the size below the new capacity.

Note that the queue uses move semantics to place items into the queue and remove items from the queue. This means that the type, T, of the data held by the queue only needs to follow move semantics; not copy semantics. In addition, this means that copies of the value will not be left in the queue. This is especially useful when creating queues of shared pointers, as the "dead" part of the queue will not hold onto a reference count after the item has been removed from the queue.

Parameters

T	The type of the items to be held in the queue.
Container	The type of the underlying container to use. It must support back(), front(), push_back(), pop_front().

Member Typedef Documentation

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

using mqtt::thread_queue< T, Container >::container_type = Container

The underlying container type to use for the queue.

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

using mqtt::thread_queue< T, Container >::size_type = typename Container::size_type

The type used to specify number of items in the container.

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

using mqtt::thread_queue< T, Container >::value_type = T

The type of items to be held in the queue.

Constructor & Destructor Documentation

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

mqtt::thread_queue< T, Container >::thread_queue ( size_t  cap )

inlineexplicit

Constructs a queue with the specified capacity.

Parameters

cap	The maximum number of items that can be placed in the queue.

Member Function Documentation

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

size_type mqtt::thread_queue< T, Container >::capacity ( ) const

inline

Gets the capacity of the queue.

Returns

The maximum number of elements before the queue is full.

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

void mqtt::thread_queue< T, Container >::capacity ( size_type  cap )

inline

Sets the capacity of the queue.

Note that the capacity can be set to a value smaller than the current size of the queue. In that event, all calls to put() will block until a suffucuent number

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

bool mqtt::thread_queue< T, Container >::empty ( ) const

inline

Determine if the queue is empty.

Returns

true if there are no elements in the queue, false if there are any items in the queue.

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

void mqtt::thread_queue< T, Container >::get ( value_type *  val )

inline

Retrieve a value from the queue.

If the queue is empty, this will block indefinitely until a value is added to the queue by another thread,

Parameters

val	Pointer to a variable to receive the value.

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

value_type mqtt::thread_queue< T, Container >::get ( )

inline

Retrieve a value from the queue.

If the queue is empty, this will block indefinitely until a value is added to the queue by another thread,

Returns

The value removed from the queue

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

void mqtt::thread_queue< T, Container >::put ( value_type  val )

inline

Put an item into the queue.

If the queue is full, this will block the caller until items are removed bringing the size less than the capacity.

Parameters

val	The value to add to the queue.

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

size_type mqtt::thread_queue< T, Container >::size ( ) const

inline

Gets the number of items in the queue.

Returns

The number of items in the queue.

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

bool mqtt::thread_queue< T, Container >::try_get ( value_type *  val )

inline

Attempts to remove a value from the queue without blocking.

If the queue is currently empty, this will return immediately with a failure, otherwise it will get the next value and return it.

Parameters

val	Pointer to a variable to receive the value.

Returns

true if a value was removed from the queue, false if the queue is empty.

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

template<typename Rep , class Period >

bool mqtt::thread_queue< T, Container >::try_get_for ( value_type *  val, const std::chrono::duration< Rep, Period > &  relTime  )

inline

Attempt to remove an item from the queue for a bounded amout of time.

This will retrieve the next item from the queue. If the queue is empty, it will wait the specified amout of time for an item to arive before timing out.

Parameters

val	Pointer to a variable to receive the value.
relTime	The amount of time to wait until timing out.

Returns

true if the value was removed the queue, false if a timeout occurred.

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

template<class Clock , class Duration >

bool mqtt::thread_queue< T, Container >::try_get_until ( value_type *  val, const std::chrono::time_point< Clock, Duration > &  absTime  )

inline

Attempt to remove an item from the queue for a bounded amout of time.

This will retrieve the next item from the queue. If the queue is empty, it will wait until the specified time for an item to arive before timing out.

Parameters

val	Pointer to a variable to receive the value.
absTime	The absolute time to wait to before timing out.

Returns

true if the value was removed from the queue, false if a timeout occurred.

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

bool mqtt::thread_queue< T, Container >::try_put ( value_type  val )

inline

Non-blocking attempt to place an item into the queue.

Parameters

val	The value to add to the queue.

Returns

true if the item was added to the queue, false if the item was not added because the queue is currently full.

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

template<typename Rep , class Period >

bool mqtt::thread_queue< T, Container >::try_put_for ( value_type *  val, const std::chrono::duration< Rep, Period > &  relTime  )

inline

Attempt to place an item in the queue with a bounded wait.

This will attempt to place the value in the queue, but if it is full, it will wait up to the specified time duration before timing out.

Parameters

val	The value to add to the queue.
relTime	The amount of time to wait until timing out.

Returns

true if the value was added to the queue, false if a timeout occurred.

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

template<class Clock , class Duration >

bool mqtt::thread_queue< T, Container >::try_put_until ( value_type *  val, const std::chrono::time_point< Clock, Duration > &  absTime  )

inline

Attempt to place an item in the queue with a bounded wait to an absolute time point.

This will attempt to place the value in the queue, but if it is full, it will wait up until the specified time before timing out.

Parameters

val	The value to add to the queue.
absTime	The absolute time to wait to before timing out.

Returns

true if the value was added to the queue, false if a timeout occurred.

Member Data Documentation

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

constexpr size_type mqtt::thread_queue< T, Container >::MAX_CAPACITY = std::numeric_limits<size_type>::max()

static

The maximum capacity of the queue.

---

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

• src/mqtt/thread_queue.h