TSDuck v3.46-4964
MPEG Transport Stream Toolkit
Loading...
Searching...
No Matches
ts::MessageQueue< MSG > Class Template Reference

#include <tsMessageQueue.h>

Inheritance diagram for ts::MessageQueue< MSG >:
Collaboration diagram for ts::MessageQueue< MSG >:

Public Types

using MessagePtr = std::shared_ptr<MSG>
using MessageType = MSG

Public Member Functions

 MessageQueue (size_t max_messages=0)
virtual ~MessageQueue () override
void addSubscription (SubscriptionHandlerInterface *handler)
void cancelSubscription (SubscriptionHandlerInterface *handler)
void clear ()
size_t currentQueueSize ()
void dequeue (MessagePtr &msg)
bool dequeue (MessagePtr &msg, cn::milliseconds timeout)
bool enqueue (MessagePtr &msg)
bool enqueue (MessagePtr &msg, cn::milliseconds timeout)
bool enqueue (MSG *msg)
bool enqueue (MSG *msg, cn::milliseconds timeout)
bool forceEnqueue (MessagePtr &msg, bool close_queue=false)
bool forceEnqueue (MSG *msg, bool close_queue=false)
size_t getMaxMessages () const
bool isClosed () const
MessagePtr peek ()
void setMaxMessages (size_t max_messages)

Protected Types

using MessageList = std::list<MessagePtr>

Protected Member Functions

template<typename HANDLER, typename F>
requires std::derived_from<HANDLER, SubscriptionHandlerInterface>
void callSubscribers (F &&func)
virtual MessageList::iterator dequeuePlacement (MessageList &list)
virtual MessageList::iterator enqueuePlacement (const MessagePtr &msg, MessageList &list)

Detailed Description

template<typename MSG>
class ts::MessageQueue< MSG >

Template message queue for inter-thread communication.

This class implements a synchronized access to a shared queue of generic messages. Messages are manipulated using shared pointers (std::shared_ptr).

Subscription to enqueue and dequese is possible using MessageQueueHandlerInterface.

See also
SubscriptionBase
Template Parameters
MSGThe type of the messages to exchange.

Member Typedef Documentation

◆ MessageType

template<typename MSG>
using ts::MessageQueue< MSG >::MessageType = MSG

Common renaming of the message type.

◆ MessagePtr

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

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.

◆ MessageList

template<typename MSG>
using ts::MessageQueue< MSG >::MessageList = std::list<MessagePtr>
protected

Queues are implemented as list of smart pointers to messages.

Constructor & Destructor Documentation

◆ MessageQueue()

template<typename MSG>
ts::MessageQueue< MSG >::MessageQueue ( size_t max_messages = 0)

Constructor.

Parameters
[in]max_messagesMaximum number of messages in the queue.
See also
setMaxMessages()

◆ ~MessageQueue()

template<typename MSG>
ts::MessageQueue< MSG >::~MessageQueue ( )
overridevirtual

Destructor

Member Function Documentation

◆ getMaxMessages()

template<typename MSG>
size_t ts::MessageQueue< MSG >::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>
void ts::MessageQueue< MSG >::setMaxMessages ( size_t max_messages)

Change the maximum allowed messages in the queue.

Parameters
[in]max_messagesMaximum 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 max_messages 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.

◆ currentQueueSize()

template<typename MSG>
size_t ts::MessageQueue< MSG >::currentQueueSize ( )

Get the current queue size.

Returns
The current number of messages in the queue. This is an instantaneous value. Because messages can be inserted or removed at any time, the actual number of messages in the queue may change immediately after this methods returns.

◆ isClosed()

template<typename MSG>
bool ts::MessageQueue< MSG >::isClosed ( ) const
inline

Check if the queue has been closed after a forceEnqueue().

Returns
True if the queue has been closed.

◆ enqueue() [1/4]

template<typename MSG>
bool ts::MessageQueue< MSG >::enqueue ( MessagePtr & msg)

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]msgThe 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. If the queue was previously closed, msg is unchanged.
Returns
True on success, false on error (queue closed).

◆ enqueue() [2/4]

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

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

◆ enqueue() [3/4]

template<typename MSG>
bool ts::MessageQueue< MSG >::enqueue ( MSG * msg)

Insert a message in the queue.

Parameters
[in]msgA 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. If the queue is closed, the message is immediately deallocated.
Returns
True on success, false on error (queue closed).

◆ enqueue() [4/4]

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

Insert a message in the queue.

Parameters
[in]msgA 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 or closed queue, the message is not enqueued and immediately deallocated.
[in]timeoutMaximum time to wait in milliseconds.
Returns
True on success, false on error (queue still full after timeout).

◆ forceEnqueue() [1/2]

template<typename MSG>
bool ts::MessageQueue< MSG >::forceEnqueue ( MessagePtr & msg,
bool close_queue = false )

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]msgThe 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.
[in]close_queueWhen true, the queue is considered closed and no more messages will be enqueued. All further enqueue operations will fail.
Returns
True on success, false on error (queue already closed).

◆ forceEnqueue() [2/2]

template<typename MSG>
bool ts::MessageQueue< MSG >::forceEnqueue ( MSG * msg,
bool close_queue = false )

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]msgA 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.
[in]close_queueWhen true, the queue is considered closed and no more messages will be enqueued. All further enqueue operations will fail.
Returns
True on success, false on error (queue already closed).

◆ dequeue() [1/2]

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

Remove a message from the queue. Wait until a message is received.

Parameters
[out]msgReceived message.

◆ dequeue() [2/2]

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

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>
ts::MessageQueue< MSG >::MessagePtr ts::MessageQueue< MSG >::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.

◆ clear()

template<typename MSG>
void ts::MessageQueue< MSG >::clear ( )

Clear the content of the queue. If the close_queue flags was set, it is cleared and the queue is no longer closed.

◆ enqueuePlacement()

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

This virtual protected method performs placement in the message queue.

Parameters
[in]msgThe message to enqueue later. The message is not enqueued. Its value is used to compute the place where it should be inserted.
[in]listThe 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)
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.

◆ addSubscription()

void ts::SubscriptionBase::addSubscription ( SubscriptionHandlerInterface * handler)
inherited

Add a subscriber to open/close events.

Parameters
[in]handlerThe object to call on open() and close().

◆ cancelSubscription()

void ts::SubscriptionBase::cancelSubscription ( SubscriptionHandlerInterface * handler)
inherited

Remove a subscriber to open/close events.

Parameters
[in]handlerThe object to no longer call on open() and close().

◆ callSubscribers()

template<typename HANDLER, typename F>
requires std::derived_from<HANDLER, SubscriptionHandlerInterface>
void ts::SubscriptionBase::callSubscribers ( F && func)
inlineprotectedinherited

Call a handler on all subscribers, using a lambda expression.

Parameters
[in]funcFunction to call as lambda expression.

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