actor-framework
Classes | Public Types | Public Member Functions | Friends | List of all members
caf::actor_system Class Reference

Actor environment including scheduler, registry, and optional components such as a middleman. More...

#include <actor_system.hpp>

Inheritance diagram for caf::actor_system:
Inheritance graph
[legend]

Classes

struct  actor_metric_families_t
 Metrics that some actors may collect in addition to the base metrics. More...
 
struct  base_metrics_t
 Metrics that the actor system collects by default. More...
 
class  global_state_guard
 Calls a cleanup function in its destructor for cleaning up global state. More...
 
class  impl
 
class  networking_module
 An (optional) component of the actor system with networking capabilities. More...
 

Public Types

using mpi = std::set< std::string >
 A message passing interface (MPI) in run-time checkable representation.
 

Public Member Functions

 actor_system (const actor_system &)=delete
 
actor_systemoperator= (const actor_system &)=delete
 
 actor_system (actor_system_config &cfg)
 
template<class T , class E = std::enable_if_t<!is_typed_actor_v<T>>>
mpi message_types (type_list< T >) const
 
template<class... Ts>
mpi message_types (type_list< typed_actor< Ts... >>) const
 
template<class T , class E = std::enable_if_t<!detail::is_type_list_v<T>>>
mpi message_types (const T &) const
 
template<class T >
mpi message_types () const
 Returns a string representation of the messaging interface using portable names;.
 
bool assignable (const mpi &xs, const mpi &ys) const
 Returns whether actor handles described by xs can be assigned to actor handles described by ys. More...
 
template<class T >
bool assignable (const std::set< std::string > &xs) const
 Returns whether actor handles described by xs can be assigned to actor handles of type T. More...
 
base_metrics_tbase_metrics () noexcept
 
const base_metrics_tbase_metrics () const noexcept
 
const actor_metric_families_tactor_metric_families () const noexcept
 
detail::global_meta_objects_guard_type meta_objects_guard () const noexcept
 Returns the global meta objects guard.
 
span< const std::string > metrics_actors_includes () const noexcept
 Returns the caf.metrics-filters.actors.includes parameter.
 
span< const std::string > metrics_actors_excludes () const noexcept
 Returns the caf.metrics-filters.actors.excludes parameter.
 
const actor_system_configconfig () const
 Returns the configuration of this actor system.
 
actor_clockclock () noexcept
 Returns the system-wide clock.
 
size_t detached_actors () const noexcept
 Returns the number of detached actors.
 
bool await_actors_before_shutdown () const
 Returns whether this actor system calls await_all_actors_done in its destructor before shutting down. More...
 
void await_actors_before_shutdown (bool new_value)
 Configures whether this actor system calls await_all_actors_done in its destructor before shutting down. More...
 
const strong_actor_ptrspawn_serv () const
 Returns the internal actor for dynamic spawn operations.
 
const strong_actor_ptrconfig_serv () const
 Returns the internal actor for storing the runtime configuration for this actor system. More...
 
telemetry::metric_registrymetrics () noexcept
 Returns the metrics registry for this system.
 
const telemetry::metric_registrymetrics () const noexcept
 Returns the metrics registry for this system.
 
const node_idnode () const
 Returns the host-local identifier for this system.
 
caf::schedulerscheduler ()
 Returns the scheduler instance.
 
caf::loggerlogger ()
 Returns the system-wide event logger.
 
actor_registryregistry ()
 Returns the system-wide actor registry.
 
bool has_middleman () const
 Returns true if the I/O module is available, false otherwise.
 
io::middlemanmiddleman ()
 Returns the middleman instance from the I/O module. More...
 
bool has_openssl_manager () const
 Returns true if the openssl module is available, false otherwise.
 
openssl::manageropenssl_manager () const
 Returns the manager instance from the OpenSSL module. More...
 
bool has_network_manager () const noexcept
 Returns true if the network module is available, false otherwise.
 
net::middlemannetwork_manager ()
 Returns the network manager (middleman) instance. More...
 
actor_id next_actor_id ()
 Returns a new actor ID.
 
actor_id latest_actor_id () const
 Returns the last given actor ID.
 
void await_all_actors_done () const
 Blocks this caller until all actors are done.
 
void monitor (const node_id &node, const actor_addr &observer)
 Send a node_down_msg to observer if this system loses connection to node. More...
 
void demonitor (const node_id &node, const actor_addr &observer)
 Removes observer from the list of actors that receive a node_down_msg if this system loses connection to node. More...
 
template<class C , spawn_options Os, class... Ts>
infer_handle_from_class_t< C > spawn_class (actor_config &cfg, Ts &&... xs)
 Called by spawn when used to create a class-based actor to apply automatic conversions to xs before spawning the actor. More...
 
template<class C , spawn_options Os = no_spawn_options, class... Ts>
infer_handle_from_class_t< C > spawn (Ts &&... xs)
 Returns a new actor of type C using xs... as constructor arguments. More...
 
template<spawn_options Os = no_spawn_options, class F , class... Ts>
infer_handle_from_fun_t< F > spawn (F fun, Ts &&... xs)
 Returns a new functor-based actor. More...
 
template<spawn_options Options = no_spawn_options, class CustomSpawn , class... Args>
CustomSpawn::handle_type spawn (CustomSpawn, Args &&... args)
 Returns a new stateful actor.
 
