Abstract base class for messages exchanged between nodes. More...

#include <dfx-core/messages/Message.hpp>

Inheritance diagram for dfx::Core::Message:

Public Member Functions
	DISABLE_COPY_AND_MOVE (Message)
	Messages are non-copyable and non-movable.
virtual	~Message ()
	Virtual destructor.
template<typename Clock = std::chrono::steady_clock> requires std::chrono::is_clock_v<Clock>
std::chrono::time_point< Clock, std::chrono::microseconds >	timestampToTimePoint () const noexcept
	Convert timestamp() into a time_point of the given clock type.
void	addToPathTaken (std::string path)
	Append one hop to the message path trace.
virtual Kind	kind () const =0
	Connectivity domain of this message (data/control "network").
virtual MessagePtr	clone () const =0
	Clone this message (polymorphic deep copy).
template<DerivedFromMessage T>
bool	is () const noexcept
	Check whether this message is of a given derived type.
template<DerivedFromMessage T>
T &	as () noexcept
	Cast this message to a derived type (unchecked).
template<DerivedFromMessage T>
T const &	as () const noexcept
	Cast this message to a derived type (unchecked).
Introspection
Utils::UUID const &	uuid () const noexcept
	Unique identifier of this message instance.
Utils::UUID const &	parentUuid () const noexcept
	UUID of the parent message if created from one, otherwise default UUID value.
std::vector< std::string > const &	pathTaken () const noexcept
	Sequence of "node.port" hops this message has traversed.
std::chrono::microseconds	timestamp () const noexcept
	Construction timestamp in microseconds since timestampClock epoch. This is not "wall clock time" unless timestampClock is CLOCK_REALTIME.
MIME type
bool	hasMimeType () const noexcept
	Whether the message carries an explicit MIME type.
MimeType	mimeType () const noexcept
	Get the message MIME type. If no explicit MIME type is set, returns dfx::Core::MimeType::OctetStream.
void	setMimeType (MimeType mimeType)
	Set the message MIME type.
void	resetMimeType ()
	Clear the explicit MIME type (message then defaults to octet-stream).

Static Public Member Functions
template<DerivedFromMessage T, typename ... Args>
static std::unique_ptr< T >	create (Args &&... args)
	Convenience allocator for derived message types.

Static Public Attributes
static clockid_t	timestampClock
	Clock used by the constructor to capture timestamps.

Protected Member Functions
virtual void	cloneFromBase (Message const &base)
	Copy the base-class state from another message.
	Message (MessagePtr const &parent=nullptr)
	Construct a message, optionally inheriting state from a parent message.
	Message (MimeType mimeType, MessagePtr const &parent=nullptr)
	Construct a message with an explicit MIME type, optionally inheriting from a parent.

Detailed Description

Abstract base class for messages exchanged between nodes.

Identity (UUID / parent UUID): Each message instance gets a UUID at construction time (uuid()). When a message is created with a parent message (see constructors), the new message records the parent's UUID as parentUuid(), and also inherits the parent's MIME type.

Timestamp: A timestamp is captured at construction using clock_gettime() with the clock specified by timestampClock (defaults to CLOCK_REALTIME).

The timestamp is stored as microseconds since the selected clock epoch and can be converted to a time_point via timestampToTimePoint.

Path tracing: Messages carry a vector of strings representing the route they took through the graph. Typical entries are "nodeName.portName". Nodes/ports append to it using addToPathTaken. This is used for debugging, tracing, and diagnostics.

MIME type semantics

The base stores an optional MIME type:

hasMimeType reports whether an explicit MIME type is present.
mimeType returns the explicit value if present, otherwise defaults to dfx::Core::MimeType::OctetStream (application/octet-stream).

The wildcard MIME type dfx::Core::MimeType::Any is forbidden on messages:

setMimeType asserts if passed Any.
The constructor overload taking a MIME type asserts if passed Any.

This is intentional: Any is used for ports as a "don’t care / negotiable" value, while messages must carry a concrete type (or implicitly default to octet-stream).

Cloning contract: clone() must allocate a new message of the same dynamic type. Derived implementations should copy base fields using cloneFromBase.

Note: Base cloning keeps the UUID identical (the clone represents the same logical message). Channel fan-out relies on message cloning to provide independent message instances for each delivery.

Constructor & Destructor Documentation

◆ ~Message()

virtual dfx::Core::Message::~Message ( )

virtual

Virtual destructor.

◆ Message() [1/2]

dfx::Core::Message::Message ( MessagePtr const & parent = nullptr )

protected

Construct a message, optionally inheriting state from a parent message.

Captures a timestamp and generates a new UUID.

If parent is non-null:

parentUuid() becomes the parent's UUID
MIME type (if any) is inherited

Parameters

parent Optional parent message (non-owning reference through pointer).

◆ Message() [2/2]

dfx::Core::Message::Message	(	MimeType	mimeType,
		MessagePtr const &	parent = nullptr )

protected

Construct a message with an explicit MIME type, optionally inheriting from a parent.

Equivalent to Message(MessagePtr const&) followed by setMimeType.

Parameters

mimeType	Concrete MIME type to assign (must not be Any, asserted).
parent	Optional parent message.

Member Function Documentation

◆ addToPathTaken()

void dfx::Core::Message::addToPathTaken ( std::string path )

inline

Append one hop to the message path trace.

Parameters

path	Usually formatted as "nodeName.portName".

See also: dfx::Core::InputPort::processMessage; dfx::Core::OutputPort::sendMessage

◆ as() [1/2]

template<DerivedFromMessage T>

T const & dfx::Core::Message::as ( ) const

inlinenoexcept

Cast this message to a derived type (unchecked).

Template Parameters

T	A type derived from Message.

Warning: This uses static_cast. Only call after checking with is.

◆ as() [2/2]

template<DerivedFromMessage T>

T & dfx::Core::Message::as ( )

inlinenoexcept

Cast this message to a derived type (unchecked).

Template Parameters

T	A type derived from Message.

Warning: This uses static_cast. Only call after checking with is.

◆ clone()

virtual MessagePtr dfx::Core::Message::clone ( ) const

pure virtual

Clone this message (polymorphic deep copy).

Base fields should typically be copied using cloneFromBase.

Returns: Newly allocated message of the same dynamic type.

Implemented in dfx::Core::ControlMessage, and dfx::Core::DataMessage.

◆ cloneFromBase()

virtual void dfx::Core::Message::cloneFromBase ( Message const & base )

protectedvirtual

Copy the base-class state from another message.

Copies:

UUID (kept identical)
parent UUID
pathTaken
timestamp
optional MIME type

Intended to be called by derived clone implementations.

Reimplemented in dfx::Core::ControlMessage, and dfx::Core::DataMessage.

◆ create()

template<DerivedFromMessage T, typename ... Args>

std::unique_ptr< T > dfx::Core::Message::create ( Args &&... args )

inlinestatic

Convenience allocator for derived message types.

Template Parameters

T	Concrete message type.

Parameters

args	Constructor arguments forwarded to T.

Returns: std::unique_ptr<T> owning the created message.

◆ DISABLE_COPY_AND_MOVE()

dfx::Core::Message::DISABLE_COPY_AND_MOVE ( Message )

Messages are non-copyable and non-movable.

◆ hasMimeType()

bool dfx::Core::Message::hasMimeType ( ) const

inlinenoexcept

Whether the message carries an explicit MIME type.

◆ is()

template<DerivedFromMessage T>

bool dfx::Core::Message::is ( ) const

inlinenoexcept

Check whether this message is of a given derived type.

Template Parameters

T	A type derived from Message.

◆ kind()

virtual Kind dfx::Core::Message::kind ( ) const

pure virtual

Connectivity domain of this message (data/control "network").

Implemented in dfx::Core::ControlMessage, and dfx::Core::DataMessage.

◆ mimeType()

MimeType dfx::Core::Message::mimeType ( ) const

inlinenoexcept

Get the message MIME type. If no explicit MIME type is set, returns dfx::Core::MimeType::OctetStream.

◆ parentUuid()

Utils::UUID const & dfx::Core::Message::parentUuid ( ) const

inlinenoexcept

UUID of the parent message if created from one, otherwise default UUID value.

◆ pathTaken()

std::vector< std::string > const & dfx::Core::Message::pathTaken ( ) const

inlinenoexcept

Sequence of "node.port" hops this message has traversed.

◆ resetMimeType()

void dfx::Core::Message::resetMimeType ( )

inline

Clear the explicit MIME type (message then defaults to octet-stream).

◆ setMimeType()

void dfx::Core::Message::setMimeType ( MimeType mimeType )

Set the message MIME type.

Parameters

mimeType Concrete MIME type to assign.

Precondition: mimeType must not be dfx::Core::MimeType::Any (asserted).

◆ timestamp()

std::chrono::microseconds dfx::Core::Message::timestamp ( ) const

inlinenoexcept

Construction timestamp in microseconds since timestampClock epoch. This is not "wall clock time" unless timestampClock is CLOCK_REALTIME.

◆ timestampToTimePoint()

template<typename Clock = std::chrono::steady_clock>
requires std::chrono::is_clock_v<Clock>

std::chrono::time_point< Clock, std::chrono::microseconds > dfx::Core::Message::timestampToTimePoint ( ) const

inlinenoexcept

Convert timestamp() into a time_point of the given clock type.

This is a raw conversion: the numeric value is reinterpreted as a time_point for the requested clock; it does not compensate between different clock epochs.

Template Parameters

Clock Any std::chrono clock type.

Returns: time_point whose duration is microseconds and whose value equals timestamp().

◆ uuid()

Utils::UUID const & dfx::Core::Message::uuid ( ) const

inlinenoexcept

Unique identifier of this message instance.

Member Data Documentation

◆ timestampClock

clockid_t dfx::Core::Message::timestampClock

static

Clock used by the constructor to capture timestamps.

Default value is CLOCK_REALTIME. The constructor uses clock_gettime(timestampClock, ...). Changing this affects the meaning/epoch of timestamp().

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

lib/dfx-core/messages/Message.hpp

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~Message()

◆ Message() [1/2]

◆ Message() [2/2]

Member Function Documentation

◆ addToPathTaken()

◆ as() [1/2]

◆ as() [2/2]

◆ clone()

◆ cloneFromBase()

◆ create()

◆ DISABLE_COPY_AND_MOVE()

◆ hasMimeType()

◆ is()

◆ kind()

◆ mimeType()

◆ parentUuid()

◆ pathTaken()

◆ resetMimeType()

◆ setMimeType()

◆ timestamp()

◆ timestampToTimePoint()

◆ uuid()

Member Data Documentation

◆ timestampClock