Type-restricted mailbox with optimized buffer sizing. More...

#include <commrat/mailbox/typed_mailbox.hpp>

Public Member Functions
	TypedMailbox (const MailboxConfig &config)
	Construct a typed mailbox.

	~TypedMailbox ()=default

	TypedMailbox (const TypedMailbox &)=delete

TypedMailbox &	operator= (const TypedMailbox &)=delete

	TypedMailbox (TypedMailbox &&) noexcept=default

TypedMailbox &	operator= (TypedMailbox &&) noexcept=default

auto	start () -> MailboxResult< void >

void	stop ()

bool	is_running () const

uint32_t	mailbox_id () const

template<typename PayloadT >
auto	send (PayloadT &message, uint32_t dest_mailbox) -> MailboxResult< void >
	Send a message (type-restricted)

template<typename PayloadT >
auto	send (PayloadT &message, uint32_t dest_mailbox, uint64_t timestamp) -> MailboxResult< void >
	Send a message with explicit timestamp (type-restricted)

template<typename PayloadT >
auto	send (const TimsMessage< PayloadT > &tims_message, uint32_t dest_mailbox) -> MailboxResult< void >
	Send a TimsMessage (type-restricted)

template<typename PayloadT >
auto	receive () -> MailboxResult< TimsMessage< PayloadT > >
	Blocking receive for specific payload type.

template<typename PayloadT >
auto	receive_for (std::chrono::milliseconds timeout) -> MailboxResult< TimsMessage< PayloadT > >
	Receive with timeout for specific payload type.

template<typename PayloadT >
auto	try_receive () -> MailboxResult< TimsMessage< PayloadT > >
	Non-blocking receive (type-restricted)

template<typename Visitor >
auto	receive_any (Visitor &&visitor) -> MailboxResult< void >
	Blocking receive any allowed message type using visitor pattern.

template<typename Visitor >
auto	receive_any_for (std::chrono::milliseconds timeout, Visitor &&visitor) -> MailboxResult< void >
	Receive any allowed message type with timeout.

auto &	get_underlying_mailbox ()
	Receive any allowed message using a visitor.

const auto &	get_underlying_mailbox () const

Static Public Member Functions
template<typename PayloadT >
static constexpr bool	is_allowed ()
	Check if a payload type is allowed in this mailbox.

Static Public Attributes
static constexpr size_t	max_message_size
	Maximum message size for allowed types only.

static constexpr size_t	num_allowed_types = sizeof...(AllowedPayloadTypes)

Detailed Description

template<typename Registry, typename... AllowedPayloadTypes>
class commrat::TypedMailbox< Registry, AllowedPayloadTypes >

Type-restricted mailbox with optimized buffer sizing.

Unlike regular Mailbox which can handle all types in the registry, TypedMailbox is restricted to a specific subset of payload types. This enables:

Memory optimization: Buffer sized for max(AllowedTypes) instead of max(Registry)
Type safety: Compile-time rejection of wrong message types
Documentation: Type signature shows what mailbox handles

Key Feature: Separate receive and send type restrictions!

Buffer sized for AllowedPayloadTypes only (receive types)
Can send AllowedPayloadTypes OR SendOnlyTypes
Receive restricted to AllowedPayloadTypes only

Template Parameters

Registry	Full message registry (MessageRegistry<...>)
AllowedPayloadTypes	Payload types this mailbox can RECEIVE (determines buffer size)
SendOnlyTypes	Additional types that can be SENT but not received (no buffer impact)

Memory Savings Example:

// Registry has: TinyCmd (16B), SmallCmd (24B), HugeData (2048B)
// Registry::max_message_size = 2048 bytes
 
// OLD: Regular mailbox uses 2048 bytes per receive buffer
Mailbox<Registry> cmd_mailbox(config);  // 10 slots × 2048B = 20,480B
 
