libcaf  0.13.2
Classes | Typedefs | Enumerations | Functions
caf::io Namespace Reference

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
sizeThe 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
whomActor that should be published at port.
portUnused TCP port.
inThe 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
hostValid hostname or IP address.
portTCP port.
Returns
An actor_ptr to the proxy instance representing a remote actor.
Exceptions
network_errorThrown 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
hostValid hostname or IP address.
portTCP port.
Returns
An actor_ptr to the proxy instance representing a typed remote actor.
Exceptions
network_errorThrown 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
whomActor that should be unpublished at port.
portTCP port.