vreMessageManager.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file vreMessageManager.h
//! \brief Defines the central message manager for the VREngage messaging system
//!
//! This file contains the DtVreMessageManager abstract base class which serves as the
//! central hub for message routing and dispatching in the VREngage system. It provides
//! a thread-safe mechanism for registering message handlers, queuing messages, and
//! dispatching messages to appropriate handlers across multiple threads.
 
#pragma once
 
#include "vreMessageManager/export.h"
#include "vreMessageManager/vreMessage.h"
 
#include "vreUtil/assert.h"
 
namespace makVre
{
class DtVreMessageFactory;
 
//! \brief Central manager for the VREngage messaging system
//!
//! This abstract base class defines the interface for the message manager, which
//! serves as the central hub for message routing and dispatching in the VREngage
//! system. It provides thread-safe mechanisms for registering message handlers,
//! queuing messages, and dispatching messages to appropriate handlers.
//!
//! The message manager uses a hierarchical message listener tree to efficiently
//! route messages to the appropriate handlers based on their message types, and
//! supports both immediate message dispatch and delayed message queuing.
//!
//! The system is implemented as a singleton, with a concrete implementation
//! (DtTbbVreMessageManager) that uses Intel TBB concurrent containers for
//! thread-safe message queuing across multiple threads.
class MESSAGEMANAGER_DLL DtVreMessageManager
{
public:
   //! \brief Statistics for message dispatching
   //!
   //! This structure stores statistics about message dispatching activity,
   //! including the number of messages dispatched in the current frame and
   //! the types of messages that were dispatched.
   struct EventStats
   {
      //! \brief Number of messages dispatched in the current frame
      int messagesDispatchedThisFrame;
 
      //! \brief List of message types that were dispatched
      std::vector<std::string> messageTypesDispatched;
   };
 
   //! \brief Position for adding a message handler in the handler list
   //!
   //! This enumeration defines the possible positions for adding a message
   //! handler in the handler list for a specific message type. The position
   //! affects the order in which handlers are called when a message is dispatched.
   enum class HandlerPosition
   {
      FRONT = 0, //!< Add the handler at the front of the list (called first)
      BACK       //!< Add the handler at the back of the list (called last)
   };
 
   //! \brief Gets the singleton instance of the message manager
   //! \return Reference to the singleton message manager instance
   //!
   //! This static method returns a reference to the singleton instance of the
   //! message manager. If the instance doesn't exist yet, it creates a new one.
   static DtVreMessageManager& instance();
 
   //! \brief Initializes the message manager
   //!
   //! This method must be called in the main thread to initialize the message
   //! manager. It identifies the main thread, which has special responsibilities
   //! in the messaging system, such as handling delayed messages.
   //!
   //! \note This function must be called from the main thread because the main
   //!       thread performs some additional work in the messaging system.
   virtual void init() = 0;
 
   //! \brief Registers a message handler for a specific message type
   //! \param messageType Type of messages to handle (can include wildcards)
   //! \param handler Delegate to the handler function
   //! \param handlerPos Position to add the handler (FRONT or BACK)
   //!
   //! This method registers a handler function for a specific message type.
   //! When a message of the specified type is dispatched, the handler function
   //! will be called with the message as its parameter. The position parameter
   //! determines whether the handler is added to the front or back of the
   //! handler list, affecting its execution order relative to other handlers
   //! for the same message type.
   //!
   //! The message type can include wildcards ("*") to match multiple message
   //! types. For example, "entity.*" would match all message types that start
   //! with "entity.".
   virtual void addHandler(const std::string& messageType, const DtVreMessageDelegate& handler,
      HandlerPosition handlerPos = HandlerPosition::BACK) = 0;
 
   //! \brief Unregisters a message handler for a specific message type
   //! \param messageType Type of messages the handler was registered for
   //! \param handler Delegate to the handler function to remove
   //!
   //! This method removes a previously registered handler function for a
   //! specific message type. After removal, the handler will no longer be
   //! called when messages of the specified type are dispatched.
   virtual void removeHandler(const std::string& messageType, const DtVreMessageDelegate& handler) = 0;
 
