core_lib::threads::ConcurrentQueue< T > Class Template Reference

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

strongprivate

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 )

inlineprivate

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 )

inlineprivate

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  )

inlineprivate

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