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

  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

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

inline explicit

Constructs a queue with the specified capacity. This is a bounded queue.

Parameters

  cap | The 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 of items are removed from the queue.

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

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

  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.

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

  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.

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

  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.

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

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

  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.

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

  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.

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

  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.

## 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()

static constexpr

The maximum capacity of the queue.

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

- thread_queue.h