   //! \brief Processes queued messages for the current thread
   //! \param dt Delta time in seconds since the last tick
   //!
   //! This method processes all queued messages for the current thread,
   //! dispatching them to registered handlers. It also updates the timers
   //! for delayed messages, making them available for dispatch when their
   //! delay time has elapsed.
   //!
   //! \note Each thread that participates in the messaging system must call
   //!       this method in its thread loop to process messages targeted for
   //!       that thread.
   virtual void tick(double dt) = 0;
 
   //! \brief Queues a message for later dispatch
   //! \param msg Pointer to the message to queue
   //! \param delay Delay in seconds before the message is dispatched
   //!
   //! This method queues a message for later dispatch. If a delay is specified,
   //! the message will not be dispatched until the delay time has elapsed.
   //! The message will be dispatched the next time tick() is called after the
   //! delay has elapsed.
   //!
   //! \note The message manager takes ownership of the message and will delete
   //!       it when it is no longer needed.
   virtual void queueMessage(DtVreMessage* msg, double delay = 0.0) = 0;
 
   //! \brief Immediately dispatches a message
   //! \param msg Pointer to the message to dispatch
   //!
   //! This method immediately dispatches a message to all registered handlers
   //! that match its message type. The message is dispatched in the context of
   //! the calling thread.
   //!
   //! \note The message manager takes ownership of the message and will delete
   //!       it when it is no longer needed.
   virtual void sendMessage(DtVreMessage* msg) = 0;
 
   //! \brief Gets the message factory associated with this message manager
   //! \return Reference to the message factory
   //!
   //! This method returns a reference to the message factory associated with
   //! this message manager. The factory is used to create messages from
   //! serialized data and to register message types.
   virtual DtVreMessageFactory& factory() = 0;
 
   //! \brief Gets the event statistics for the current thread
   //! \return Reference to the event statistics structure
   //!
   //! This method returns a reference to the event statistics structure for
   //! the current thread. The statistics include the number of messages
   //! dispatched in the current frame and the types of messages that were
   //! dispatched.
   virtual const EventStats& stats() = 0;
 
protected:
   //! \brief Protected constructor
   //!
   //! This constructor is protected to enforce the singleton pattern.
   //! It creates a new message factory and initializes member variables.
   DtVreMessageManager();
 
   //! \brief Virtual destructor
   //!
   //! Ensures proper cleanup of derived classes.
   virtual ~DtVreMessageManager();
 
   //! \brief Singleton instance of the message manager
   //!
   //! This static pointer holds the singleton instance of the message manager.
   //! It is initialized by the constructor and accessed through the instance() method.
   static DtVreMessageManager* theVreMessageManager;
 
   //! \brief Message factory for creating messages
   //!
   //! This static pointer holds the message factory associated with the message
   //! manager. It is initialized by the constructor and accessed through the
   //! factory() method.
   static DtVreMessageFactory* theMessageFactory;
};
 
} // namespace makVre
 
//! \name Message Type Assertion Macros
//! @{
 
//! \brief Asserts that a message is of the expected type and casts it
//! \param msg Pointer to the message to check and cast
//! \param MsgType Expected message type (class name)
//! \param msgCast Variable name for the cast message pointer
//!
//! This macro checks that a message is of the expected type using dynamic_cast,
//! and then creates a properly typed pointer to the message using static_cast.
//! It should be used when handling messages for which you have registered a
//! handler with the exact message type (no wildcards).
#define ASSERT_TYPE(msg, MsgType, msgCast)                                                                             \
   DtASSERT(dynamic_cast<MsgType*>(msg), "Message is incorrect type");                                                 \
   MsgType* msgCast = static_cast<MsgType*>(msg);
 
//! \brief Asserts that a message is of the expected type without casting it
//! \param msg Pointer to the message to check
//! \param MsgType Expected message type (class name)
//!
//! This macro checks that a message is of the expected type using dynamic_cast,
//! but does not create a cast pointer. It should be used when handling messages
//! for which you have registered a handler with the exact message type (no wildcards)
//! and you don't need to access type-specific members of the message.
#define ASSERT_TYPE_NO_CAST(msg, MsgType) DtASSERT(dynamic_cast<MsgType*>(msg), "Message is incorrect type");
 
//! @}