// NEW: TypedMailbox uses 24 bytes per receive buffer (max of allowed types)
TypedMailbox<Registry, TinyCmd, SmallCmd> cmd_mailbox(config);  // 10 slots × 24B = 240B
// SAVINGS: 20,240 bytes (98.8%)!

Usage Example:

using MyRegistry = MessageRegistry<
    MessageDefinition<ResetCmd, ...>,
    MessageDefinition<CalibrateCmd, ...>,
    MessageDefinition<SensorData, ...>
>;
 
// CMD mailbox only handles commands
TypedMailbox<MyRegistry, ResetCmd, CalibrateCmd> cmd_mailbox(config);
 
// DATA mailbox only handles sensor data
TypedMailbox<MyRegistry, SensorData> data_mailbox(config);
 
// Send/receive work as usual
cmd_mailbox.send(ResetCmd{}, dest);
auto result = cmd_mailbox.receive<ResetCmd>();
 
// Compile error: SensorData not allowed in cmd_mailbox
// cmd_mailbox.send(SensorData{}, dest);  // static_assert fails!

Definition at line 82 of file typed_mailbox.hpp.

Constructor & Destructor Documentation

◆ TypedMailbox() [1/3]

template<typename Registry , typename... AllowedPayloadTypes>

commrat::TypedMailbox< Registry, AllowedPayloadTypes >::TypedMailbox ( const MailboxConfig & config )

inlineexplicit

Construct a typed mailbox.

Parameters

config Mailbox configuration (buffer sizes optimized automatically)

Definition at line 146 of file typed_mailbox.hpp.

◆ ~TypedMailbox()

template<typename Registry , typename... AllowedPayloadTypes>

commrat::TypedMailbox< Registry, AllowedPayloadTypes >::~TypedMailbox ( )

default

◆ TypedMailbox() [2/3]

template<typename Registry , typename... AllowedPayloadTypes>

commrat::TypedMailbox< Registry, AllowedPayloadTypes >::TypedMailbox ( const TypedMailbox< Registry, AllowedPayloadTypes > & )

delete

◆ TypedMailbox() [3/3]

template<typename Registry , typename... AllowedPayloadTypes>

commrat::TypedMailbox< Registry, AllowedPayloadTypes >::TypedMailbox ( TypedMailbox< Registry, AllowedPayloadTypes > && )

defaultnoexcept

Member Function Documentation

◆ get_underlying_mailbox() [1/2]

template<typename Registry , typename... AllowedPayloadTypes>

auto & commrat::TypedMailbox< Registry, AllowedPayloadTypes >::get_underlying_mailbox ( )

inline

Receive any allowed message using a visitor.

The visitor will be called with the received message if its type is in AllowedPayloadTypes. Otherwise returns error.

Parameters

visitor Callable that accepts any allowed message type

Returns: Success or error

Example:

typed_mailbox.receive_any([](auto&& msg) {
    using MsgType = std::decay_t<decltype(msg.message)>;
    if constexpr (std::is_same_v<MsgType, ResetCmd>) {
        std::cout << "Reset command\n";
    } else if constexpr (std::is_same_v<MsgType, CalibrateCmd>) {
        std::cout << "Calibrate command\n";
    }
    // Only AllowedPayloadTypes will match
});

Get reference to underlying RegistryMailbox

Needed for interop with legacy code that expects RegistryMailbox*. Use with caution - bypasses type restrictions!

Definition at line 389 of file typed_mailbox.hpp.

◆ get_underlying_mailbox() [2/2]

template<typename Registry , typename... AllowedPayloadTypes>

const auto & commrat::TypedMailbox< Registry, AllowedPayloadTypes >::get_underlying_mailbox ( ) const

inline

Definition at line 390 of file typed_mailbox.hpp.

◆ is_allowed()

template<typename Registry , typename... AllowedPayloadTypes>

template<typename PayloadT >

static constexpr bool commrat::TypedMailbox< Registry, AllowedPayloadTypes >::is_allowed ( )

inlinestaticconstexpr

