TSDuck v3.46-4965
MPEG Transport Stream Toolkit
Loading...
Searching...
No Matches
ts::MessagePriorityQueue< MSG, COMPARE > Class Template Reference

#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>
using MessageType = MSG

Public Member Functions

 MessagePriorityQueue (size_t max_messages=0)
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>
using SuperClass = MessageQueue<MSG>

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 SuperClass::MessageList::iterator enqueuePlacement (const typename SuperClass::MessagePtr &msg, typename SuperClass::MessageList &list) override
virtual MessageList::iterator enqueuePlacement (const MessagePtr &msg, MessageList &list)

Detailed Description

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

Template message queue for inter-thread communication with priority.

This 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
MSGThe type of the messages to exchange.
COMPAREA function object to sort MSG instances. When a message is "before" or "less than" another message, it will be dequeued first (it has a higher priority). By default, the '<' operator on MSG is used.

Member Typedef Documentation

◆ SuperClass

template<typename MSG, class COMPARE = std::less<MSG>>
using ts::MessagePriorityQueue< MSG, COMPARE >::SuperClass = MessageQueue<MSG>
protected

Explicit reference to superclass.

◆ MessageType

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

Common renaming of the message type.

◆ 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.

◆ MessageList

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

Queues are implemented as list of smart pointers to messages.

Constructor & Destructor Documentation

◆ MessagePriorityQueue()

template<typename MSG, class COMPARE = std::less<MSG>>
ts::MessagePriorityQueue< MSG, COMPARE >::MessagePriorityQueue ( size_t max_messages = 0)
inline

Constructor.

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.

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]msgThe message to enqueue.
[in]listThe 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 max_messages)
inherited

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

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
inlineinherited

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)
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]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 )
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]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)
inherited

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

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 )
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]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 )
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]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)
inherited

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

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

◆ clear()

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

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

◆ 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]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)
protectedvirtualinherited

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: