caf::actor_system Class Reference

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

#include <actor_system.hpp>

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	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_system &	operator= (const actor_system &)=delete
	actor_system (actor_system_config &cfg, version::abi_token=make_abi_token())
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.
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.
base_metrics_t &	base_metrics () noexcept
const base_metrics_t &	base_metrics () const noexcept
const actor_metric_families_t &	actor_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_config &	config () const
	Returns the configuration of this actor system.
actor_clock &	clock () 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.
void	await_actors_before_shutdown (bool new_value)
	Configures whether this actor system calls await_all_actors_done in its destructor before shutting down.
const strong_actor_ptr &	spawn_serv () const
	Returns the internal actor for dynamic spawn operations.
const strong_actor_ptr &	config_serv () const
	Returns the internal actor for storing the runtime configuration for this actor system.
telemetry::metric_registry &	metrics () noexcept
	Returns the metrics registry for this system.
const telemetry::metric_registry &	metrics () const noexcept
	Returns the metrics registry for this system.
const node_id &	node () const
	Returns the host-local identifier for this system.
caf::scheduler &	scheduler ()
	Returns the scheduler instance.
caf::logger &	logger ()
	Returns the system-wide event logger.
actor_registry &	registry ()
	Returns the system-wide actor registry.
bool	has_middleman () const
	Returns true if the I/O module is available, false otherwise.
io::middleman &	middleman ()
	Returns the middleman instance from the I/O module.
bool	has_openssl_manager () const
	Returns true if the openssl module is available, false otherwise.
openssl::manager &	openssl_manager () const
	Returns the manager instance from the OpenSSL module.
bool	has_network_manager () const noexcept
	Returns true if the network module is available, false otherwise.
net::middleman &	network_manager ()
	Returns the network manager (middleman) instance.
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.
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.
intrusive_ptr< actor_companion >	make_companion ()
	Creates a new actor companion and returns a smart pointer to it.
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.
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.
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.
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.
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.

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.

Examples

dancing_kirby.cpp, dining_philosophers.cpp, and hello_world.cpp.

Constructor & Destructor Documentation

actor_system()

caf::actor_system::actor_system ( actor_system_config & cfg, version::abi_token token = make_abi_token() )

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

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

Attention

This feature is experimental.

assignable() [2/2]

template<class T >

bool caf::actor_system::assignable

(

const std::set< std::string > &

xs

)

const

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

Attention

This feature is experimental.

middleman()

io::middleman & caf::actor_system::middleman

(

)

Returns the middleman instance from the I/O module.

Exceptions

`std::logic_error`

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

`std::logic_error`

if module is not loaded.

openssl_manager()

openssl::manager & caf::actor_system::openssl_manager

(

)

const

Returns the manager instance from the OpenSSL module.

Exceptions

`std::logic_error`

if module is not loaded.

redirect_text_output()

void caf::actor_system::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.

Parameters

out	The new output stream to write to.
write	The new print function to use. Must not be null.
cleanup	Deletes the output stream when the actor system shuts down. May be null if no cleanup is necessary.

spawn() [1/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 )

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

Attention

This feature is experimental.

spawn() [2/3]

template<spawn_options Os = no_spawn_options, class F , class... Ts>

infer_handle_from_fun_t< F > caf::actor_system::spawn	(	F	fun,
		Ts &&...	xs )

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 C , spawn_options Os = no_spawn_options, class... Ts>

infer_handle_from_class_t< C > caf::actor_system::spawn

(

Ts &&...

xs

)

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

xs	Constructor arguments for C.

Examples

dining_philosophers.cpp, and hello_world.cpp.

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 )

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

cfg	To-be-filled config for the actor.
xs	Constructor arguments for C.

---

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

• libcaf_core/caf/actor_system.hpp
• libcaf_core/caf/actor_system.cpp