Check if a payload type is allowed in this mailbox.

Definition at line 134 of file typed_mailbox.hpp.

◆ is_running()

template<typename Registry , typename... AllowedPayloadTypes>

bool commrat::TypedMailbox< Registry, AllowedPayloadTypes >::is_running ( ) const

inline

Definition at line 177 of file typed_mailbox.hpp.

◆ mailbox_id()

template<typename Registry , typename... AllowedPayloadTypes>

uint32_t commrat::TypedMailbox< Registry, AllowedPayloadTypes >::mailbox_id ( ) const

inline

Definition at line 181 of file typed_mailbox.hpp.

◆ operator=() [1/2]

template<typename Registry , typename... AllowedPayloadTypes>

TypedMailbox & commrat::TypedMailbox< Registry, AllowedPayloadTypes >::operator= ( const TypedMailbox< Registry, AllowedPayloadTypes > & )

delete

◆ operator=() [2/2]

template<typename Registry , typename... AllowedPayloadTypes>

TypedMailbox & commrat::TypedMailbox< Registry, AllowedPayloadTypes >::operator= ( TypedMailbox< Registry, AllowedPayloadTypes > && )

defaultnoexcept

◆ receive()

template<typename Registry , typename... AllowedPayloadTypes>

template<typename PayloadT >

auto commrat::TypedMailbox< Registry, AllowedPayloadTypes >::receive ( ) -> MailboxResult<TimsMessage<PayloadT>>

inline

Blocking receive for specific payload type.

Template Parameters

PayloadT Payload type (must be in AllowedPayloadTypes)

Returns: Received message or error

Definition at line 289 of file typed_mailbox.hpp.

◆ receive_any()

template<typename Registry , typename... AllowedPayloadTypes>

template<typename Visitor >

auto commrat::TypedMailbox< Registry, AllowedPayloadTypes >::receive_any ( Visitor && visitor ) -> MailboxResult<void>

inline

Blocking receive any allowed message type using visitor pattern.

Template Parameters

Visitor Callable accepting TimsMessage<T> for any allowed T

Returns: Success or error

Definition at line 336 of file typed_mailbox.hpp.

◆ receive_any_for()

template<typename Registry , typename... AllowedPayloadTypes>

template<typename Visitor >

auto commrat::TypedMailbox< Registry, AllowedPayloadTypes >::receive_any_for	(	std::chrono::milliseconds	timeout,
		Visitor &&	visitor
	)		-> MailboxResult<void>

inline

Receive any allowed message type with timeout.

Template Parameters

Visitor Callable accepting TimsMessage<T> for any allowed T

Parameters

timeout Maximum time to wait

Returns: Success or error

Definition at line 348 of file typed_mailbox.hpp.

◆ receive_for()

template<typename Registry , typename... AllowedPayloadTypes>

template<typename PayloadT >

auto commrat::TypedMailbox< Registry, AllowedPayloadTypes >::receive_for ( std::chrono::milliseconds timeout ) -> MailboxResult<TimsMessage<PayloadT>>

inline

Receive with timeout for specific payload type.

Template Parameters

PayloadT Payload type (must be in AllowedPayloadTypes)

Parameters

timeout Maximum time to wait

Returns: Received message or error

Definition at line 306 of file typed_mailbox.hpp.

◆ send() [1/3]

template<typename Registry , typename... AllowedPayloadTypes>

template<typename PayloadT >

auto commrat::TypedMailbox< Registry, AllowedPayloadTypes >::send	(	const TimsMessage< PayloadT > &	tims_message,
		uint32_t	dest_mailbox
	)		-> MailboxResult<void>

inline

Send a TimsMessage (type-restricted)

Definition at line 266 of file typed_mailbox.hpp.

◆ send() [2/3]

template<typename Registry , typename... AllowedPayloadTypes>

template<typename PayloadT >

auto commrat::TypedMailbox< Registry, AllowedPayloadTypes >::send	(	PayloadT &	message,
		uint32_t	dest_mailbox
	)		-> MailboxResult<void>

