Core Library 1.7.0.0 Library containing core utilities and tools for threading, networking, logging, INI and CSV file management etc.

Public Types | Public Member Functions | Private Types | Private Member Functions | Private Attributes | List of all members
core_lib::threads::ConcurrentQueue< T > Class Template Referencefinal

Class defining a concurrent queue. More...

`#include <ConcurrentQueue.h>`

## Public Types
using | container_type = std::deque< T >
| Typedef for container type.

## Public Member Functions
| ConcurrentQueue ()=default
| Default constructor.
| ConcurrentQueue (const ConcurrentQueue &)=delete
| Copy constructor deleted.
ConcurrentQueue & | operator= (const ConcurrentQueue &)=delete
| Copy assignment operator deleted.
| ConcurrentQueue (ConcurrentQueue &&)=delete
| Move constructor deleted.
ConcurrentQueue & | operator= (ConcurrentQueue &&)=delete
| Move assignment operator deleted.
| ~ConcurrentQueue ()=default
| Destructor. More...
size_t | Size () const
| Size of the queue. More...
bool | Empty () const
| Is the queue empty. More...
void | Push (T &&item)
| Push an item onto the queue. More...
void | Push (const T &item)
| Push an item onto the queue. More...
void | BreakPopWait ()
| Break out of waiting on a Pop method. More...
bool | Pop (T &item)
| Pop an item off the queue if there are any else wait. More...
void | PopThrow (T &item)
| Pop an item off the queue if there are any else wait. More...
bool | TryPop (T &item)
| Pop an item off the queue if there are any else return. More...
void | TryPopThrow (T &item)
| Pop an item off the queue. More...
bool | TimedPop (unsigned int timeoutMilliseconds, T &item)
| Pop an item off the queue but only wait for a given amount of time. More...
void | TimedPopThrow (unsigned int timeoutMilliseconds, T &item)
| Pop an item off the queue but only wait for a given amount of time. More...
bool | TrySteal (T &item)
| Steal an item from the back of the queue if there are any else return. More...
void | TryStealThrow (T &item)
| Steal an item from the back of the queue. More...
const T * | Peek (size_t index) const
| Take a peek at an item at a given index on the queue. More...
void | Clear ()
| Clear the queue. More...
template<typename F >
void | Clear (F deleter)
| Clear the queue. More...
container_type | TakeAll ()
| Take all items from the queue and return them, thus clearing down the internal queue. More...

## Private Types
enum | eQueueEnd { eQueueEnd::front, eQueueEnd::back }
| Enumeration controlling end of queue to pop from. More...

## Private Member Functions
bool | PopNow (T &item, eQueueEnd whichEnd=eQueueEnd::front)
| Pop an item off the queue. More...
void | PopFront (T &item)
| Pop an item off the front of the queue. More...
void | PopBack (T &item)
| Pop an item off the back of the queue. More...

## Private Attributes
std::mutex | m_mutex
| Synchronization mutex.
SyncEvent | m_itemEvent
| Synchronization event. More...
container_type | m_queue {}
| Underlying deque container acting as the queue.

## Detailed Description

### template<typename T>
class core_lib::threads::ConcurrentQueue< T >

Class defining a concurrent queue.

This class implements a fully thread-safe queue that can be used with single/multiple producer thread(s) and single/multiple consumer thread(s).

It is up to the caller to make sure individual queue items get deallocated correctly. Preferably by using RAII objects as queue items or wrapping underlying data in std::shared_ptr (using a custom deallocator if necessary - see example custom deleters: SingleItemDeleter and ArrayDeleter).

The template T must be a copyable and movable type.

## Member Enumeration Documentation

## ◆ eQueueEnd

template<typename T>

enum core_lib::threads::ConcurrentQueue::eQueueEnd
| strong private

Enumeration controlling end of queue to pop from.

Enumerator
front | Pop front of the queue.
back | Pop back of the queue.

## Constructor & Destructor Documentation

## ◆ ~ConcurrentQueue()

template<typename T>

core_lib::threads::ConcurrentQueue< T >::~ConcurrentQueue | ( |  | ) |
| default

Destructor.

If the queue items aren't RAII-like objects and so don't manager their own memory then make sure you call the second Clear method, defined later, that takes a deleter functor to tidy up the memory of each queue item.

## Member Function Documentation

## ◆ BreakPopWait()

template<typename T>

void core_lib::threads::ConcurrentQueue< T >::BreakPopWait | ( |  | ) |
| inline

Break out of waiting on a Pop method.

Useful to force consumer(s) to break out of wait on Pop etc.

## ◆ Clear() [1/2]

template<typename T>

void core_lib::threads::ConcurrentQueue< T >::Clear | ( |  | ) |
| inline

Clear the queue.

If this method is called while a thread is blocking on the item event then due to interleving of calls and mutex lock timings this may cause the list to be cleared before a waiting pop function has had a chance to pop anything from the queue. This is safe but what it means is the pop function will not find anything to pop and will either throw or return false to indicate that nothing was popped off the queue.

## ◆ Clear() [2/2]

template<typename T>
template<typename F >

void core_lib::threads::ConcurrentQueue< T >::Clear | ( | F | deleter | ) |
| inline

Clear the queue.

Parameters

  [in] | deleter | - If queue items are not RAII objects that will tidy up after themselves then you can pass in a suitable deleter to delete each queue item.

It is also expected that the queue items are raw pointers.

If this method is called while a thread is blocking on the item event then due to interleving of calls and mutex lock timings this may cause the list to be cleared before a waiting pop function has had a chance to pop anything from the queue. This is safe but what it means is the pop function will not find anything to pop and will either throw or return false to indicate that nothing was popped off the queue.

## ◆ Empty()

template<typename T>

bool core_lib::threads::ConcurrentQueue< T >::Empty | ( |  | ) | const
| inline

Is the queue empty.

Returns
  True if empty, false otherwise.

## ◆ Peek()

template<typename T>

const T* core_lib::threads::ConcurrentQueue< T >::Peek | ( | size_t | index | ) | const
| inline

Take a peek at an item at a given index on the queue.

Parameters

  [in] | index | - Zero-based index of the queue item to peek at.

Returns
  Const pointer to item on queue being peeked at.

This method returns a nullptr if the index does not exist in the queue. The use of this method can be dangerous if there are multiple consumers. or if there is a single consumer but the method is called from a different thread to the consumer.

## ◆ Pop()

template<typename T>

bool core_lib::threads::ConcurrentQueue< T >::Pop | ( | T & | item | ) |
| inline

Pop an item off the queue if there are any else wait.

Parameters

  [out] | item | - The popped item, only valid if returns true.

Returns
  True if item popped off queue, false otherwise.

Method will block forever or until an item is placed on the queue.

## ◆ PopBack()

template<typename T>

void core_lib::threads::ConcurrentQueue< T >::PopBack | ( | T & | item | ) |
| inline private

Pop an item off the back of the queue.

Parameters

  [out] | item | - Item popped off back.

## ◆ PopFront()

template<typename T>

void core_lib::threads::ConcurrentQueue< T >::PopFront | ( | T & | item | ) |
| inline private

Pop an item off the front of the queue.

Parameters

  [out] | item | - Item popped off front.

## ◆ PopNow()

template<typename T>

bool core_lib::threads::ConcurrentQueue< T >::PopNow | ( | T & | item,
|  | eQueueEnd | whichEnd = `eQueueEnd::front`
| ) |  |
| inline private

Pop an item off the queue.

Parameters

  [out] | item | - Item popped off queue.
  [out] | whichEnd | - WHich end of queue tp pop from.

Returns
  True if not empty, false if queue empty.

## ◆ PopThrow()

template<typename T>

void core_lib::threads::ConcurrentQueue< T >::PopThrow | ( | T & | item | ) |
| inline

Pop an item off the queue if there are any else wait.

Parameters

  [out] | item | - The popped item, only valid if returns true.

Method will block forever or until an item is placed on the queue.

This will throw std::runtime_error if there are no items on the queue when called.

## ◆ Push() [1/2]

template<typename T>

void core_lib::threads::ConcurrentQueue< T >::Push | ( | T && | item | ) |
| inline

Push an item onto the queue.

Parameters

  [in] | item | - Object of type T to push onto queue.

The arg item must be moveable either implicitly or by passing it to Push wrapped in a std::move() and item will be invalid once this function returns due to being moved onto the internal queue.

It is preferred to use this version when performance matters as move semantics are enforced.

## ◆ Push() [2/2]

template<typename T>

void core_lib::threads::ConcurrentQueue< T >::Push | ( | const T & | item | ) |
| inline

Push an item onto the queue.

Parameters

  [in] | item | - Object of type T to push onto queue.

Use this version only when you want to push a copy of the item arg onto the innternal queue because maybe you want to use item afterwards.

This option is not as efficient as the first version of Push because move semantics are not enforced.

## ◆ Size()

template<typename T>

size_t core_lib::threads::ConcurrentQueue< T >::Size | ( |  | ) | const
| inline

Size of the queue.

Returns
  The number of items on the queue.

## ◆ TakeAll()

template<typename T>

container_type core_lib::threads::ConcurrentQueue< T >::TakeAll | ( |  | ) |
| inline

Take all items from the queue and return them, thus clearing down the internal queue.

If this method is called while a thread is blocking on the item event then due to interleving of calls and mutex lock timings this may cause the list to be cleared before a waiting pop function has had a chance to pop anything from the queue. This is safe but what it means is the pop function will not find anything to pop and will either throw or return false to indicate that nothing was popped off the queue.

## ◆ TimedPop()

template<typename T>

bool core_lib::threads::ConcurrentQueue< T >::TimedPop | ( | unsigned int | timeoutMilliseconds,
|  | T & | item
| ) |  |
| inline

Pop an item off the queue but only wait for a given amount of time.

Parameters

  [in] | timeoutMilliseconds | - Amount of time to wait.
  [out] | item | - The popped item, only valid if returns true.

Returns
  True if item popped successfully, false if timed out.

## ◆ TimedPopThrow()

template<typename T>

void core_lib::threads::ConcurrentQueue< T >::TimedPopThrow | ( | unsigned int | timeoutMilliseconds,
|  | T & | item
| ) |  |
| inline

Pop an item off the queue but only wait for a given amount of time.

Parameters

  [in] | timeoutMilliseconds | - Amount of time to wait.
  [out] | item | - The popped item.

If no items have been put onto the queue after the specified amount to time then a std::runtime_error exception is throw.

## ◆ TryPop()

template<typename T>

bool core_lib::threads::ConcurrentQueue< T >::TryPop | ( | T & | item | ) |
| inline

Pop an item off the queue if there are any else return.

Parameters

  [out] | item | - The popped item, only valid if returns true.

Returns
  True if item popped off queue, false otherwise.

## ◆ TryPopThrow()

template<typename T>

void core_lib::threads::ConcurrentQueue< T >::TryPopThrow | ( | T & | item | ) |
| inline

Pop an item off the queue.

Parameters

  [out] | item | - The popped item.

This will throw std::runtime_error if there are no items on the queue when called.

## ◆ TrySteal()

template<typename T>

bool core_lib::threads::ConcurrentQueue< T >::TrySteal | ( | T & | item | ) |
| inline

Steal an item from the back of the queue if there are any else return.

Parameters

  [out] | item | - The stolen item, only valid if returns true.

Returns
  True if item stolen off queue, false otherwise.

## ◆ TryStealThrow()

template<typename T>

void core_lib::threads::ConcurrentQueue< T >::TryStealThrow | ( | T & | item | ) |
| inline

Steal an item from the back of the queue.

Parameters

  [out] | item | - The stolen item.

This will throw std::runtime_error if there are no items on the queue when called.

## Member Data Documentation

## ◆ m_itemEvent

template<typename T>

SyncEvent core_lib::threads::ConcurrentQueue< T >::m_itemEvent
| private

Initial value:
{
eNotifyType::signalOneThread, eResetCondition::manualReset, eIntialCondition::notSignalled}

Synchronization event.

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

- D:/Projects/CoreLibrary/Include/Threads/ConcurrentQueue.h