Classes
struct	caf::io::basp::header
	The header of a Binary Actor System Protocol (BASP) message. More...

class	caf::io::basp::instance
	Describes a protocol instance managing multiple connections. More...

class	caf::io::basp::routing_table
	Stores routing information for a single broker participating as BASP peer and provides both direct and indirect paths. More...

Enumerations
enum	caf::io::basp::connection_state { caf::io::basp::await_header , caf::io::basp::await_payload , caf::io::basp::close_connection , caf::io::basp::incompatible_versions , caf::io::basp::incompatible_application_ids , caf::io::basp::malformed_message , caf::io::basp::serializing_basp_payload_failed , caf::io::basp::redundant_connection , caf::io::basp::no_route_to_receiving_node }
	Denotes the state of a connection between two BASP nodes. More...

enum class	caf::io::basp::message_type : uint8_t { caf::io::basp::message_type::server_handshake = 0x00 , caf::io::basp::message_type::client_handshake = 0x01 , caf::io::basp::message_type::direct_message = 0x02 , caf::io::basp::message_type::routed_message = 0x03 , caf::io::basp::message_type::monitor_message = 0x04 , caf::io::basp::message_type::down_message = 0x05 , caf::io::basp::message_type::heartbeat = 0x06 }
	Describes the first header field of a BASP message and determines the interpretation of the other header fields. More...

Functions
constexpr bool	caf::io::basp::requires_shutdown (connection_state x) noexcept
	Returns whether the connection state requires a shutdown of the socket connection.

sec	caf::io::basp::to_sec (connection_state x) noexcept
	Converts the connection state to a system error code if it holds one of the overlapping values.

bool	caf::io::basp::is_handshake (const header &hdr)
	Checks whether given header contains a handshake.

bool	caf::io::basp::is_heartbeat (const header &hdr)
	Checks whether given header contains a heartbeat.

CAF_IO_EXPORT std::string	caf::io::basp::to_string (message_type)

CAF_IO_EXPORT bool	caf::io::basp::from_string (std::string_view, message_type &)

CAF_IO_EXPORT bool	caf::io::basp::from_integer (std::underlying_type_t< message_type >, message_type &)

template<class Inspector >
bool	caf::io::basp::inspect (Inspector &f, message_type &x)

template<class Inspector >
bool	inspect (Inspector &f, header &x)

CAF_IO_EXPORT bool	valid (const header &hdr)
	Checks whether given BASP header is valid.

Variables
constexpr size_t	header_size
	Size of a BASP header in serialized form.

constexpr uint64_t	caf::io::basp::version = 8
	The current BASP version. Note: BASP is not backwards compatible.

Detailed Description

Protocol Overview

The "Binary Actor System Protocol" (BASP) is not a network protocol. It is a specification for the "Remote Method Invocation" (RMI) interface used by distributed instances of CAF. The purpose of BASP is unify the structure of RMI calls in order to simplify processing and implementation. Hence, BASP is independent of any underlying network technology, and assumes a reliable communication channel.

The RMI interface of CAF enables network-transparent monitoring and linking as well as global message dispatching to actors running on different nodes.

The figure above illustrates the physical as well as the logical view of a distributed CAF application. Note that the actors used for the BASP communication ("BASP Brokers") are not part of the logical system view and are in fact not visible to other actors. A BASP Broker creates proxy actors that represent actors running on different nodes. It is worth mentioning that two instances of CAF running on the same physical machine are considered two different nodes in BASP.

BASP has two objectives:

Forward messages sent to a proxy to the actor it represents

Whenever a proxy instance receives a message, it forwards this message to its parent (a BASP Broker). This message is then serialized and forwarded over the network. If no direct connection between the node sending the message and the node receiving it exists, intermediate BASP Brokers will forward it until it the message reaches its destination.
Synchronize the state of an actor with all of its proxies.

Whenever a node learns the address of a remotely running actor, it creates Ma local proxy instance representing this actor and sends an announce_proxy_instance to the node hosting the actor. Whenever an actor terminates, the hosting node sends down_message messages to all nodes that have a proxy for this actor. This enables network-transparent actor monitoring. There are two possible ways addresses can be learned:
- A client connects to a remotely running (published) actor via remote_actor. In this case, the server_handshake will contain the address of the published actor.
- Receiving dispatch_message. Whenever an actor message arrives, it usually contains the address of the sender. Further, the message itself can contain addresses to other actors that the BASP Broker will get aware of while deserializing the message object from the payload.

Node IDs

The ID of a node consists of a 120 bit hash and the process ID. Note that we use "node" as a synonym for "CAF instance". The hash is generated from "low-level" characteristics of a machine such as the UUID of the root file system and available MAC addresses. The only purpose of the node ID is to generate a network-wide unique identifier. By adding the process ID, CAF disambiguates multiple instances running on the same phyisical machine.

Header Format

Operation ID: 4 bytes.

This field indicates what BASP function this datagram represents. The value is an uint32_t representation of message_type.
Payload Length: 4 bytes.

The length of the data following this header as uint32_t, measured in bytes.
Operation Data: 8 bytes.

This field contains.
Source Node ID: 18 bytes.

The address of the source node. See Node IDs.
Destination Node ID: 18 bytes.

The address of the destination node. See Node IDs. Upon receiving this datagram, a BASP Broker compares this node ID to its own ID. On a mismatch, it selects the next hop and forwards this datagram unchanged.
Source Actor ID: 4 bytes.

This field contains the ID of the sending actor or 0 for anonymously sent messages. The full address of an actor is the combination of the node ID and the actor ID. Thus, every actor can be unambigiously identified by combining these two IDs.
Destination Actor ID: 4 bytes.

This field contains the ID of the receiving actor or 0 for BASP functions that do not require

Example

The following diagram models a distributed application with three nodes. The pseudo code for the application can be found in the three grey boxes, while the resulting BASP messaging is shown in UML sequence diagram notation. More details about individual BASP message types can be found in the documentation of message_type below.

Enumeration Type Documentation

◆ connection_state

enum caf::io::basp::connection_state

Denotes the state of a connection between two BASP nodes.

Overlaps with sec (these states get converted to an error by the BASP instance).

Enumerator
await_header	Indicates that a connection is established and this node is waiting for the next BASP header.
await_payload	Indicates that this node has received a header with non-zero payload and is waiting for the data.
close_connection	Indicates that this connection no longer exists.
incompatible_versions	See `sec::incompatible_versions`.
incompatible_application_ids	See `sec::incompatible_application_ids`.
malformed_message	See `sec::malformed_message`.
serializing_basp_payload_failed	See `sec::serializing_basp_payload_failed`.
redundant_connection	See `sec::redundant_connection`.
no_route_to_receiving_node	See `sec::no_route_to_receiving_node`.

◆ message_type

enum class caf::io::basp::message_type : uint8_t

strong

Describes the first header field of a BASP message and determines the interpretation of the other header fields.

Enumerator
server_handshake	Send from server, i.e., the node with a published actor, to client, i.e., node that initiates a new connection using remote_actor().
client_handshake	Send from client to server after it has successfully received the server_handshake to establish the connection.
direct_message	Transmits a direct message from source to destination.
routed_message	Transmits a message from `source_node:source_actor` to `dest_node:dest_actor`.
monitor_message	Informs the receiving node that the sending node has created a proxy instance for one of its actors. Causes the receiving node to attach a functor to the actor that triggers a down_message on termination.
down_message	Informs the receiving node that it has a proxy for an actor that has been terminated.
heartbeat	Used to generate periodic traffic between two nodes in order to detect disconnects.