Cbeam
Loading...
Searching...
No Matches
cbeam::concurrency::message_manager< MessageDataType > Class Template Reference

#include <message_manager.hpp>

Public Types

enum class  order_type { FIFO , FILO , RANDOM }
 Enum class defining the order in which messages are processed. More...
 
using message_id_type = std::size_t
 
using message_logger_type = std::function<void(message_id_type, MessageDataType, bool)>
 Typedef for a message logging function.
 

Public Member Functions

void send_message (const message_id_type message_id, const MessageDataType &message_data, const std::size_t max_queued_messages=0)
 Sends a message of specified ID and data.
 
void add_handler (const message_id_type message_id, std::function< void(MessageDataType message_data)> on_message, std::function< void(const std::exception &exception)> on_exception=nullptr, std::function< void()> on_exit=nullptr, const std::string &thread_name={}, const order_type order=order_type::FIFO)
 Adds a message handler for a specified message ID.
 
void wait_until_empty (const message_id_type message_id)
 
void dispose (const message_id_type message_id)
 
void set_logger (const message_id_type message_id, message_logger_type on_message)
 

Detailed Description

template<typename MessageDataType>
class cbeam::concurrency::message_manager< MessageDataType >
Examples
cbeam/concurrency/message_manager.hpp.

Member Typedef Documentation

◆ message_id_type

template<typename MessageDataType>
using cbeam::concurrency::message_manager< MessageDataType >::message_id_type = std::size_t

◆ message_logger_type

template<typename MessageDataType>
using cbeam::concurrency::message_manager< MessageDataType >::message_logger_type = std::function<void(message_id_type, MessageDataType, bool)>

Typedef for a message logging function.

Defines a function type used for logging messages. The function takes three parameters: the message ID, the message data of type MessageDataType, and a boolean flag indicating whether the message is outgoing (true) or incoming (false). This allows for flexible integration of custom logging functionality within the message processing flow.

Member Enumeration Documentation

◆ order_type

template<typename MessageDataType>
enum class cbeam::concurrency::message_manager::order_type
strong

Enum class defining the order in which messages are processed.

This enumeration specifies the order in which messages are handled by the message handlers. The available ordering types are:

  • FIFO (First In First Out): Messages are processed in the order they are received. This is a traditional approach that ensures a predictable processing order.
  • FILO (First In Last Out): The most recently received message is processed first. This approach can be useful for prioritizing newer messages.
  • RANDOM: Messages are processed in a random order. In certain algorithmic contexts, such as fill algorithms for raster graphics, introducing randomness can reduce the overall length of the message queue. This is due to the reduction of path dependencies and the increased entropy in message processing, which avoids consistent biases towards older (FIFO) or newer (FILO) messages. However, for long message queues, the efficiency might decrease due to the overhead of random access in a std::deque. Nevertheless, the RANDOM mode can be beneficial if it aligns with the algorithmic needs and the message queues remain short.
Enumerator
FIFO 

Process messages in the order they were received.

FILO 

Process the most recently received message first.

RANDOM 

Process messages in a random order, reducing path dependencies in certain algorithms but less efficient for long queues.

Member Function Documentation

◆ add_handler()

template<typename MessageDataType>
void cbeam::concurrency::message_manager< MessageDataType >::add_handler ( const message_id_type message_id,
std::function< void(MessageDataType message_data)> on_message,
std::function< void(const std::exception &exception)> on_exception = nullptr,
std::function< void()> on_exit = nullptr,
const std::string & thread_name = {},
const order_type order = order_type::FIFO )
inline

Adds a message handler for a specified message ID.

This method registers a new message handler for a specified ID. The handler will process messages sent to the given message ID. Handlers can be customized with functions to execute on message reception, exception occurrence, idle state, and handler exit. The method supports specifying a thread name and the order in which messages are processed.

Parameters
message_idThe message ID for which the handler is being added. It can be any arbitrary number and does not require sequential order.
on_messageA function to be called when a message is received. The function should accept a message of the type specified by the MessageDataType template parameter.
on_exceptionOptional. A function to be called if an exception occurs during message processing. It must accept a std::exception object.
on_exitOptional. A function to be called when the message handler is about to exit.
thread_nameOptional. A name for the thread running the handler. Useful for debugging purposes.
orderThe order in which messages will be processed by this handler. Can be FIFO (First In First Out), FILO (First In Last Out), or RANDOM.
Note
This method is thread-safe and synchronizes the addition of handlers.
Examples
cbeam/concurrency/message_manager.hpp.

◆ dispose()

template<typename MessageDataType>
void cbeam::concurrency::message_manager< MessageDataType >::dispose ( const message_id_type message_id)
inline

◆ send_message()

template<typename MessageDataType>
void cbeam::concurrency::message_manager< MessageDataType >::send_message ( const message_id_type message_id,
const MessageDataType & message_data,
const std::size_t max_queued_messages = 0 )
inline

Sends a message of specified ID and data.

This method enqueues a message of a specified ID. The message is added to the queue corresponding to this ID and will be processed according to the queue's order type (FIFO, FILO, or RANDOM). If a maximum queue size is specified and the queue is full, this method will block until there is space available in the queue. The add_handler method does not need to be called prior to this; message_id can be any arbitrary number, assuming a corresponding handler is or will be registered. As it uses an internal std::map, IDs do not need to be sequential numbers.

Parameters
message_idThe message ID to be sent. This can be any arbitrary number and does not require sequential order.
message_dataThe message data to be sent. This must be of the type specified by the MessageDataType template parameter.
max_queued_messagesThe maximum number of messages allowed in the queue of this ID. If the queue is full, this method will block until space is available. A value of 0 means no limit on the queue size.
Note
This method is thread-safe and ensures that messages are enqueued in a synchronized manner.
Examples
cbeam/concurrency/message_manager.hpp.

◆ set_logger()

template<typename MessageDataType>
void cbeam::concurrency::message_manager< MessageDataType >::set_logger ( const message_id_type message_id,
message_logger_type on_message )
inline

◆ wait_until_empty()

template<typename MessageDataType>
void cbeam::concurrency::message_manager< MessageDataType >::wait_until_empty ( const message_id_type message_id)
inline

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