Thread-safe FIFO queue with blocking waits, the workhorse producer/consumer channel in CMSDK. More...

#include <Utils.h>

Inheritance diagram for cmlabs::utils::WaitQueue< T >:

Collaboration diagram for cmlabs::utils::WaitQueue< T >:

Public Member Functions
	WaitQueue ()
virtual	~WaitQueue ()
bool	add (T entry)
	Append an entry and wake one waiting consumer.
uint32	getCount ()
	Number of queued entries.
bool	peekFirst (T &first)
	Copy the front entry without removing it.
bool	takeFirst (T &first)
	Remove and return the front entry.
bool	waitForAndPeekFirst (T &first, uint32 timeoutMS)
	Block up to `timeoutMS` for an entry and peek it without removal.
bool	waitForAndTakeFirst (T &first, uint32 timeoutMS)
	Block up to `timeoutMS` for an entry and dequeue it.
virtual bool	clear ()
	Discard all queued entries.

Protected Attributes
Mutex	mutex
Semaphore	semaphore
std::queue< T >	internalQueue

Detailed Description

template<typename T>
class cmlabs::utils::WaitQueue< T >

Thread-safe FIFO queue with blocking waits, the workhorse producer/consumer channel in CMSDK.

All operations take an internal mutex with a 200 ms timeout and return false rather than deadlock if it cannot be acquired. A semaphore is signalled on every add() so consumers can block in waitForAndTakeFirst()/waitForAndPeekFirst() without polling.

Template Parameters

T	Element type (copied by value). For heap pointers prefer WaitQueuePointer, which deletes leftovers on clear().

Definition at line 703 of file Utils.h.

Constructor & Destructor Documentation

◆ WaitQueue()

template<typename T>

cmlabs::utils::WaitQueue< T >::WaitQueue ( )

inline

Definition at line 705 of file Utils.h.

◆ ~WaitQueue()

template<typename T>

virtual cmlabs::utils::WaitQueue< T >::~WaitQueue ( )

inlinevirtual

Definition at line 706 of file Utils.h.

Member Function Documentation

◆ add()

template<typename T>

bool cmlabs::utils::WaitQueue< T >::add ( T entry )

inline

Append an entry and wake one waiting consumer.

Parameters

entry Value to enqueue.

Returns: true on success.

Definition at line 709 of file Utils.h.

References internalQueue, mutex, and semaphore.

◆ clear()

template<typename T>

virtual bool cmlabs::utils::WaitQueue< T >::clear ( )

inlinevirtual

Discard all queued entries.

Returns: true on success.

Reimplemented in cmlabs::utils::WaitQueuePointer< T >, cmlabs::utils::WaitQueuePointer< cmlabs::DataMessage * >, and cmlabs::utils::WaitQueuePointer< cmlabs::RequestReply * >.

Definition at line 805 of file Utils.h.

References internalQueue, and mutex.

◆ getCount()

template<typename T>

uint32 cmlabs::utils::WaitQueue< T >::getCount ( )

inline

Number of queued entries.

Returns: Count, or 0 when the lock could not be taken.

Definition at line 718 of file Utils.h.

References internalQueue, and mutex.

◆ peekFirst()

template<typename T>

bool cmlabs::utils::WaitQueue< T >::peekFirst ( T & first )

inline

Copy the front entry without removing it.

Parameters

[out] first Receives the front value.

Returns: false when empty.

Definition at line 727 of file Utils.h.

References internalQueue, and mutex.

◆ takeFirst()

template<typename T>

bool cmlabs::utils::WaitQueue< T >::takeFirst ( T & first )

inline

Remove and return the front entry.

Parameters

[out] first Receives the front value.

Returns: false when empty.

Definition at line 739 of file Utils.h.

References internalQueue, and mutex.

◆ waitForAndPeekFirst()

template<typename T>

bool cmlabs::utils::WaitQueue< T >::waitForAndPeekFirst	(	T &	first,
		uint32	timeoutMS )

inline

Block up to timeoutMS for an entry and peek it without removal.

Parameters

[out]	first	Receives the front value.
	timeoutMS	Max wait in ms.

Returns: true when an entry was available.

Definition at line 753 of file Utils.h.

References internalQueue, mutex, and semaphore.

◆ waitForAndTakeFirst()

template<typename T>

bool cmlabs::utils::WaitQueue< T >::waitForAndTakeFirst	(	T &	first,
		uint32	timeoutMS )

inline

Block up to timeoutMS for an entry and dequeue it.

Parameters

[out]	first	Receives the value.
	timeoutMS	Max wait in ms.

Returns: true when an entry was taken.

Note: A race between the semaphore wait and re-lock can rarely yield false even after a signal; callers should loop.

Definition at line 779 of file Utils.h.

References internalQueue, mutex, and semaphore.

Referenced by cmlabs::utils::WaitQueuePointer< T >::waitForAndTakeFirst().

Member Data Documentation

◆ internalQueue

template<typename T>

std::queue<T> cmlabs::utils::WaitQueue< T >::internalQueue

protected

Definition at line 817 of file Utils.h.

Referenced by add(), clear(), cmlabs::utils::WaitQueuePointer< T >::clear(), getCount(), peekFirst(), takeFirst(), waitForAndPeekFirst(), and waitForAndTakeFirst().

◆ mutex

template<typename T>

Mutex cmlabs::utils::WaitQueue< T >::mutex

protected

Definition at line 815 of file Utils.h.

Referenced by add(), clear(), cmlabs::utils::WaitQueuePointer< T >::clear(), getCount(), peekFirst(), takeFirst(), waitForAndPeekFirst(), and waitForAndTakeFirst().

◆ semaphore

template<typename T>

Semaphore cmlabs::utils::WaitQueue< T >::semaphore

protected

Definition at line 816 of file Utils.h.

Referenced by add(), waitForAndPeekFirst(), and waitForAndTakeFirst().

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

/home/ubuntu/c/partner/psyclone2/CMSDK/include/Utils.h

Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ WaitQueue()

◆ ~WaitQueue()

Member Function Documentation

◆ add()

◆ clear()

◆ getCount()

◆ peekFirst()

◆ takeFirst()

◆ waitForAndPeekFirst()

◆ waitForAndTakeFirst()

Member Data Documentation

◆ internalQueue

◆ mutex

◆ semaphore