Template message queue for inter-thread communication with priority. More...

#include <tsMessagePriorityQueue.h>

Inheritance diagram for ts::MessagePriorityQueue< MSG, COMPARE >:

Collaboration diagram for ts::MessagePriorityQueue< MSG, COMPARE >:

Public Types
using	MessagePtr = std::shared_ptr< MSG >
	Safe pointer to messages.

Public Member Functions
	MessagePriorityQueue (size_t maxMessages=0)
	Constructor.

void	clear ()
	Clear the content of the queue.

void	dequeue (MessagePtr &msg)
	Remove a message from the queue.

bool	dequeue (MessagePtr &msg, cn::milliseconds timeout)
	Remove a message from the queue.

void	enqueue (MessagePtr &msg)
	Insert a message in the queue.

bool	enqueue (MessagePtr &msg, cn::milliseconds timeout)
	Insert a message in the queue.

void	enqueue (MSG *msg)
	Insert a message in the queue.

bool	enqueue (MSG *msg, cn::milliseconds timeout)
	Insert a message in the queue.

void	forceEnqueue (MessagePtr &msg)
	Insert a message in the queue, even if the queue is full.

void	forceEnqueue (MSG *msg)
	Insert a message in the queue, even if the queue is full.

size_t	getMaxMessages () const
	Get the maximum allowed messages in the queue.

MessagePtr	peek ()
	Peek the next message from the queue, without dequeueing it.

void	setMaxMessages (size_t maxMessages)
	Change the maximum allowed messages in the queue.

Protected Types
using	MessageList = std::list< MessagePtr >
	Queues are implemented as list of smart pointers to messages.

using	SuperClass = MessageQueue< MSG >
	Explicit reference to superclass.

Protected Member Functions
virtual MessageList::iterator	dequeuePlacement (MessageList &list)
	This virtual protected method performs dequeue location in the message queue.

virtual MessageList::iterator	enqueuePlacement (const MessagePtr &msg, MessageList &list)
	This virtual protected method performs placement in the message queue.

virtual SuperClass::MessageList::iterator	enqueuePlacement (const typename SuperClass::MessagePtr &msg, typename SuperClass::MessageList &list) override
	This virtual protected method performs placement in the message queue.

Detailed Description

template<typename MSG, class COMPARE = std::less<MSG>>
class ts::MessagePriorityQueue< MSG, COMPARE >

Template message queue for inter-thread communication with priority.

The ts::MessagePriorityQueue template class implements a synchronized access to a shared queue of generic messages. Each message has a priority. Messages with higher priority are deqeued first. Messages with equal priority are dequeued in their enqueueing order.

Template Parameters

MSG	The type of the messages to exchange.
COMPARE	A function object to sort MSG instances. By default, the '<' operator on MSG is used.

Member Typedef Documentation

◆ MessagePtr

template<typename MSG >

using ts::MessageQueue< MSG >::MessagePtr = std::shared_ptr<MSG>

inherited

Safe pointer to messages.

Since data are copied from the producer thread into the queue and later copied again from the queue into the consumer thread, the copied data is always a shared pointer to the actual message content.

Constructor & Destructor Documentation

◆ MessagePriorityQueue()

template<typename MSG , class COMPARE = std::less<MSG>>

ts::MessagePriorityQueue< MSG, COMPARE >::MessagePriorityQueue ( size_t maxMessages = 0 )

inline

Constructor.

Parameters

[in] maxMessages Maximum number of messages in the queue. When a thread attempts to enqueue a message and the queue is full, the thread waits until at least one message is dequeued. If maxMessages is 0, the queue is unlimited. In that case, the logic of the application must ensure that the queue is bounded somehow, otherwise the queue may exhaust all the process memory.

Member Function Documentation

◆ enqueuePlacement() [1/2]

template<typename MSG , class COMPARE >

ts::MessagePriorityQueue< MSG, COMPARE >::SuperClass::MessageList::iterator ts::MessagePriorityQueue< MSG, COMPARE >::enqueuePlacement	(	const typename SuperClass::MessagePtr &	msg,
		typename SuperClass::MessageList &	list
	)

overrideprotectedvirtual

This virtual protected method performs placement in the message queue.

Parameters

[in]	msg	The message to enqueue.
[in]	list	The content of the queue.

Returns: An iterator to the place where msg shall be placed.

◆ getMaxMessages()

template<typename MSG >

size_t ts::MessageQueue< MSG >::getMaxMessages ( ) const

inherited

Get the maximum allowed messages in the queue.

Returns: The maximum allowed messages in the queue (0 means unlimited).

◆ setMaxMessages()

template<typename MSG >

void ts::MessageQueue< MSG >::setMaxMessages ( size_t maxMessages )

inherited

Change the maximum allowed messages in the queue.

Parameters

[in] maxMessages Maximum number of messages in the queue. When a thread attempts to enqueue a message and the queue is full, the thread waits until at least one message is dequeued. If maxMessages is 0, the queue is unlimited. In that case, the logic of the application must ensure that the queue is bounded somehow, otherwise the queue may exhaust all the process memory.

◆ enqueue() [1/4]

template<typename MSG >

void ts::MessageQueue< MSG >::enqueue ( MessagePtr & msg )

inherited

Insert a message in the queue.

If the queue is full, the calling thread waits until some space becomes available in the queue.

Parameters

[in,out] msg The message to enqueue. The ownership of the pointed object is transfered to the message queue. Upon return, the msg safe pointer becomes a null pointer if the message was successfully enqueued.

