Messages

constellation::message Namespace

using constellation::message::AssembledMessage = std::array<std::byte, protocol::CHIRP::MESSAGE_LENGTH>

CHIRP message assembled to array of bytes

class BaseHeader

#include <constellation/core/message/BaseHeader.hpp>

Message Header Base Class

Subclassed by constellation::message::CMDP1Message::Header, constellation::message::CSCP1Message::Header

Public Functions

virtual ~BaseHeader() = default

inline protocol::Protocol getProtocol() const

Return message protocol

inline std::string_view getSender() const

Return message sender

inline std::chrono::system_clock::time_point getTime() const

Return message time

inline const config::Dictionary &getTags() const

Return message tags

inline bool hasTag(const std::string &key) const

Return if message has given tag

template<typename T>
inline T getTag(const std::string &key) const

Return message tag

template<typename T>
inline void setTag(const std::string &key, const T &value)

Set message tag

virtual std::string to_string() const

Convert message header to human readable string

virtual void msgpack_pack(msgpack::packer<msgpack::sbuffer> &msgpack_packer) const

Pack message header with msgpack

Protected Functions

inline BaseHeader(protocol::Protocol protocol, std::string sender, std::chrono::system_clock::time_point time, config::Dictionary tags = {})

Construct new message header

Parameters:

• protocol – Message protocol

• sender – Sender name

• time – Message time

• tags – Message tags (defaults to empty dictionary)

Protected Static Functions

static BaseHeader disassemble(protocol::Protocol protocol, std::span<const std::byte> data)

Disassemble message from from bytes

Parameters:

• protocol – Protocol

• data – View to byte data

class CDTP2BORMessage : public constellation::message::CDTP2Message

#include <constellation/core/message/CDTP2Message.hpp>

Class representing a CDTP2 begin-of-run message.

Public Functions

CDTP2BORMessage(std::string sender, config::Dictionary user_tags, const config::Configuration &configuration)

Construct a CDTP2 begin-of-run message.

Parameters:

• sender – Name of the sender

• user_tags – User tags to attach to the message

• configuration – Configuration of the sender

CDTP2BORMessage(CDTP2Message &&message)

Construct a CDTP2 begin-of-run message from a CDTP2 message.

Parameters:

message – CDTP2 message

inline const config::Dictionary &getUserTags() const

Get the user tags of the begin-of-run message.

Returns:

Dictionary containing the user tags

config::Configuration getConfiguration() const

Get the configuration of the sender.

Returns:

Configuration

class CDTP2EORMessage : public constellation::message::CDTP2Message

#include <constellation/core/message/CDTP2Message.hpp>

Class representing a CDTP2 end-of-run message.

Public Functions

CDTP2EORMessage(std::string sender, config::Dictionary user_tags, config::Dictionary run_metadata)

Construct a CDTP2 end-of-run message.

Parameters:

• sender – Name of the sender

• user_tags – User tags to attach to the message

• run_metadata – Run metadata

CDTP2EORMessage(CDTP2Message &&message)

Construct a CDTP2 end-of-run message from a CDTP2 message.

Parameters:

message – CDTP2 message

inline const config::Dictionary &getUserTags() const

Get the user tags of the end-of-run message.

Returns:

Dictionary containing the user tags

inline const config::Dictionary &getRunMetadata() const

Get the run metadata.

Returns:

Dictionary containing the run metadata

class CDTP2Message

#include <constellation/core/message/CDTP2Message.hpp>

Class representing a CDTP2 message.

Subclassed by constellation::message::CDTP2BORMessage, constellation::message::CDTP2EORMessage

Public Types

enum class Type : std::uint8_t

Enum describing the type of the CDTP message.

Values:

enumerator DATA

Message containing data

enumerator BOR

Message containing begin-of-run information

enumerator EOR

Message containing end-of-run information

Public Functions

inline CDTP2Message(std::string sender, Type type, std::size_t blocks = 1)

Construct a CDTP2 message.

Parameters:

• sender – Name of the sender

• type – CDTP message type

• blocks – Optional number of blocks to reserve

inline std::string_view getSender() const

Get the name of the sender.

Returns:

Name of the sender

inline Type getType() const

Get the message type.

Returns:

Message type

inline const std::vector<DataRecord> &getDataRecords() const

Get the data records attached to the message.

Returns:

Vector containing the data records

inline void addDataRecord(DataRecord &&data_record)

Add a data record to the message.

Parameters:

data_record – Data record

std::size_t countPayloadBytes() const

Count the number of payload bytes contained in each data record.

Returns:

Size of the payload in bytes

inline void clearBlocks()

Clear data records attached to message.

zmq::multipart_t assemble() const

Assemble full message for ZeroMQ.

Returns:

ZeroMQ multipart message

Public Static Functions

static CDTP2Message disassemble(zmq::multipart_t &frames)

Disassemble message from ZeroMQ frames.

Parameters:

frames – ZeroMQ frames

Returns:

CDTP2 message

class DataRecord

#include <constellation/core/message/CDTP2Message.hpp>

Data record representing a data point.

Public Functions

DataRecord() = default

inline DataRecord(std::uint64_t sequence_number, config::Dictionary tags, std::size_t blocks = 1)

Constructs a data record.

Parameters:

• sequence_number – Sequence number of the data record

• tags – Dictionary containing metainformation of the data record

• blocks – Optional number of blocks to reserve

inline std::uint64_t getSequenceNumber() const

Get the sequence number of the data record.

Returns:

Sequence number

inline const config::Dictionary &getTags() const

Get the dictionary containing the metainformation of the data record.

Returns:

Tags of the data record

template<typename T>
inline void addTag(const std::string &key, const T &value)

Add a tag to the metainformation of the data record.

Parameters:

• key – Name of the tag

• value – Value of the tag

inline const std::vector<PayloadBuffer> &getBlocks() const

Get the attached blocks of the data record.

Returns:

Vector containing payload blocks

inline void addBlock(PayloadBuffer &&payload)

Add a block to the data record.

Parameters:

payload – Payload buffer to be added as block

inline std::size_t countBlocks() const

Count the number of attached blocks of the data record.

Returns:

Number of attached blocks

std::size_t countPayloadBytes() const

Count the number of bytes contained in the blocks.

Returns:

Size of the payload in bytes

void msgpack_pack(msgpack::packer<msgpack::sbuffer> &msgpack_packer) const

void msgpack_unpack(const msgpack::object &msgpack_object)

class CHIRPMessage

#include <constellation/core/message/CHIRPMessage.hpp>

CHIRP message

Public Functions

CHIRPMessage(protocol::CHIRP::MessageType type, MD5Hash group_id, MD5Hash host_id, protocol::CHIRP::ServiceIdentifier service_id, networking::Port port)

Parameters:

• type – CHIRP message type

• group_id – Constellation group ID (MD5 Hash of group name)

• host_id – Constellation host ID (MD5 Hash of host name)

• service_id – CHIRP service identifier

• port – Service port

CHIRPMessage(protocol::CHIRP::MessageType type, std::string_view group, std::string_view host, protocol::CHIRP::ServiceIdentifier service_id, networking::Port port)

Parameters:

• type – CHIRP message type

• group – Constellation group name (converted to group ID using MD5Hash)

• host – Host name (converted to host ID using MD5Hash)

• service_id – CHIRP service identifier

• port – Service port

inline protocol::CHIRP::MessageType getType() const

Return the message type

inline MD5Hash getGroupID() const

Return the group ID of the message

inline MD5Hash getHostID() const

Return the host ID of the message

inline protocol::CHIRP::ServiceIdentifier getServiceIdentifier() const

Return the service identifier of the message

inline networking::Port getPort() const

Return the service port of the message

AssembledMessage assemble() const

Assemble message to byte array

Public Static Functions

static CHIRPMessage disassemble(std::span<const std::byte> assembled_message)

Constructor for a CHIRP message from an assembled message

Parameters:

assembled_message – View of assembled message

Throws:

DecodeError – If the message header does not match the CHIRP specification, or if the message has an unknown ServiceIdentifier

class CHP1Message

#include <constellation/core/message/CHP1Message.hpp>

Class representing a CHP1 message

Public Functions

inline CHP1Message(std::string sender, protocol::CSCP::State state, std::chrono::milliseconds interval, protocol::CHP::MessageFlags flags = {}, std::optional<std::string> status = {}, std::chrono::system_clock::time_point time = std::chrono::system_clock::now())

Parameters:

• sender – Sender name

• state – State of the sender

• interval – Time interval until next message is expected

• flags – Message flags

• status – Optional status string for the message

• time – Message time

inline protocol::Protocol getProtocol() const

Return message protocol

inline std::string_view getSender() const

Return message sender

