Strongly-typed mailbox for message-based communication. More...

#include <commrat/mailbox/mailbox.hpp>

Public Member Functions
	Mailbox (const MailboxConfig &config)
	Construct a mailbox with the given configuration.

	~Mailbox ()
	Destructor - automatically stops and cleans up.

	Mailbox (const Mailbox &)=delete

Mailbox &	operator= (const Mailbox &)=delete

	Mailbox (Mailbox &&other) noexcept

Mailbox &	operator= (Mailbox &&other) noexcept

auto	start () -> MailboxResult< void >
	Start the mailbox (initialize TiMS connection)

void	stop ()
	Stop the mailbox.

bool	is_running () const
	Check if mailbox is running.

template<typename T > requires is_registered<T>
auto	send (T &message, uint32_t dest_mailbox) -> MailboxResult< void >
	Send a message to a destination mailbox.

template<typename T > requires is_registered<T>
auto	receive () -> MailboxResult< TimsMessage< T > >
	Receive a message of specific type (blocking)

template<typename T > requires is_registered<T>
auto	try_receive () -> std::optional< TimsMessage< T > >
	Try to receive a message without blocking.

template<typename T > requires is_registered<T>
auto	receive_for (std::chrono::milliseconds timeout) -> MailboxResult< TimsMessage< T > >
	Receive a message with timeout.

auto	receive_any_raw (std::chrono::milliseconds timeout=std::chrono::milliseconds{-1}) -> MailboxResult< RawReceivedMessage >
	Receive any message without knowing its type.

template<typename Visitor >
auto	receive_any (Visitor &&visitor) -> MailboxResult< void >
	Receive any registered message type using a visitor.

auto	clean () -> MailboxResult< void >
	Clear all pending messages from the mailbox.

uint32_t	mailbox_id () const
	Get the mailbox ID.

uint64_t	messages_sent () const
	Get number of messages sent.

uint64_t	messages_received () const
	Get number of messages received.

Static Public Member Functions
static constexpr size_t	num_message_types ()
	Get number of registered message types.

Static Public Attributes
template<typename T >
static constexpr bool	is_registered
	Check if a type is registered with this mailbox at compile time For TimsMessage<PayloadT>, check if PayloadT is registered.

Detailed Description

template<typename... MessageDefs>
class commrat::Mailbox< MessageDefs >

Strongly-typed mailbox for message-based communication.

A modern C++20 mailbox interface that provides compile-time type safety for message operations. Accepts MessageDefinition types which contain compile-time message IDs.

Template Parameters

MessageDefs Pack of MessageDefinition types this mailbox can handle

Example:

using StatusMsg = MessageDefinition<StatusData, MessagePrefix::UserDefined, UserSubPrefix::Data>;
using CmdMsg = MessageDefinition<CommandData, MessagePrefix::UserDefined, UserSubPrefix::Commands>;
 
Mailbox<StatusMsg, CmdMsg> mbx(config);
mbx.start();
 
StatusData status{.status_code = 100};
mbx.send(status, dest_mailbox_id);
 
auto result = mbx.receive<StatusData>();
if (result) {
    std::cout << "Status: " << result->message.status_code << "\n";
}

Definition at line 177 of file mailbox.hpp.

Constructor & Destructor Documentation

◆ Mailbox() [1/3]

template<typename... MessageDefs>

commrat::Mailbox< MessageDefs >::Mailbox ( const MailboxConfig & config )

inlineexplicit

Construct a mailbox with the given configuration.

Parameters

config Mailbox configuration

Definition at line 202 of file mailbox.hpp.

◆ ~Mailbox()

template<typename... MessageDefs>

commrat::Mailbox< MessageDefs >::~Mailbox ( )

inline

Destructor - automatically stops and cleans up.

Definition at line 211 of file mailbox.hpp.

References commrat::Mailbox< MessageDefs >::stop().

◆ Mailbox() [2/3]

template<typename... MessageDefs>

commrat::Mailbox< MessageDefs >::Mailbox ( const Mailbox< MessageDefs > & )

delete

◆ Mailbox() [3/3]

template<typename... MessageDefs>

commrat::Mailbox< MessageDefs >::Mailbox ( Mailbox< MessageDefs > && other )

inlinenoexcept

Definition at line 220 of file mailbox.hpp.

Member Function Documentation

◆ clean()

template<typename... MessageDefs>

auto commrat::Mailbox< MessageDefs >::clean ( ) -> MailboxResult<void>

inline

Clear all pending messages from the mailbox.

Returns: Success or error

Definition at line 553 of file mailbox.hpp.

References commrat::MessageRegistry< MessageDefs... >::max_message_size, commrat::NotRunning, and commrat::TimsWrapper::receive_raw_bytes().

◆ is_running()

template<typename... MessageDefs>

bool commrat::Mailbox< MessageDefs >::is_running ( ) const

inline

Check if mailbox is running.

Definition at line 274 of file mailbox.hpp.

◆ mailbox_id()

template<typename... MessageDefs>

uint32_t commrat::Mailbox< MessageDefs >::mailbox_id ( ) const

inline

Get the mailbox ID.

Definition at line 572 of file mailbox.hpp.

References commrat::MailboxConfig::mailbox_id.

◆ messages_received()

template<typename... MessageDefs>

uint64_t commrat::Mailbox< MessageDefs >::messages_received ( ) const

inline

Get number of messages received.

Definition at line 586 of file mailbox.hpp.

References commrat::TimsWrapper::get_messages_received().

◆ messages_sent()

template<typename... MessageDefs>

uint64_t commrat::Mailbox< MessageDefs >::messages_sent ( ) const

inline

Get number of messages sent.

Definition at line 579 of file mailbox.hpp.

References commrat::TimsWrapper::get_messages_sent().

◆ num_message_types()

template<typename... MessageDefs>

static constexpr size_t commrat::Mailbox< MessageDefs >::num_message_types ( )

inlinestaticconstexpr

Get number of registered message types.

Definition at line 299 of file mailbox.hpp.

◆ operator=() [1/2]

template<typename... MessageDefs>

Mailbox & commrat::Mailbox< MessageDefs >::operator= ( const Mailbox< MessageDefs > & )

delete

◆ operator=() [2/2]

template<typename... MessageDefs>

Mailbox & commrat::Mailbox< MessageDefs >::operator= ( Mailbox< MessageDefs > && other )

inlinenoexcept

Definition at line 227 of file mailbox.hpp.

References commrat::Mailbox< MessageDefs >::stop().

◆ receive()

template<typename... MessageDefs>

template<typename T >
requires is_registered<T>

auto commrat::Mailbox< MessageDefs >::receive ( ) -> MailboxResult<TimsMessage<T>>

inline

Receive a message of specific type (blocking)

Template Parameters

T	Message type to receive

Returns: Received message or error

Definition at line 352 of file mailbox.hpp.

References commrat::deserialize(), commrat::NetworkError, commrat::NotRunning, commrat::TimsWrapper::receive_raw_bytes(), and commrat::SerializationError.

◆ receive_any()

template<typename... MessageDefs>

template<typename Visitor >

auto commrat::Mailbox< MessageDefs >::receive_any ( Visitor && visitor ) -> MailboxResult<void>

inline

Receive any registered message type using a visitor.

The visitor will be called with the received message, allowing runtime dispatch based on the actual message type received.

Parameters

visitor Callable that accepts any registered message type

Returns: Success or error

Example:

mailbox.receive_any([](auto&& msg) {
    using T = std::decay_t<decltype(msg)>;
    if constexpr (std::is_same_v<T, TimsMessage<StatusMessage>>) {
        std::cout << "Status: " << msg->payload.status_code << "\n";
    }
});

Definition at line 506 of file mailbox.hpp.

References commrat::InvalidMessage, commrat::MessageRegistry< MessageDefs... >::max_message_size, commrat::TimsHeader::msg_type, commrat::NetworkError, commrat::NotRunning, commrat::TimsWrapper::receive_raw_bytes(), and commrat::MessageRegistry< MessageDefs... >::visit().

◆ receive_any_raw()

template<typename... MessageDefs>

auto commrat::Mailbox< MessageDefs >::receive_any_raw ( std::chrono::milliseconds timeout = std::chrono::milliseconds{-1} ) -> MailboxResult<RawReceivedMessage>

inline

Receive any message without knowing its type.

Returns raw message data with type information. Useful for command loops that need to inspect the message type before deserializing.

Parameters

timeout Maximum time to wait for a message

Returns: Raw message with type info, or error

Definition at line 444 of file mailbox.hpp.

◆ receive_for()

template<typename... MessageDefs>

template<typename T >
requires is_registered<T>

auto commrat::Mailbox< MessageDefs >::receive_for ( std::chrono::milliseconds timeout ) -> MailboxResult<TimsMessage<T>>

inline

Receive a message with timeout.

Template Parameters

T	Message type to receive

Parameters

timeout Maximum time to wait

Returns: Received message or error (including timeout)

Definition at line 405 of file mailbox.hpp.

References commrat::deserialize(), commrat::NetworkError, commrat::NotRunning, commrat::TimsWrapper::receive_raw_bytes(), commrat::SerializationError, and commrat::Timeout.

◆ send()

template<typename... MessageDefs>

template<typename T >
requires is_registered<T>

auto commrat::Mailbox< MessageDefs >::send	(	T &	message,
		uint32_t	dest_mailbox
	)		-> MailboxResult<void>

inline

Send a message to a destination mailbox.

Template Parameters

T	Message type (must be registered)

Parameters

message	Message to send
dest_mailbox	Destination mailbox ID

Returns: Success or error

Definition at line 317 of file mailbox.hpp.

References commrat::InvalidDestination, commrat::NetworkError, commrat::NotRunning, commrat::TimsWrapper::send(), commrat::MessageRegistry< MessageDefs... >::serialize(), and commrat::SUCCESS.

◆ start()

template<typename... MessageDefs>

auto commrat::Mailbox< MessageDefs >::start ( ) -> MailboxResult<void>

inline

Start the mailbox (initialize TiMS connection)

Returns: Success or error

Definition at line 246 of file mailbox.hpp.

References commrat::AlreadyRunning, commrat::TimsWrapper::initialize(), commrat::NotInitialized, and commrat::SUCCESS.

◆ stop()

template<typename... MessageDefs>

void commrat::Mailbox< MessageDefs >::stop ( )

inline

Stop the mailbox.

Definition at line 264 of file mailbox.hpp.

References commrat::TimsWrapper::shutdown().

Referenced by commrat::Mailbox< MessageDefs >::~Mailbox(), and commrat::Mailbox< MessageDefs >::operator=().

◆ try_receive()

template<typename... MessageDefs>

template<typename T >
requires is_registered<T>

auto commrat::Mailbox< MessageDefs >::try_receive ( ) -> std::optional<TimsMessage<T>>

inline

Try to receive a message without blocking.

Template Parameters

T	Message type to receive

Returns: Message if available, empty optional otherwise

Definition at line 386 of file mailbox.hpp.

Member Data Documentation

◆ is_registered

template<typename... MessageDefs>

template<typename T >

constexpr bool commrat::Mailbox< MessageDefs >::is_registered

staticconstexpr

Initial value:

= []() constexpr {
        
        if constexpr (requires { typename T::payload_type; }) {
            return Registry::template is_registered<typename T::payload_type>;
        } else {
            return Registry::template is_registered<T>;
        }
    }()

Check if a type is registered with this mailbox at compile time For TimsMessage<PayloadT>, check if PayloadT is registered.

Definition at line 287 of file mailbox.hpp.

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

commrat/mailbox/mailbox.hpp

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Mailbox() [1/3]

◆ ~Mailbox()

◆ Mailbox() [2/3]

◆ Mailbox() [3/3]

Member Function Documentation

◆ clean()

◆ is_running()

◆ mailbox_id()

◆ messages_received()

◆ messages_sent()

◆ num_message_types()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ receive()

◆ receive_any()

◆ receive_any_raw()

◆ receive_for()

◆ send()

◆ start()

◆ stop()

◆ try_receive()

Member Data Documentation

◆ is_registered