inline

Send a message (type-restricted)

Template Parameters

PayloadT Payload type (must be in AllowedPayloadTypes)

Parameters

message	Message to send
dest_mailbox	Destination mailbox ID

Returns: Success or error

Compile-time validation:

PayloadT must be in AllowedPayloadTypes (static_assert)
Helpful error message if wrong type used

Definition at line 202 of file typed_mailbox.hpp.

References commrat::TimsMessage< PayloadT >::header, and commrat::TimsHeader::msg_type.

◆ send() [3/3]

template<typename Registry , typename... AllowedPayloadTypes>

template<typename PayloadT >

auto commrat::TypedMailbox< Registry, AllowedPayloadTypes >::send	(	PayloadT &	message,
		uint32_t	dest_mailbox,
		uint64_t	timestamp
	)		-> MailboxResult<void>

inline

Send a message with explicit timestamp (type-restricted)

Template Parameters

PayloadT Payload type (must be in AllowedPayloadTypes)

Parameters

message	Message to send
dest_mailbox	Destination mailbox ID
timestamp	Explicit timestamp to set in TimsHeader

Returns: Success or error

Definition at line 237 of file typed_mailbox.hpp.

References commrat::TimsMessage< PayloadT >::header, and commrat::TimsHeader::msg_type.

◆ start()

template<typename Registry , typename... AllowedPayloadTypes>

auto commrat::TypedMailbox< Registry, AllowedPayloadTypes >::start ( ) -> MailboxResult<void>

inline

Definition at line 169 of file typed_mailbox.hpp.

◆ stop()

template<typename Registry , typename... AllowedPayloadTypes>

void commrat::TypedMailbox< Registry, AllowedPayloadTypes >::stop ( )

inline

Definition at line 173 of file typed_mailbox.hpp.

◆ try_receive()

template<typename Registry , typename... AllowedPayloadTypes>

template<typename PayloadT >

auto commrat::TypedMailbox< Registry, AllowedPayloadTypes >::try_receive ( ) -> MailboxResult<TimsMessage<PayloadT>>

inline

Non-blocking receive (type-restricted)

Template Parameters

PayloadT Payload type (must be in AllowedPayloadTypes)

Returns: Received message or TIMEOUT error if no message available

Definition at line 321 of file typed_mailbox.hpp.

Member Data Documentation

◆ max_message_size

template<typename Registry , typename... AllowedPayloadTypes>

constexpr size_t commrat::TypedMailbox< Registry, AllowedPayloadTypes >::max_message_size

staticconstexpr

Initial value:

=

Registry::template max_size_for_types<AllowedPayloadTypes...>()

Maximum message size for allowed types only.

This is the key optimization: buffer sized for max(AllowedPayloadTypes) instead of max(all registry types).

Definition at line 125 of file typed_mailbox.hpp.

◆ num_allowed_types

template<typename Registry , typename... AllowedPayloadTypes>

constexpr size_t commrat::TypedMailbox< Registry, AllowedPayloadTypes >::num_allowed_types = sizeof...(AllowedPayloadTypes)

staticconstexpr

Definition at line 128 of file typed_mailbox.hpp.

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

commrat/mailbox/typed_mailbox.hpp

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ TypedMailbox() [1/3]

◆ ~TypedMailbox()

◆ TypedMailbox() [2/3]

◆ TypedMailbox() [3/3]

Member Function Documentation

◆ get_underlying_mailbox() [1/2]

◆ get_underlying_mailbox() [2/2]

◆ is_allowed()

◆ is_running()

◆ mailbox_id()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ receive()

◆ receive_any()

◆ receive_any_for()

◆ receive_for()

◆ send() [1/3]

◆ send() [2/3]

◆ send() [3/3]

◆ start()

◆ stop()

◆ try_receive()

Member Data Documentation

◆ max_message_size

◆ num_allowed_types