An actor poool is a lightweight abstraction for a set of workers. More...

#include <actor_pool.hpp>

Inheritance diagram for caf::actor_pool:

Collaboration diagram for caf::actor_pool:

Public Types
using	actor_vec = std::vector< actor >

using	factory = std::function< actor()>

using	guard_type = std::unique_lock< std::mutex >

using	policy = std::function< void(actor_system &, guard_type &, const actor_vec &, mailbox_element_ptr &, scheduler *)>

Public Member Functions
bool	enqueue (mailbox_element_ptr what, scheduler *sched) override
	Enqueues a new message wrapped in a `mailbox_element` to the actor. More...

	actor_pool (actor_config &cfg)

const char *	name () const override
	Returns an implementation-dependent name for logging purposes, which is only valid as long as the actor is running. More...

void	setup_metrics ()

Public Member Functions inherited from caf::abstract_actor
	abstract_actor (const abstract_actor &)=delete

abstract_actor &	operator= (const abstract_actor &)=delete

void	attach (attachable_ptr ptr)
	Attaches `ptr` to this actor. More...

template<class F >
void	attach_functor (F f)
	Convenience function that attaches the functor `f` to this actor. More...

size_t	detach (const attachable::token &what)
	Detaches the first attached object that matches `what`.

void	link_to (const actor_addr &other)
	Links this actor to `other`.

template<class ActorHandle >
void	link_to (const ActorHandle &other)
	Links this actor to `other`.

void	unlink_from (const actor_addr &other)
	Unlinks this actor from `addr`.

template<class ActorHandle >
void	unlink_from (const ActorHandle &other)
	Links this actor to `hdl`.

virtual std::set< std::string >	message_types () const
	Returns the set of accepted messages types as strings or an empty set if this actor is untyped. More...

actor_id	id () const noexcept
	Returns the ID of this actor.

node_id	node () const noexcept
	Returns the node this actor is living on.

actor_system &	home_system () const noexcept
	Returns the system that created this actor (or proxy).

actor_control_block *	ctrl () const
	Returns the control block for this actor.

actor_addr	address () const noexcept
	Returns the logical actor address.

virtual mailbox_element *	peek_at_next_mailbox_element ()
	Called by the testing DSL to peek at the next element in the mailbox. More...

bool	cleanup (error &&reason, scheduler *sched)
	Called by the runtime system to perform cleanup actions for this actor. More...

Static Public Member Functions
static policy	round_robin ()
	Returns a simple round robin dispatching policy.

static policy	broadcast ()
	Returns a broadcast dispatching policy.

static policy	random ()
	Returns a random dispatching policy.

template<class T , class Join , class Split = detail::nop_split>
static policy	split_join (Join jf, Split sf=Split(), T init=T())
	Returns a split/join dispatching policy. More...

static actor	make (actor_system &sys, policy pol)
	Returns an actor pool without workers using the dispatch policy `pol`.

static actor	make (actor_system &sys, size_t num_workers, const factory &fac, policy pol)
	Returns an actor pool with `n` workers created by the factory function `fac` using the dispatch policy `pol`. More...

Protected Member Functions
void	on_cleanup (const error &reason) override
	Called from `cleanup` to perform extra cleanup actions for this actor.

Protected Member Functions inherited from caf::abstract_actor
virtual void	on_unreachable ()
	Called on actor if the last strong reference to it expired without a prior call to `quit(exit_reason::not_exited)`. More...

int	flags () const

void	flags (int new_value)

bool	is_terminated () const noexcept
	Checks whether this actor has terminated.

	abstract_actor (actor_config &cfg)

void	attach_impl (attachable_ptr &ptr)

size_t	detach_impl (const attachable::token &what, bool stop_on_hit=false, bool dry_run=false)

void	add_link (abstract_actor *other)
	Causes the actor to establish a link to `other`.

void	remove_link (abstract_actor *other)
	Causes the actor to remove any established link to `other`.

virtual bool	add_backlink (abstract_actor *other)
	Adds an entry to `other` to the link table of this actor. More...

virtual bool	remove_backlink (abstract_actor *other)
	Removes an entry to `other` from the link table of this actor. More...

Additional Inherited Members
Protected Attributes inherited from caf::abstract_actor
std::atomic< int >	flags_
	Holds several state and type flags.

std::mutex	mtx_
	Guards members that may be subject to concurrent access . More...

std::condition_variable	cv_
	Allows blocking actors to actively wait for incoming messages.

error	fail_state_
	Stores the user-defined exit reason if this actor has finished execution.

attachable_ptr	attachables_head_
	Points to the first attachable in the linked list of attachables (if any).

Related Functions inherited from caf::abstract_actor
using	actor_id = uint64_t
	A unique actor ID.

Detailed Description

An actor poool is a lightweight abstraction for a set of workers.

The pool itself is an actor, meaning that it can be passed around in an actor system to hide the actual set of workers.

After construction, new workers can be added via `{'SYS', 'PUT', actor} messages, e.g.,send(my_pool, sys_atom::value, put_atom::value, worker). {'SYS', 'DELETE', actor}messages remove a specific worker from the set, {'SYS', 'DELETE'}removes all workers, and{'SYS', 'GET'}returns a vector<actor>` containing all workers.

Note that the pool always sends exit messages to all of its workers when forced to quit. The pool monitors all of its workers. Messages queued up in a worker's mailbox are lost, i.e., the pool itself does not buffer and resend messages. Advanced caching or resend strategies can be implemented in a policy.

It is worth mentioning that the pool is not an event-based actor. Neither does it live in its own thread. Messages are dispatched immediately during the enqueue operation. Any user-defined policy thus has to dispatch messages with as little overhead as possible, because the dispatching runs in the context of the sender.

Member Function Documentation

◆ enqueue()

bool caf::actor_pool::enqueue	(	mailbox_element_ptr	what,
		scheduler *	sched
	)

overridevirtual

Enqueues a new message wrapped in a mailbox_element to the actor.

This enqueue variant allows to define forwarding chains.

Returns: true if the message has added to the mailbox, false otherwise. In the latter case, the actor terminated and the message has been dropped. Once this function returns false, it returns false for all future invocations.

Note: The returned value is purely informational and may be used to discard actor handles early. Messages may still get dropped later even if this function returns true. In particular when dealing with remote actors.

Implements caf::abstract_actor.

◆ make()

actor caf::actor_pool::make	(	actor_system &	sys,
		size_t	num_workers,
		const factory &	fac,
		policy	pol
	)

static

Returns an actor pool with n workers created by the factory function fac using the dispatch policy pol.

◆ name()

const char * caf::actor_pool::name ( ) const

overridevirtual

Returns an implementation-dependent name for logging purposes, which is only valid as long as the actor is running.

The default implementation simply returns "actor".

Implements caf::abstract_actor.

◆ split_join()

template<class T , class Join , class Split = detail::nop_split>

static policy caf::actor_pool::split_join	(	Join	jf,
		Split	sf = `Split()`,
		T	init = `T()`
	)

inlinestatic

Returns a split/join dispatching policy.

The function object sf distributes a work item to all workers (split step) and the function object jf joins individual results into a single one with init as initial value of the operation.

Template Parameters

T	Result type of the join step.
Join	Function object with signature `void (T&, message&)`.
Split	Function object with signature `void (vector<pair<actor, message>>&, message&)`. The first argument is a mapping from actors (workers) to tasks (messages). The second argument is the input message. The default split policy broadcasts the work item to all workers.

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

libcaf_core/caf/actor_pool.hpp
libcaf_core/caf/actor_pool.cpp

Public Types

Public Member Functions

Static Public Member Functions