General purpose message queue for inter-thread communication.
More...
#include <MessageQueue.h>
|
|
virtual | ~IMessageQueue () |
| | Destructor.
|
| |
| virtual std::size_t | push (Message message)=0 |
| | Pushes one message into the queue. More...
|
| |
| virtual std::size_t | pop (Message &message, bool blocking)=0 |
| | Pops one message from the queue. More...
|
| |
| virtual void | cancel ()=0 |
| | Cancel the queue functionality indefinitely releasing any blocked thread. More...
|
| |
|
virtual bool | is_cancelled () const =0 |
| | Returns true if the queue have been cancelled.
|
| |
|
virtual std::size_t | size () const =0 |
| | Returns the number of messages contained inside the queue.
|
| |
| template<typename Derived > |
| std::size_t | popT (std::shared_ptr< Derived > &message, bool blocking) |
| | Convenient template method to pop messages. More...
|
| |
|
| static IMessageQueue * | create (std::size_t max_capacity=std::numeric_limits< std::size_t >::max()) |
| | Factory method to create a message queue implemented for the current platform. More...
|
| |
General purpose message queue for inter-thread communication.
This class uses run-time polymorphism to allow message-driven communication and synchronization between two or more threads.
The class is defined as a pure abstract class with a factory method (see IMessageQueue::create) to build platform-specific implementations of the queue while maintaining a platform-agnostic interface.
- Note
- Only one method of this class can (optionally) block the calling thread: IMessageQueue::pop.
- This class is 100% thread safe.
| virtual void IMessageQueue::cancel |
( |
| ) |
|
|
pure virtual |
Cancel the queue functionality indefinitely releasing any blocked thread.
The cancelled status is not reversible and is meant mainly as an action to be performed before the queue destruction.
- Note
- Doesn't wait for the peer threads to be released, just broadcast a signal to them.
| static IMessageQueue* IMessageQueue::create |
( |
std::size_t |
max_capacity = std::numeric_limits< std::size_t >::max() | ) |
|
|
static |
Factory method to create a message queue implemented for the current platform.
- Parameters
-
| max_capacity | Maximum number of messages that can be queued at the same time. By default this limit is relaxed as much as possible. |
- Returns
- The newly created message queue.
| virtual std::size_t IMessageQueue::pop |
( |
Message & |
message, |
|
|
bool |
blocking |
|
) |
| |
|
pure virtual |
Pops one message from the queue.
- Parameters
-
| [out] | message | Smart pointer that will be reset with the popped message in case of success. |
| blocking | If set to true the method blocks the current thread indefinitely until a new message is pushed into the queue by another thread or until the queue is not cancelled. |
- Returns
- On success, the number of messages contained by the queue before the extraction, that is at least one.
- On failure, zero (parameter message is not touched in that case).
- Precondition
- The queue have not been cancelled.
template<typename Derived >
| std::size_t IMessageQueue::popT |
( |
std::shared_ptr< Derived > & |
message, |
|
|
bool |
blocking |
|
) |
| |
|
inline |
Convenient template method to pop messages.
Since by design the user should derive messages from the class IMessage this template take care to dynamic cast shared pointers to the user defined derived class.
This method is meant to be used when the user uses the queue with one single derived class and hence don't need to manually dynamic cast every popped message from the generic IMessage.
- Parameters
-
| [out] | message | Smart pointer that will be reset with the popped message in case of success. |
| blocking | If set to true the method blocks the current thread indefinitely until a new message is pushed into the queue by another thread or until the queue is not cancelled. |
- Returns
- On success, the number of messages contained by the queue before the extraction, that is at least one.
- On failure, zero (parameter message is not touched in that case).
- Precondition
- The queue have not been cancelled.
| virtual std::size_t IMessageQueue::push |
( |
Message |
message | ) |
|
|
pure virtual |
Pushes one message into the queue.
- Parameters
-
| message | The message to be inserted. |
- Returns
- On success, the number of messages contained by the queue after the insertion, that is at least one.
- On failure, zero. This may happen if the maximum allowed capacity for the queue have been reached.
- Precondition
- The parameter message is not null.
- The queue have not been cancelled.
The documentation for this class was generated from the following file:
1.8.5