◆ enqueue() [2/4]

template<typename MSG >

bool ts::MessageQueue< MSG >::enqueue	(	MessagePtr &	msg,
		cn::milliseconds	timeout
	)

inherited

Insert a message in the queue.

If the queue is full, the calling thread waits until some space becomes available in the queue or the timeout expires.

Parameters

[in,out]	msg	The message to enqueue. The ownership of the pointed object is transfered to the message queue. Upon return, the msg safe pointer becomes a null pointer if the message was successfully enqueued (no timeout).
[in]	timeout	Maximum time to wait in milliseconds.

Returns: True on success, false on error (queue still full after timeout).

◆ enqueue() [3/4]

template<typename MSG >

void ts::MessageQueue< MSG >::enqueue ( MSG * msg )

inherited

Insert a message in the queue.

Parameters

[in] msg A pointer to the message to enqueue. This pointer shall not be owned by a safe pointer. When the message is successfully enqueued, the pointer becomes owned by a safe pointer and will be deallocated when no longer used.

◆ enqueue() [4/4]

template<typename MSG >

bool ts::MessageQueue< MSG >::enqueue	(	MSG *	msg,
		cn::milliseconds	timeout
	)

inherited

Insert a message in the queue.

Parameters

[in]	msg	A pointer to the message to enqueue. This pointer shall not be owned by a safe pointer. When the message is successfully enqueued, the pointer becomes owned by a safe pointer and will be deallocated when no longer used. In case of timeout, the object is not equeued and immediately deallocated.
[in]	timeout	Maximum time to wait in milliseconds.

Returns: True on success, false on error (queue still full after timeout).

◆ forceEnqueue() [1/2]

template<typename MSG >

void ts::MessageQueue< MSG >::forceEnqueue ( MessagePtr & msg )

inherited

Insert a message in the queue, even if the queue is full.

This method immediately inserts the message, even if the queue is full. This can be used to allow exceptional overflow of the queue with unique messages, to enqueue a message to instruct the consumer thread to terminate for instance.

Parameters

[in,out] msg The message to enqueue. The ownership of the pointed object is transfered to the message queue. Upon return, the msg safe pointer becomes a null pointer.

◆ forceEnqueue() [2/2]

template<typename MSG >

void ts::MessageQueue< MSG >::forceEnqueue ( MSG * msg )

inherited

Insert a message in the queue, even if the queue is full.

This method immediately inserts the message, even if the queue is full. This can be used to allow exceptional overflow of the queue with unique messages, to enqueue a message to instruct the consumer thread to terminate for instance.

Parameters

[in] msg A pointer to the message to enqueue. This pointer shall not be owned by a safe pointer. When the message is enqueued, the pointer becomes owned by a safe pointer and will be deallocated when no longer used.

◆ dequeue() [1/2]

template<typename MSG >

void ts::MessageQueue< MSG >::dequeue ( MessagePtr & msg )

inherited

Remove a message from the queue.

Wait until a message is received.

Parameters

[out] msg Received message.

◆ dequeue() [2/2]

template<typename MSG >

bool ts::MessageQueue< MSG >::dequeue	(	MessagePtr &	msg,
		cn::milliseconds	timeout
	)

inherited

Remove a message from the queue.

Wait until a message is received or the timeout expires.

Parameters

[out]	msg	Received message.
[in]	timeout	Maximum time to wait in milliseconds. If timeout is zero and the queue is empty, return immediately.

Returns: True on success, false on error (queue still empty after timeout).

◆ peek()

template<typename MSG >

ts::MessageQueue< MSG >::MessagePtr ts::MessageQueue< MSG >::peek ( )

inherited

Peek the next message from the queue, without dequeueing it.

If several threads simultaneously read from the queue, the returned message may be deqeued in the meantime by another thread.

Returns: A safe pointer to the first message in the queue or a null pointer if the queue is empty.

◆ enqueuePlacement() [2/2]

template<typename MSG >

ts::MessageQueue< MSG >::MessageList::iterator ts::MessageQueue< MSG >::enqueuePlacement	(	const MessagePtr &	msg,
		MessageList &	list
	)

protectedvirtualinherited

This virtual protected method performs placement in the message queue.

Parameters

[in]	msg	The message to enqueue later. The message is not enqueued. Its value is used to compute the place where it should be inserted.
[in]	list	The content of the queue.

Returns: An iterator to the place where msg shall be placed.

◆ dequeuePlacement()

template<typename MSG >

ts::MessageQueue< MSG >::MessageList::iterator ts::MessageQueue< MSG >::dequeuePlacement ( MessageList & list )

protectedvirtualinherited

This virtual protected method performs dequeue location in the message queue.

Parameters

[in] list The content of the queue.

Returns: An iterator to the place from where the next message shall be removed.

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

tsMessagePriorityQueue.h

Public Types

Public Member Functions

Protected Types

Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ MessagePtr

Constructor & Destructor Documentation

◆ MessagePriorityQueue()

Member Function Documentation

◆ enqueuePlacement() [1/2]

◆ getMaxMessages()

◆ setMaxMessages()

◆ enqueue() [1/4]

◆ enqueue() [2/4]

◆ enqueue() [3/4]

◆ enqueue() [4/4]

◆ forceEnqueue() [1/2]

◆ forceEnqueue() [2/2]

◆ dequeue() [1/2]

◆ dequeue() [2/2]

◆ peek()

◆ enqueuePlacement() [2/2]

◆ dequeuePlacement()