A thread-safe queue. More...

#include <mvIMPACT_acquire_helper.h>

Public Types
enum	TQueueResult { qrNoError = 0 , qrFull , qrLocked }
	Defines valid queue result values. More...

Public Member Functions
void	clear (void)
	Clears the queue. Discards all data.

bool	front (T *pData=nullptr) const
	Gets a copy of the oldest element from the queue.

std::queue< T >::size_type	getCurrentSize (void) const
	Returns the current number of elements stored by this queue.

std::queue< T >::size_type	getMaxSize (void) const
	Returns the maximum number of elements this queue can store.

bool	isFull (void) const
	Checks if this queue is currently full.

bool	lock (void)
	Locks the queue.

ThreadSafeQueue &	operator= (const ThreadSafeQueue &rhs)=delete
	assignment operator (deleted)

template<class Rep , class Period >
bool	pop (const std::chrono::duration< Rep, Period > &rel_time, T *pData=nullptr)
	Removes the oldest element from the queue, effectively reducing its size by one.

bool	pop (T *pData=nullptr)
	Removes the oldest element from the queue, effectively reducing its size by one.

bool	pop (unsigned int timeout_ms, T *pData=nullptr)
	Removes the oldest element from the queue, effectively reducing its size by one.

TQueueResult	push (const T &t)
	Adds a new copy of an element to the queue.

void	terminateWait (void)
	Terminates a single wait operation currently pending from another thread without delivering data.

	ThreadSafeQueue (const ThreadSafeQueue &src)=delete
	Copy-constructor (deleted)

	ThreadSafeQueue (typename std::queue< T >::size_type queueSizeMax=std::numeric_limits< typename std::queue< T >::size_type >::max())
	Creates a new mvIMPACT::acquire::helper::ThreadSafeQueue instance.

bool	unlock (void)
	Unlocks the queue.

Detailed Description

template<class T>
class mvIMPACT::acquire::helper::ThreadSafeQueue< T >

A thread-safe queue.

This class provides a thread-safe queue implementation with all the operations typically needed within a multi-threaded environment.

Note: This class requires a C++11 compliant compiler!

Since: 2.33.0

Member Enumeration Documentation

◆ TQueueResult

template<class T >

enum TQueueResult

Defines valid queue result values.

These enumeration defines valid values that might be returned from some of the queue operations defined by the surrounding mvIMPACT::acquire::helper::ThreadSafeQueue class.

Enumerator
qrNoError	The operation on the queue returned successfully.
qrFull	The operation on the queue could not be executed as the queue is currently full thus contains the maximum number of allowed elements.
qrLocked	The operation on the queue could not be executed as the queue is currently locked.

Constructor & Destructor Documentation

◆ ThreadSafeQueue() [1/2]

template<class T >

ThreadSafeQueue ( typename std::queue< T >::size_type queueSizeMax = std::numeric_limits<typename std::queue<T>::size_type>::max() )

inlineexplicit

Creates a new mvIMPACT::acquire::helper::ThreadSafeQueue instance.

Parameters

[in] queueSizeMax The maximum number of elements this queue shall be allowed to store until another push operation will fail.

◆ ThreadSafeQueue() [2/2]

template<class T >

ThreadSafeQueue ( const ThreadSafeQueue< T > & src )

delete

Copy-constructor (deleted)

Objects of this type shall not be copy-constructed!

Member Function Documentation

◆ clear()

template<class T >

void clear ( void )

inline

Clears the queue. Discards all data.

◆ front()

template<class T >

bool front ( T * pData = nullptr ) const

inline

Gets a copy of the oldest element from the queue.

Gets a copy of the oldest element in the queue and the same element that is popped out from the queue when mvIMPACT::acquire::helper::ThreadSafeQueue::pop is called.

See also: mvIMPACT::acquire::helper::ThreadSafeQueue::pop,
mvIMPACT::acquire::helper::ThreadSafeQueue::push

Returns

true if the queue contains at least one element
false if the queue is empty

Parameters

[in,out] pData A pointer to the storage location that shall receive a copy of the oldest element currently stored in the queue. Can be nullptr if a caller just wants to check if there is at least one element stored be the queue right now.

◆ getCurrentSize()

template<class T >

std::queue< T >::size_type getCurrentSize ( void ) const

inline

Returns the current number of elements stored by this queue.

See also: mvIMPACT::acquire::helper::ThreadSafeQueue::getMaxSize

Returns: The current number of elements stored by this queue.

◆ getMaxSize()

template<class T >

std::queue< T >::size_type getMaxSize ( void ) const

inline

Returns the maximum number of elements this queue can store.

When trying to push more elements into the queue than returned by this function the next mvIMPACT::acquire::helper::ThreadSafeQueue::push call will fail until at least one element has been extracted before. The maximum number of elements a queue can store can be specified when constructing the queue.

See also: mvIMPACT::acquire::helper::ThreadSafeQueue::clear
mvIMPACT::acquire::helper::ThreadSafeQueue::getCurrentSize
mvIMPACT::acquire::helper::ThreadSafeQueue::pop

Returns: The maximum number of elements this queue can store.

◆ isFull()

template<class T >

