Contains all network-related classes and functions. More...

Classes
class	accept_handle
	Generic handle type for managing incoming connections. More...

struct	acceptor_closed_msg
	Signalizes that a broker acceptor has been closed. More...

class	basp_broker
	A broker implementation for the Binary Actor System Protocol (BASP). More...

class	broker
	A broker mediates between actor systems and other components in the network. More...

struct	connection_closed_msg
	Signalizes that a broker connection has been closed. More...

class	connection_handle
	Generic handle type for identifying connections. More...

class	hook
	Interface to define hooks into the IO layer. More...

class	middleman
	Manages brokers and network backends. More...

struct	new_connection_msg
	Signalizes a newly accepted connection from a broker. More...

struct	new_data_msg
	Signalizes newly arrived data for a broker. More...

Typedefs
using	broker_ptr = intrusive_ptr< broker >

using	middleman_actor = typed_actor< replies_to< put_atom, actor_addr, uint16_t, std::string, bool >::with_either< ok_atom, uint16_t >::or_else< error_atom, std::string >, replies_to< put_atom, actor_addr, uint16_t, std::string >::with_either< ok_atom, uint16_t >::or_else< error_atom, std::string >, replies_to< put_atom, actor_addr, uint16_t, bool >::with_either< ok_atom, uint16_t >::or_else< error_atom, std::string >, replies_to< put_atom, actor_addr, uint16_t >::with_either< ok_atom, uint16_t >::or_else< error_atom, std::string >, replies_to< get_atom, std::string, uint16_t >::with_either< ok_atom, actor_addr >::or_else< error_atom, std::string >, replies_to< get_atom, std::string, uint16_t, std::set< std::string >>::with_either< ok_atom, actor_addr >::or_else< error_atom, std::string >, replies_to< delete_atom, actor_addr >::with_either< ok_atom >::or_else< error_atom, std::string >, replies_to< delete_atom, actor_addr, uint16_t >::with_either< ok_atom >::or_else< error_atom, std::string >>
	A message passing interface for asynchronous networking operations. More...

Enumerations
enum	receive_policy_flag { at_least, at_most, exactly }

Functions
void	max_msg_size (size_t size)
	Sets the maximum size of a message over network. More...

size_t	max_msg_size ()
	Queries the maximum size of messages over network. More...

middleman_actor	get_middleman_actor ()
	Returns a handle for asynchronous networking operations.

uint16_t	publish_impl (abstract_actor_ptr whom, uint16_t port, const char *in, bool reuse_addr)

uint16_t	publish (caf::actor whom, uint16_t port, const char *in=nullptr, bool reuse_addr=false)
	Publishes `whom` at `port`. More...

template<class... Sigs>
uint16_t	typed_publish (typed_actor< Sigs...> whom, uint16_t port, const char *in=nullptr, bool reuse_addr=false)

uint16_t	publish_local_groups (uint16_t port, const char *addr=nullptr)
	Makes all local groups accessible via network on address `addr` and `port`. More...

abstract_actor_ptr	remote_actor_impl (std::set< std::string > ifs, const std::string &host, uint16_t port)

actor	remote_actor (const std::string &host, uint16_t port)
	Establish a new connection to the actor at `host` on given `port`. More...

template<class ActorHandle >
ActorHandle	typed_remote_actor (const std::string &host, uint16_t port)
	Establish a new connection to the typed actor at `host` on given `port`. More...

group	remote_group (const std::string &group_uri)
	<group-name><host>:<port>

group	remote_group (const std::string &group_identifier, const std::string &host, uint16_t port)

template<spawn_options Os = no_spawn_options, class F = std::function<void(broker*)>, class... Ts>
actor	spawn_io (F fun, Ts &&...xs)
	Spawns a new functor-based broker.

template<spawn_options Os = no_spawn_options, class F = std::function<void(broker*)>, class... Ts>
actor	spawn_io_client (F fun, const std::string &host, uint16_t port, Ts &&...xs)
	Spawns a new functor-based broker connecting to `host:port`.

template<spawn_options Os = no_spawn_options, class F = std::function<void(broker*)>, class... Ts>
actor	spawn_io_server (F fun, uint16_t port, Ts &&...xs)
	Spawns a new broker as server running on given `port`.

void	unpublish_impl (const actor_addr &whom, uint16_t port, bool block_caller)

template<class Handle >
void	unpublish (const Handle &whom, uint16_t port=0)
	Unpublishes `whom` by closing `port` or all assigned ports if `port == 0`. More...

Detailed Description

Contains all network-related classes and functions.

Typedef Documentation

using caf::io::middleman_actor = typedef typed_actor< replies_to<put_atom, actor_addr, uint16_t, std::string, bool> ::with_either<ok_atom, uint16_t> ::or_else<error_atom, std::string>, replies_to<put_atom, actor_addr, uint16_t, std::string> ::with_either<ok_atom, uint16_t> ::or_else<error_atom, std::string>, replies_to<put_atom, actor_addr, uint16_t, bool> ::with_either<ok_atom, uint16_t> ::or_else<error_atom, std::string>, replies_to<put_atom, actor_addr, uint16_t> ::with_either<ok_atom, uint16_t> ::or_else<error_atom, std::string>, replies_to<get_atom, std::string, uint16_t> ::with_either<ok_atom, actor_addr> ::or_else<error_atom, std::string>, replies_to<get_atom, std::string, uint16_t, std::set<std::string>> ::with_either<ok_atom, actor_addr> ::or_else<error_atom, std::string>, replies_to<delete_atom, actor_addr> ::with_either<ok_atom> ::or_else<error_atom, std::string>, replies_to<delete_atom, actor_addr, uint16_t> ::with_either<ok_atom> ::or_else<error_atom, std::string>>

A message passing interface for asynchronous networking operations.

The interface implements the following pseudo code.

using put_result =
  either (ok_atom, uint16_t port)
  or     (error_atom, string error_string);
using get_result =
  either (ok_atom, actor_addr remote_address)
  or     (error_atom, string error_string);
using delete_result =
  either (ok_atom)
  or     (error_atom, string error_string);
interface middleman_actor {
  (put_atom, actor_addr whom, uint16_t port, string addr, bool reuse_addr)
  -> put_result;
  (put_atom, actor_addr whom, uint16_t port, string addr)
  -> put_result;
  (put_atom, actor_addr whom, uint16_t port, bool reuse_addr)
  -> put_result;
  (put_atom, actor_addr whom, uint16_t port)
  -> put_result;
  (get_atom, string hostname, uint16_t port)
  -> get_result;
  (get_atom, string hostname, uint16_t port, set<string> expected_ifs)
  -> get_result;
  (delete_atom, actor_addr whom)
  -> delete_result;
  (delete_atom, actor_addr whom, uint16_t port)
  -> delete_result;
}

The middleman_actor actor offers the following operations:

PUT establishes a new port <-> actor mapping and returns the actual port in use on success. Passing 0 as port instructs the OS to choose the next high-level port available for binding.

Type	Name	Parameter Description
put_atom		Identifies `PUT` operations.
actor_addr	whom	Actor that should be published at given port.
uint16_t	port	Unused TCP port or 0 for any.
string	addr	Optional; IP address to listen to or `INADDR_ANY`
bool	reuse_addr	Optional; enable SO_REUSEPORT option

GET queries a remote node and returns an actor_addr to the remote actor on success. This handle must be cast to either actor or typed_actor using actor_cast.

Type	Name	Parameter Description
get_atom		Identifies `GET` operations.
string	hostname	Valid hostname or IP address.
uint16_t	port	TCP port.
set<string>	expected_ifs	Optional; Interface of typed remote actor.

DELETE removes either all port <-> actor mappings for an actor or only a single one if the optional port parameter is set.

Type Name Parameter Description

delete_atom Identifies DELETE operations.

actor_addr whom Published actor.

uint16_t port Optional; remove only a single mapping.

Function Documentation

void caf::io::max_msg_size ( size_t size )

Sets the maximum size of a message over network.

Parameters

size	The maximum number of bytes a message may occupy.

size_t caf::io::max_msg_size ( )

Queries the maximum size of messages over network.

Returns: The number maximum number of bytes a message may occupy.

uint16_t caf::io::publish	(	caf::actor	whom,
		uint16_t	port,
		const char *	in = `nullptr`,
		bool	reuse_addr = `false`
	)

Publishes whom at port.

The connection is managed by the middleman.

Parameters

whom	Actor that should be published at `port`.
port	Unused TCP port.
in	The IP address to listen to or `INADDR_ANY` if `in == nullptr`.

Returns: The actual port the OS uses after bind(). If port == 0 the OS chooses a random high-level port.

Exceptions

bind_failure

uint16_t caf::io::publish_local_groups	(	uint16_t	port,
		const char *	addr = `nullptr`
	)

Makes all local groups accessible via network on address addr and port.

Returns: The actual port the OS uses after bind(). If port == 0 the OS chooses a random high-level port.

Exceptions

bind_failure
network_error

actor caf::io::remote_actor	(	const std::string &	host,
		uint16_t	port
	)

Establish a new connection to the actor at host on given port.

Parameters

host	Valid hostname or IP address.
port	TCP port.

Returns: An actor_ptr to the proxy instance representing a remote actor.

Exceptions

network_error Thrown on connection error or when connecting to a typed actor.

template<class... Sigs>

uint16_t caf::io::typed_publish	(	typed_actor< Sigs...>	whom,
		uint16_t	port,
		const char *	in = `nullptr`,
		bool	reuse_addr = `false`
	)

template<class ActorHandle >

ActorHandle caf::io::typed_remote_actor	(	const std::string &	host,
		uint16_t	port
	)

Establish a new connection to the typed actor at host on given port.

Parameters

host	Valid hostname or IP address.
port	TCP port.

Returns: An actor_ptr to the proxy instance representing a typed remote actor.

Exceptions

network_error Thrown on connection error or when connecting to an untyped otherwise unexpected actor.

template<class Handle >

void caf::io::unpublish	(	const Handle &	whom,
		uint16_t	port = `0`
	)

Unpublishes whom by closing port or all assigned ports if port == 0.

Parameters

whom	Actor that should be unpublished at `port`.
port	TCP port.

Type	Name	Parameter Description
delete_atom		Identifies `DELETE` operations.
actor_addr	whom	Published actor.
uint16_t	port	Optional; remove only a single mapping.

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Function Documentation