TSDuck Version 3.16-1064 (TSDuck - The MPEG Transport Stream Toolkit)
ts::MessageQueue< MSG, MUTEX > Class Template Reference

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

Inheritance diagram for ts::MessageQueue< MSG, MUTEX >:

Public Types

typedef SafePtr< MSG, MUTEX > MessagePtr
 Safe pointer to messages. More...
 

Public Member Functions

 MessageQueue (size_t maxMessages=0)
 Constructor. More...
 
virtual ~MessageQueue ()
 Destructor.
 
void clear ()
 Clear the content of the queue.
 
bool dequeue (MessagePtr &msg, MilliSecond timeout=Infinite)
 Remove a message from the queue. More...
 
bool enqueue (const MessagePtr &msg, MilliSecond timeout=Infinite)
 Insert a message in the queue. More...
 
void forceEnqueue (const MessagePtr &msg)
 Insert a message in the queue, even if the queue is full. More...
 
size_t getMaxMessages () const
 Get the maximum allowed messages in the queue. More...
 
MessagePtr peek ()
 Peek the next message from the queue, without dequeueing it. More...
 
void setMaxMessages (size_t maxMessages)
 Change the maximum allowed messages in the queue. More...
 

Protected Types

typedef std::list< MessagePtrMessageList
 Queues are implemented as list of smart pointers to messages.
 

Protected Member Functions

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

Detailed Description

template<typename MSG, class MUTEX = Mutex>
class ts::MessageQueue< MSG, MUTEX >

Template message queue for inter-thread communication.

The ts::MessageQueue template class implements a synchronized access to a shared queue of generic messages.

Template Parameters
MSGThe type of the messages to exchange.
MUTEXThe type of mutex for synchronization (ts::Mutex by default).

Member Typedef Documentation

◆ MessagePtr

template<typename MSG, class MUTEX = Mutex>
typedef SafePtr<MSG, MUTEX> ts::MessageQueue< MSG, MUTEX >::MessagePtr

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 safe-pointer to the actual message content.

Constructor & Destructor Documentation

◆ MessageQueue()

template<typename MSG, class MUTEX = Mutex>
ts::MessageQueue< MSG, MUTEX >::MessageQueue ( size_t  maxMessages = 0)

Constructor.

Parameters
[in]maxMessagesMaximum 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

◆ getMaxMessages()

template<typename MSG, class MUTEX = Mutex>
size_t ts::MessageQueue< MSG, MUTEX >::getMaxMessages ( ) const

Get the maximum allowed messages in the queue.

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

◆ setMaxMessages()

template<typename MSG, class MUTEX = Mutex>
void ts::MessageQueue< MSG, MUTEX >::setMaxMessages ( size_t  maxMessages)

Change the maximum allowed messages in the queue.

Parameters
[in]maxMessagesMaximum 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()

template<typename MSG, class MUTEX = Mutex>
bool ts::MessageQueue< MSG, MUTEX >::enqueue ( const MessagePtr msg,
MilliSecond  timeout = Infinite 
)

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]msgThe message to enqueue.
[in]timeoutMaximum time to wait in milliseconds.
Returns
True on success, false on error (queue still full after timeout).

◆ forceEnqueue()

template<typename MSG, class MUTEX = Mutex>
void ts::MessageQueue< MSG, MUTEX >::forceEnqueue ( const MessagePtr msg)

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]msgThe message to enqueue.

◆ dequeue()

template<typename MSG, class MUTEX = Mutex>
bool ts::MessageQueue< MSG, MUTEX >::dequeue ( MessagePtr msg,
MilliSecond  timeout = Infinite 
)

Remove a message from the queue.

Wait until a message is received or the timeout expires.

Parameters
[out]msgReceived message.
[in]timeoutMaximum 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, class MUTEX = Mutex>
MessagePtr ts::MessageQueue< MSG, MUTEX >::peek ( )

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()

template<typename MSG, class MUTEX = Mutex>
virtual MessageList::iterator ts::MessageQueue< MSG, MUTEX >::enqueuePlacement ( const MessagePtr msg,
MessageList list 
)
protectedvirtual

This virtual protected method performs placement in the message queue.

Parameters
[in]msgThe message to enqueue.
[in]listThe content of the queue.
Returns
An iterator to the place where msg shall be placed.

◆ dequeuePlacement()

template<typename MSG, class MUTEX = Mutex>
virtual MessageList::iterator ts::MessageQueue< MSG, MUTEX >::dequeuePlacement ( MessageList list)
protectedvirtual

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

Parameters
[in]listThe 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: