caf::io Namespace Reference

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

Namespaces
namespace	basp
	Contains all classes and functions for the Binary Actor System Protocol.
namespace	network
	Contains classes and functions used for network abstraction.

Classes
class	abstract_broker
	A broker mediates between actor systems and other components in the network. More...
class	accept_handle
	Generic handle type for managing incoming connections. More...
struct	acceptor_closed_msg
	Signalizes that a broker acceptor has been closed. More...
struct	acceptor_passivated_msg
	Signalizes that an acceptor has entered passive mode. More...
class	basp_broker
	A broker implementation for the Binary Actor System Protocol (BASP). More...
class	broker
	Describes a dynamically typed broker. More...
class	broker_servant
	Base class for scribe and doorman. More...
struct	connection_closed_msg
	Signalizes that a broker connection has been closed. More...
class	connection_handle
	Generic handle type for identifying connections. More...
struct	connection_passivated_msg
	Signalizes that a connection has entered passive mode. More...
struct	data_transferred_msg
	Signalizes that a certain amount of bytes has been written. More...
class	datagram_handle
	Generic handle type for identifying datagram endpoints. More...
struct	datagram_sent_msg
	Signalizes that a datagram with a certain size has been sent. More...
class	datagram_servant
	Manages writing to a datagram sink. More...
struct	datagram_servant_closed_msg
	Signalizes that a datagram endpoint has entered passive mode. More...
struct	datagram_servant_passivated_msg
	Signalizes that a datagram sink has entered passive mode. More...
class	doorman
	Manages incoming connections. More...
class	middleman
	Manages brokers and network backends. More...
class	middleman_actor_impl
	Default implementation of the middleman_actor interface. 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...
struct	new_datagram_msg
	Signalizes that a datagram with a certain size has been sent. More...
class	scribe
	Manages a stream. More...
class	typed_broker
	A typed broker mediates between actor systems and other components in the network. More...

Typedefs
template<class State >
using	stateful_broker = stateful_actor<State, broker>
	Convenience template alias for declaring state-based brokers.
using	datagram_servant_base
using	datagram_servant_ptr = intrusive_ptr<datagram_servant>
using	doorman_base
using	doorman_ptr = intrusive_ptr<doorman>
using	scribe_ptr = intrusive_ptr<scribe>
using	middleman_actor
	A message passing interface for asynchronous networking operations.
using	scribe_base = broker_servant<network::stream_manager, connection_handle, new_data_msg>

Enumerations
enum class	receive_policy_flag : unsigned {   at_least ,   at_most ,   exactly }

Functions
expected< void >	close (actor_system &sys, uint16_t port)
	Closes port port regardless of whether an actor is published to it.
expected< node_id >	connect (actor_system &sys, std::string host, uint16_t port)
	Tries to connect to given node.
behavior	connection_helper (stateful_actor< connection_helper_state > *self, actor b)
middleman_actor	make_middleman_actor (actor_system &sys, actor db)
	Spawns the default implementation for the middleman_actor interface.
expected< uint16_t >	open (actor_system &sys, uint16_t port, const char *in=nullptr, bool reuse=false)
	Tries to open a port for other CAF instances to connect to.
template<class Handle >
expected< uint16_t >	publish (const Handle &whom, uint16_t port, const char *in=nullptr, bool reuse=false)
	Tries to publish whom at port and returns either an error or the bound port.
constexpr unsigned	to_integer (receive_policy_flag x)
std::string	to_string (receive_policy_flag x)
template<class ActorHandle = actor>
expected< ActorHandle >	remote_actor (actor_system &sys, std::string host, uint16_t port)
	Establish a new connection to the actor at host on given port.
template<class Inspector >
bool	inspect (Inspector &f, new_connection_msg &x)
template<class Handle >
expected< void >	unpublish (const Handle &whom, uint16_t port=0)
	Unpublishes whom by closing port or all assigned ports if port == 0.

Variables
constexpr invalid_accept_handle_t	invalid_accept_handle = invalid_accept_handle_t{}
constexpr invalid_connection_handle_t	invalid_connection_handle = invalid_connection_handle_t{}
constexpr invalid_datagram_handle_t	invalid_datagram_handle = invalid_datagram_handle_t{}

Detailed Description

Contains all IO-related classes and functions.

Typedef Documentation

datagram_servant_base

using caf::io::datagram_servant_base

Initial value:

 broker_servant<network::datagram_manager,
                                             datagram_handle, new_datagram_msg>

doorman_base

using caf::io::doorman_base

Initial value:

 broker_servant<network::acceptor_manager, accept_handle,
                                    new_connection_msg>

middleman_actor

using caf::io::middleman_actor

Initial value:

 typed_actor< 
  result<uint16_t>(publish_atom, uint16_t, strong_actor_ptr,
                   std::set<std::string>, std::string, bool),
 
  result<uint16_t>(open_atom, uint16_t, std::string, bool),
 
  result<node_id, strong_actor_ptr, std::set<std::string>>(
    connect_atom, std::string, uint16_t),
 
  result<void>(unpublish_atom, actor_addr, uint16_t),
 
  result<void>(close_atom, uint16_t),
 
  result<strong_actor_ptr>(spawn_atom, node_id, std::string, message,
                           std::set<std::string>),
 
  result<node_id, std::string, uint16_t>(get_atom, node_id)>

A message passing interface for asynchronous networking operations.

The interface implements the following pseudo code.

interface middleman_actor {
 
  // 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.
  // port: Unused TCP port or 0 for any.
  // whom: Actor that should be published at given port.
  // ifs: Interface of given actor.
  // addr: IP address to listen to or empty for any.
  // reuse:_addr: Enables or disables SO_REUSEPORT option.
  (publish_atom, uint16_t port, strong_actor_ptr whom,
   set<string> ifs, string addr, bool reuse_addr)
  -> (uint16_t)
 
  // Opens a new port other CAF instances can connect to. The
  // difference between `PUBLISH` and `OPEN` is that no actor is mapped to
  // this port, meaning that connecting nodes only get a valid `node_id`
  // handle when connecting.
  // port: Unused TCP port or 0 for any.
  // addr: IP address to listen to or empty for any.
  // reuse:_addr: Enables or disables SO_REUSEPORT option.
  (open_atom, uint16_t port, string addr, bool reuse_addr)
  -> (uint16_t)
 
  // Queries a remote node and returns an ID to this node as well as
  // an `strong_actor_ptr` to a remote actor if an actor was published at
  this
  // port. The actor address must be cast to either `actor` or
  // `typed_actor` using `actor_cast` after validating `ifs`.
  // hostname: IP address or DNS hostname.
  // port: TCP port.
  (connect_atom, string hostname, uint16_t port)
  -> (node_id nid, strong_actor_ptr remote_actor, set<string> ifs)
 
  // Closes `port` if it is mapped to `whom`.
  // whom: A published actor.
  // port: Used TCP port.
  (unpublish_atom, strong_actor_ptr whom, uint16_t port)
  -> void
 
  // Unconditionally closes `port`, removing any actor
  // published at this port.
  // port: Used TCP port.
  (close_atom, uint16_t port)
  -> void
 
  // Spawns an actor on a remote node, initializing it using the arguments
  // stored in `msg` and returns the address of the spawned actor and its
  // interface description on success; an error string otherwise.
  // nid: ID of the remote node that should spawn the actor.
  // name: Announced type name of the actor.
  // args: Initialization arguments for the actor.
  (spawn_atom, node_id nid, string name, message args)
  -> (strong_actor_ptr, set<string>)
 
}

Function Documentation

connect()

expected< node_id > caf::io::connect	(	actor_system &	sys,
		std::string	host,
		uint16_t	port )

Tries to connect to given node.

Attention

This feature is experimental.

open()

expected< uint16_t > caf::io::open	(	actor_system &	sys,
		uint16_t	port,
		const char *	in = nullptr,
		bool	reuse = false )

Tries to open a port for other CAF instances to connect to.

Attention

This feature is experimental.

publish()

template<class Handle >

expected< uint16_t > caf::io::publish	(	const Handle &	whom,
		uint16_t	port,
		const char *	in = nullptr,
		bool	reuse = false )

Tries to publish whom at port and returns either an error or the bound port.

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.
reuse	Create socket using SO_REUSEADDR.

Returns

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

remote_actor()

template<class ActorHandle = actor>

expected< ActorHandle > caf::io::remote_actor	(	actor_system &	sys,
		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 to the proxy instance representing a remote actor or an error.

unpublish()

template<class Handle >

expected< 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.