inline std::chrono::system_clock::time_point getTime() const

Return message time

inline protocol::CSCP::State getState() const

Return state of the message

inline protocol::CHP::MessageFlags getFlags() const

Return the message flags

inline bool hasFlag(protocol::CHP::MessageFlags flag) const

Check whether this message has a specific flag set

inline bool isExtrasystole() const

Return whether this message is an extraystole

inline protocol::CHP::Role getRole() const

Return role of the sender

inline const std::optional<std::string> &getStatus() const

Return optional status of the message

inline std::chrono::milliseconds getInterval() const

Return maxima time interval until next message is expected

zmq::multipart_t assemble()

Assemble full message to frames for ZeroMQ

Public Static Functions

static CHP1Message disassemble(zmq::multipart_t &frames)

Disassemble message from ZeroMQ frames

This function moves the frames

class CMDP1LogMessage : public constellation::message::CMDP1Message

Subclassed by constellation::gui::QLogMessage

Public Functions

CMDP1LogMessage(log::Level level, std::string log_topic, Header header, std::string message)

Construct a new CMDP1 message for logging

Parameters:

• level – Log level of the message

• log_topic – Log topic of the message (can be empty)

• header – CMDP1 header of the message

• message – Log message

CMDP1LogMessage(CMDP1Message &&message)

Construct a CMDP1LogMessage from a decoded CMDP1Message

Throws:

IncorrectMessageType – If the message is not a (valid) log message

inline log::Level getLogLevel() const

Returns:

Log level of the message

inline std::string_view getLogTopic() const

Returns:

Log topic of the message (might be empty)

std::string_view getLogMessage() const

Returns:

Log message

Public Static Functions

static CMDP1LogMessage disassemble(zmq::multipart_t &frames)

Disassemble log message from ZeroMQ frames

This function moves the payload.

Throws:

• MessageDecodingError – If the message is not a valid CMDP1 message

• IncorrectMessageType – If the message is a valid CMDP1 message but not a (valid) log message

Returns:

New CMDP1LogMessage assembled from ZeroMQ frames

class CMDP1Message

#include <constellation/core/message/CMDP1Message.hpp>

Class representing a CMDP1 message

Subclassed by constellation::message::CMDP1LogMessage, constellation::message::CMDP1Notification, constellation::message::CMDP1StatMessage

Public Functions

inline const Header &getHeader() const

Returns:

Read-only reference to the CMDP1 header of the message

inline Header &getHeader()

Returns:

Reference to the CMDP1 header of the message

inline std::string_view getMessageTopic() const

Returns:

CMDP message topic

std::string getTopic() const

Get topic without CMDP identifier (LOG or STAT)

Returns:

topic

bool isLogMessage() const

Returns:

If the message is a log message

bool isStatMessage() const

Returns:

If the message is a stat message

bool isNotification() const

Returns:

if the message is a notification

zmq::multipart_t assemble()

Assemble full message to frames for ZeroMQ

This function moves the payload.

Returns:

Message assembled to ZeroMQ frames

Public Static Functions

static CMDP1Message disassemble(zmq::multipart_t &frames)

Disassemble message from ZeroMQ frames

This function moves the payload.

Throws:

MessageDecodingError – If the message is not a valid CMDP1 message

Returns:

New CMDP1Message assembled from ZeroMQ frames

Protected Functions

CMDP1Message(std::string topic, Header header, message::PayloadBuffer &&payload)

Construct a new CMDP1 message with payload

Parameters:

• topic – Topic of the message

• header – Header of the message

• payload – Payload of the message

inline const message::PayloadBuffer &get_payload() const

Returns:

Message payload

Protected Static Functions

static log::Level get_log_level_from_topic(std::string_view topic)

Extract the log level from CMDP1 message topic

Parameters:

topic – Topic of the message

Throws:

MessageDecodingError – If not a valid log level

class Header : public constellation::message::BaseHeader

#include <constellation/core/message/CMDP1Message.hpp>

CMDP1 Header

Public Functions

inline Header(std::string sender, std::chrono::system_clock::time_point time = std::chrono::system_clock::now())

Public Static Functions

static inline Header disassemble(std::span<const std::byte> data)

class CMDP1Notification : public constellation::message::CMDP1Message

Public Functions

CMDP1Notification(Header header, std::string id, config::Dictionary topics)

Construct a new CMDP1 message for metrics

Note

The message topic will be taken as the metric name

Parameters:

• header – CMDP1 header of the message

• id – Identifier of notification

• topics – Dictionary with available topics for the given identifier

CMDP1Notification(CMDP1Message &&message)

Construct a CMDP1Notification from a decoded CMDP1Message

Throws:

IncorrectMessageType – If the message is not a (valid) notification

inline const config::Dictionary &getTopics() const

Returns:

List of topics

Public Static Functions

static CMDP1Notification disassemble(zmq::multipart_t &frames)

Disassemble stats message from ZeroMQ frames

This function moves the payload.

Throws:

• MessageDecodingError – If the message is not a valid CMDP1 message

• IncorrectMessageType – If the message is a valid CMDP1 message but not a (valid) stat message

Returns:

New CMDP1Notification assembled from ZeroMQ frames

class CMDP1StatMessage : public constellation::message::CMDP1Message

Public Functions

CMDP1StatMessage(Header header, metrics::MetricValue metric_value)

Construct a new CMDP1 message for metrics

Note

The message topic will be taken as the metric name

Parameters:

• header – CMDP1 header of the message

• metric_value – The metric value to be sent

CMDP1StatMessage(CMDP1Message &&message)

Construct a CMDP1StatMessage from a decoded CMDP1Message

Throws:

IncorrectMessageType – If the message is not a (valid) metrics message

inline const metrics::MetricValue &getMetric() const

Returns:

Metric value

Public Static Functions

static CMDP1StatMessage disassemble(zmq::multipart_t &frames)

Disassemble stats message from ZeroMQ frames

This function moves the payload.

Throws:

• MessageDecodingError – If the message is not a valid CMDP1 message

• IncorrectMessageType – If the message is a valid CMDP1 message but not a (valid) stat message

Returns:

New CMDP1StatMessage assembled from ZeroMQ frames

class CSCP1Message

#include <constellation/core/message/CSCP1Message.hpp>

Class representing a CSCP1 message

Public Types

enum class Type : std::uint8_t

Enum describing the type of CSCP1 message

Values:

enumerator REQUEST

Request with a command

enumerator SUCCESS

Command is being executed

enumerator NOTIMPLEMENTED

Command is valid but not implemented

enumerator INCOMPLETE

Command is valid but mandatory payload information is missing or incorrectly formatted

enumerator INVALID

Command is invalid for the current state

enumerator UNKNOWN

Command is entirely unknown

enumerator ERROR

Previously received message is invalid

Public Functions

CSCP1Message(Header header, std::pair<Type, std::string> verb)

Parameters:

• header – CSCP1 header of the message

• verb – Message verb containing the type and the command/reply string

inline const Header &getHeader() const

Returns:

Read-only reference to the CSCP1 header of the message

inline Header &getHeader()

Returns:

Reference to the CSCP1 header of the message

inline std::pair<Type, std::string_view> getVerb() const

Returns:

Message verb containing the type and the command/reply string

inline const message::PayloadBuffer &getPayload() const

Returns:

Message payload

inline bool hasPayload() const

Returns:

True if message has payload

inline void addPayload(message::PayloadBuffer &&payload)

Parameters:

payload – Payload buffer containing the payload to be added as ZeroMQ message

zmq::multipart_t assemble(bool keep_payload = false)

Assemble full message to frames for ZeroMQ

Parameters:

keep_payload – If true, the payload is kept such that the message can be send again

Returns:

Message assembled to ZeroMQ frames

Public Static Functions

static CSCP1Message disassemble(zmq::multipart_t &frames)

Disassemble message from ZeroMQ frames

This function moves the payload frame if there is one.

Throws:

TODO –

Returns:

New CSCP1Message assembled from ZeroMQ frames

class Header : public constellation::message::BaseHeader

#include <constellation/core/message/CSCP1Message.hpp>

CSCP1 Header

Public Functions

inline Header(std::string sender, std::chrono::system_clock::time_point time = std::chrono::system_clock::now(), config::Dictionary tags = {})

Public Static Functions

static inline Header disassemble(std::span<const std::byte> data)

class IncorrectMessageType : public constellation::utils::RuntimeError

#include <constellation/core/message/exceptions.hpp>

Incorrect message type.

The message type does not match the requested operation

Public Functions

inline explicit IncorrectMessageType(std::string_view why)

class InvalidPayload : public constellation::message::MessageDecodingError

#include <constellation/core/message/exceptions.hpp>

Invalid message payload.

The message payload is invalid and cannot be used

Public Functions

inline explicit InvalidPayload(std::string_view reason)

class InvalidProtocolError : public constellation::message::MessageDecodingError

#include <constellation/core/message/exceptions.hpp>

Invalid protocol identifier.

The message identifier does not represent a valid or known protocol identifier

Public Functions

inline explicit InvalidProtocolError(std::string_view protocol)

class MD5Hash : public std::array<std::uint8_t, 16>

#include <constellation/core/message/CHIRPMessage.hpp>

MD5 hash stored as array with 16 bytes

Public Functions

constexpr MD5Hash() = default

MD5Hash(std::string_view string)

Construct MD5 hash from a string

Parameters:

string – String from which to create the MD5 hash

std::string to_string() const

Convert MD5 hash to an human readable string

Returns:

String containing a lowercase hex representation of the MD5 hash

bool operator<(const MD5Hash &other) const

class MessageDecodingError : public constellation::utils::RuntimeError

#include <constellation/core/message/exceptions.hpp>

Error in decoding the message.

The message cannot be correctly decoded because the format does not adhere to protocol.

Subclassed by constellation::message::InvalidPayload, constellation::message::InvalidProtocolError, constellation::message::UnexpectedProtocolError

Public Functions

inline explicit MessageDecodingError(std::string_view protocol, std::string_view reason)

Protected Functions

MessageDecodingError() = default

class PayloadBuffer

#include <constellation/core/message/PayloadBuffer.hpp>

Buffer holding an arbitrary object that can be turned into a zmq::message_t

This buffer takes ownership of an arbitrary object that owns some memory. The buffer stores the object in an std::any and memory range owned by the object in a span. The buffer features manual memory management to allow for zero-copy message transport with ZeroMQ.

To make the zero-copy mechanism work, the std::any is allocated via new on the heap. This allows to pass a free function to ZeroMQ, which deallocates the std::any via delete. However, to avoid that the std::any is deleted when the buffer goes out of scope, the buffer has to be released. This simply means that it resets the pointer to the std::any such that it does not get deleted in the destructor of the buffer.

Public Functions

template<typename T, typename F>
inline PayloadBuffer(T &&t, F f)

Construct buffer given by moving an arbitrary object.

Note

If T doesn’t construct nicely to an std::any, one possibility is moving it into an std::shared_ptr

Parameters:

• t – L-Value Reference of object T to move into the buffer

• f – Function F that takes a reference of T and returns an std::span<std::byte>

inline PayloadBuffer(zmq::message_t &&msg)

Specialized constructor for zmq::message_t

inline PayloadBuffer(msgpack::sbuffer &&buf)

Specialized constructor for msgpack::sbuffer

template<typename R>
inline PayloadBuffer(R &&range)

Specialized constructor for non-const ranges.

PayloadBuffer() = default

Default constructor (empty payload)

inline ~PayloadBuffer()

Destructor deleting the std::any

inline PayloadBuffer(PayloadBuffer &&other) noexcept

Move constructor taking over other pointer and releasing other buffer.

inline PayloadBuffer &operator=(PayloadBuffer &&other) noexcept

Move assignment freeing the buffer, taking over other pointer and releasing other buffer.

inline std::span<const std::byte> span() const

Read-only access to the data in the buffer.

Returns:

Constant span of the data

inline std::span<std::byte> span()

Write access to the data in the buffer.

Returns:

Non-constant span of the data

inline bool empty() const

Check if the payload is empty.

Returns:

If the span is empty

inline std::string_view to_string_view() const

Interpret data as string.

Note

This function does not ensure that the data in the buffer is actually a string

Returns:

String of the content in the buffer

inline zmq::message_t to_zmq_msg_copy() const

Create a ZeroMQ message by copying the buffer.

Returns:

ZeroMQ message with a copy of the data in the buffer

inline zmq::message_t to_zmq_msg_release()

Create a ZeroMQ message for zero-copy transport.

Note

The buffer will be released after this function, meaning that the buffer cannot be used anymore

Returns:

ZeroMQ message owning the data in the buffer

class UnexpectedProtocolError : public constellation::message::MessageDecodingError

#include <constellation/core/message/exceptions.hpp>

Unexpected protocol identifier.

The protocol identifier of the message does not match the expected protocol

Public Functions

inline explicit UnexpectedProtocolError(protocol::Protocol prot_recv, protocol::Protocol prot_exp)