PahoMqttCpp
MQTT C++ Client for POSIX and Windows
Loading...
Searching...
No Matches
mqtt::thread_queue< T, Container > Class Template Reference

#include <thread_queue.h>

Public Types

using container_type = Container
 
using value_type = T
 
using size_type = typename Container::size_type
 

Public Member Functions

 thread_queue ()
 
 thread_queue (size_t cap)
 
bool empty () const
 
size_type capacity () const
 
void capacity (size_type cap)
 
size_type size () const
 
void close ()
 
bool closed () const
 
bool done () const
 
void clear ()
 
void put (value_type val)
 
bool try_put (value_type val)
 
template<typename Rep , class Period >
bool try_put_for (value_type val, const std::chrono::duration< Rep, Period > &relTime)
 
template<class Clock , class Duration >
bool try_put_until (value_type val, const std::chrono::time_point< Clock, Duration > &absTime)
 
bool get (value_type *val)
 
value_type get ()
 
bool try_get (value_type *val)
 
template<typename Rep , class Period >
bool try_get_for (value_type *val, const std::chrono::duration< Rep, Period > &relTime)
 
template<class Clock , class Duration >
bool try_get_until (value_type *val, const std::chrono::time_point< Clock, Duration > &absTime)
 

Static Public Attributes

static constexpr size_type MAX_CAPACITY = std::numeric_limits<size_type>::max()
 

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 locking 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 constructor 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.
The queue can be closed. After that, no new items can be placed into it; a put() calls will fail. Receivers can still continue to get any items out of the queue that were added before it was closed. Once there are no more items left in the queue after it is closed, it is considered "done". Nothing useful can be done with the queue.
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.
Template Parameters
TThe type of the items to be held in the queue.
ContainerThe type of the underlying container to use. It must support back(), front(), push_back(), pop_front().

Member Typedef Documentation

◆ container_type

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.

◆ value_type

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.

◆ size_type

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.

Constructor & Destructor Documentation

◆ thread_queue() [1/2]

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

Constructs a queue with the maximum capacity. This is effectively an unbounded queue.

◆ thread_queue() [2/2]

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. This is a bounded queue.

Parameters
capThe maximum number of items that can be placed in the queue. The minimum capacity is 1.

Member Function Documentation

◆ empty()

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.

◆ capacity() [1/2]

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.

◆ capacity() [2/2]

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

◆ size()

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.

◆ close()

template<typename T , class Container = std::deque<T>>
void mqtt::thread_queue< T, Container >::close ( )
inline

Close the queue. Once closed, the queue will not accept any new items, but receievers will still be able to get any remaining items out of the queue until it is empty.

◆ closed()

template<typename T , class Container = std::deque<T>>
bool mqtt::thread_queue< T, Container >::closed ( ) const
inline

Determines if the queue is closed. Once closed, the queue will not accept any new items, but receievers will still be able to get any remaining items out of the queue until it is empty.

Returns
true if the queue is closed, @false otherwise.

◆ done()

template<typename T , class Container = std::deque<T>>
bool mqtt::thread_queue< T, Container >::done ( ) const
inline

Determines if all possible operations are done on the queue. If the queue is closed and empty, then no further useful operations can be done on it.

Returns
@true if the queue is closed and empty, false otherwise.

◆ clear()

template<typename T , class Container = std::deque<T>>
void mqtt::thread_queue< T, Container >::clear ( )
inline

Clear the contents of the queue. This discards all items in the queue.

◆ put()

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
valThe value to add to the queue.

◆ try_put()

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

◆ try_put_for()

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
valThe value to add to the queue.
relTimeThe amount of time to wait until timing out.
Returns
true if the value was added to the queue, false if a timeout occurred.

◆ try_put_until()

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
valThe value to add to the queue.
absTimeThe absolute time to wait to before timing out.
Returns
true if the value was added to the queue, false if a timeout occurred.

◆ get() [1/2]

template<typename T , class Container = std::deque<T>>
bool 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
valPointer to a variable to receive the value.

◆ get() [2/2]

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

◆ try_get()

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
valPointer to a variable to receive the value.
Returns
true if a value was removed from the queue, false if the queue is empty.

◆ try_get_for()

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 amount of time. This will retrieve the next item from the queue. If the queue is empty, it will wait the specified amount of time for an item to arrive before timing out.

Parameters
valPointer to a variable to receive the value.
relTimeThe amount of time to wait until timing out.
Returns
true if the value was removed the queue, false if a timeout occurred.

◆ try_get_until()

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 amount 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 arrive before timing out.

Parameters
valPointer to a variable to receive the value.
absTimeThe absolute time to wait to before timing out.
Returns
true if the value was removed from the queue, false if a timeout occurred.

Field Documentation

◆ MAX_CAPACITY

template<typename T , class Container = std::deque<T>>
size_type mqtt::thread_queue< T, Container >::MAX_CAPACITY = std::numeric_limits<size_type>::max()
staticconstexpr

The maximum capacity of the queue.


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