bool isFull ( void ) const

inline

Checks if this queue is currently full.

See also: mvIMPACT::acquire::helper::ThreadSafeQueue::getMaxSize

Returns

true if the queue is currently full
false otherwise

◆ lock()

template<class T >

bool lock ( void )

inline

Locks the queue.

While a queue is locked subsequent calls to mvIMPACT::acquire::helper::ThreadSafeQueue::push will fail and will return mvIMPACT::acquire::helper::ThreadSafeQueue::qrLocked.

See also: mvIMPACT::acquire::helper::ThreadSafeQueue::getMaxSize,
mvIMPACT::acquire::helper::ThreadSafeQueue::push

Returns

true if the queue was locked already
false otherwise

◆ operator=()

template<class T >

ThreadSafeQueue & operator= ( const ThreadSafeQueue< T > & rhs )

delete

assignment operator (deleted)

Objects of this type shall not be assigned!

◆ pop() [1/3]

template<class T >

template<class Rep , class Period >

bool pop	(	const std::chrono::duration< Rep, Period > &	rel_time,
		T *	pData = nullptr )

inline

Removes the oldest element from the queue, effectively reducing its size by one.

See also: mvIMPACT::acquire::helper::ThreadSafeQueue::front,
mvIMPACT::acquire::helper::ThreadSafeQueue::push

Returns

true if the queue did contain at least one element
false if the queue was empty

Parameters

[in]	rel_time	The maximum time to wait for incoming data if the queue currently does not contain any data to pick up.
[in,out]	pData	A pointer to the storage location that shall receive a copy of the oldest element currently stored in the queue. Can be nullptr if a caller just wants to remove an element from the queue but is not actually interested in it.

◆ pop() [2/3]

template<class T >

bool pop ( T * pData = nullptr )

inline

Removes the oldest element from the queue, effectively reducing its size by one.

See also: mvIMPACT::acquire::helper::ThreadSafeQueue::front,
mvIMPACT::acquire::helper::ThreadSafeQueue::push

Returns

true if the queue did contain at least one element
false if the queue was empty

Parameters

[in,out] pData A pointer to the storage location that shall receive a copy of the oldest element currently stored in the queue. Can be nullptr if a caller just wants to remove an element from the queue but is not actually interested in it.

◆ pop() [3/3]

template<class T >

bool pop	(	unsigned int	timeout_ms,
		T *	pData = nullptr )

inline

Removes the oldest element from the queue, effectively reducing its size by one.

See also: mvIMPACT::acquire::helper::ThreadSafeQueue::front,
mvIMPACT::acquire::helper::ThreadSafeQueue::push

Returns

true if the queue did contain at least one element
false if the queue was empty

Parameters

[in]	timeout_ms	The maximum time (in mill-seconds) to wait for incoming data if the queue currently does not contain any data to pick up.
[in,out]	pData	A pointer to the storage location that shall receive a copy of the oldest element currently stored in the queue. Can be nullptr if a caller just wants to remove an element from the queue but is not actually interested in it.

◆ push()

template<class T >

TQueueResult push ( const T & t )

inline

Adds a new copy of an element to the queue.

See also: mvIMPACT::acquire::helper::ThreadSafeQueue::front,
mvIMPACT::acquire::helper::ThreadSafeQueue::pop

Returns

mvIMPACT::acquire::helper::ThreadSafeQueue::qrFull if the queue contains the maximum number of elements already. The new element will NOT be added then
mvIMPACT::acquire::helper::ThreadSafeQueue::qrLocked if the queue is currently in a locked state. The new element will NOT be added then
mvIMPACT::acquire::helper::ThreadSafeQueue::qrNoError otherwise

Parameters

[in] t A const reference to the element to store in the queue. The object must be copy-constructible as this operation will create a copy of the object.

◆ terminateWait()

template<class T >

void terminateWait ( void )

inline

Terminates a single wait operation currently pending from another thread without delivering data.

If one or multiple thread(s) are currently executing a mvIMPACT::acquire::helper::ThreadSafeQueue::pop operation ONE of these threads will get signaled and the call will return.

See also: mvIMPACT::acquire::helper::ThreadSafeQueue::pop

◆ unlock()

template<class T >

bool unlock ( void )

inline

Unlocks the queue.

While a queue is locked subsequent calls to mvIMPACT::acquire::helper::ThreadSafeQueue::push will fail and will return mvIMPACT::acquire::helper::ThreadSafeQueue::qrLocked.

See also: mvIMPACT::acquire::helper::ThreadSafeQueue::getMaxSize,
mvIMPACT::acquire::helper::ThreadSafeQueue::push

Returns

true if the queue was unlocked already
false otherwise

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ TQueueResult

Constructor & Destructor Documentation

◆ ThreadSafeQueue() [1/2]

◆ ThreadSafeQueue() [2/2]

Member Function Documentation

◆ clear()

◆ front()

◆ getCurrentSize()

◆ getMaxSize()

◆ isFull()

◆ lock()

◆ operator=()

◆ pop() [1/3]

◆ pop() [2/3]

◆ pop() [3/3]

◆ push()

◆ terminateWait()

◆ unlock()