template<class Handle , class E = std::enable_if_t<is_handle_v<Handle>>>
expected< Handle > spawn (const std::string &name, message args, caf::scheduler *ctx=nullptr, bool check_interface=true, const mpi *expected_ifs=nullptr)
 Returns a new actor with run-time type name, constructed with the arguments stored in args. More...
 
template<class... Args>
void println (term color, std::string_view fmt, Args &&... args)
 Adds a new line to stdout.
 
template<class... Args>
void println (std::string_view fmt, Args &&... args)
 Adds a new line to stdout.
 
void redirect_text_output (void *out, void(*write)(void *, term, const char *, size_t), void(*cleanup)(void *))
 Redirects the output of println to a custom function. More...
 

Friends

class abstract_actor
 
class actor_ostream
 
class detail::actor_system_access
 
class local_actor
 
class logger
 
class net::middleman
 
template<class >
class actor_from_state_t
 
struct detail::printer_actor_state
 

Detailed Description

Actor environment including scheduler, registry, and optional components such as a middleman.

Constructor & Destructor Documentation

◆ actor_system()

caf::actor_system::actor_system ( actor_system_config cfg)
explicit
Warning
The system stores a reference to cfg, which means the config object must outlive the actor system.

Member Function Documentation

◆ assignable() [1/2]

bool caf::actor_system::assignable ( const mpi xs,
const mpi ys 
) const
inline

Returns whether actor handles described by xs can be assigned to actor handles described by ys.

◆ assignable() [2/2]

template<class T >
bool caf::actor_system::assignable ( const std::set< std::string > &  xs) const
inline

Returns whether actor handles described by xs can be assigned to actor handles of type T.

◆ await_actors_before_shutdown() [1/2]

bool caf::actor_system::await_actors_before_shutdown ( ) const

Returns whether this actor system calls await_all_actors_done in its destructor before shutting down.

◆ await_actors_before_shutdown() [2/2]

void caf::actor_system::await_actors_before_shutdown ( bool  new_value)

Configures whether this actor system calls await_all_actors_done in its destructor before shutting down.

◆ config_serv()

const strong_actor_ptr & caf::actor_system::config_serv ( ) const

Returns the internal actor for storing the runtime configuration for this actor system.

◆ demonitor()

void caf::actor_system::demonitor ( const node_id node,
const actor_addr observer 
)

Removes observer from the list of actors that receive a node_down_msg if this system loses connection to node.

◆ middleman()

io::middleman & caf::actor_system::middleman ( )

Returns the middleman instance from the I/O module.

Exceptions
<tt>std::logic_error</tt>if module is not loaded.

◆ monitor()

void caf::actor_system::monitor ( const node_id node,
const actor_addr observer 
)

Send a node_down_msg to observer if this system loses connection to node.

Note
Calling this function n times causes the system to send node_down_msg n times to the observer. In order to not receive the messages, the observer must call demonitor n times.

◆ network_manager()

net::middleman & caf::actor_system::network_manager ( )

Returns the network manager (middleman) instance.

Exceptions
<tt>std::logic_error</tt>if module is not loaded.

◆ openssl_manager()

openssl::manager & caf::actor_system::openssl_manager ( ) const

Returns the manager instance from the OpenSSL module.

Exceptions
<tt>std::logic_error</tt>if module is not loaded.

◆ redirect_text_output()

void caf::actor_system::redirect_text_output ( void *  out,
void(*)(void *, term, const char *, size_t)  write,
void(*)(void *)  cleanup 
)

Redirects the output of println to a custom function.

Parameters
outThe new output stream to write to.
writeThe new print function to use. Must not be null.
cleanupDeletes the output stream when the actor system shuts down. May be null if no cleanup is necessary.

◆ spawn() [1/3]

template<class C , spawn_options Os = no_spawn_options, class... Ts>
infer_handle_from_class_t<C> caf::actor_system::spawn ( Ts &&...  xs)
inline

Returns a new actor of type C using xs... as constructor arguments.

The behavior of spawn can be modified by setting Os, e.g., to opt-out of the cooperative scheduling.

Parameters
xsConstructor arguments for C.

◆ spawn() [2/3]

template<spawn_options Os = no_spawn_options, class F , class... Ts>
infer_handle_from_fun_t<F> caf::actor_system::spawn ( fun,
Ts &&...  xs 
)
inline

Returns a new functor-based actor.

The first argument must be the functor, the remainder of xs... is used to invoke the functor. The behavior of spawn can be modified by setting Os, e.g., to opt-out of the cooperative scheduling.

◆ spawn() [3/3]

template<class Handle , class E = std::enable_if_t<is_handle_v<Handle>>>
expected<Handle> caf::actor_system::spawn ( const std::string &  name,
message  args,
caf::scheduler ctx = nullptr,
bool  check_interface = true,
const mpi expected_ifs = nullptr 
)
inline

Returns a new actor with run-time type name, constructed with the arguments stored in args.

◆ spawn_class()

template<class C , spawn_options Os, class... Ts>
infer_handle_from_class_t<C> caf::actor_system::spawn_class ( actor_config cfg,
Ts &&...  xs 
)
inline

Called by spawn when used to create a class-based actor to apply automatic conversions to xs before spawning the actor.

Should not be called by users of the library directly.

Parameters
cfgTo-be-filled config for the actor.
xsConstructor arguments for C.

The documentation for this class was generated from the following files: