libcaf  0.15.3
Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
caf::actor_pool Class Reference

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

#include <actor_pool.hpp>

Inheritance diagram for caf::actor_pool:
caf::monitorable_actor caf::abstract_actor caf::abstract_channel

Public Types

using uplock = upgrade_lock< detail::shared_spinlock >
 
using actor_vec = std::vector< actor >
 
using factory = std::function< actor()>
 
using policy = std::function< void(actor_system &, uplock &, const actor_vec &, mailbox_element_ptr &, execution_unit *)>
 

Public Member Functions

void enqueue (mailbox_element_ptr what, execution_unit *eu) override
 Enqueues a new message wrapped in a mailbox_element to the actor. More...
 
 actor_pool (actor_config &cfg)
 
- Public Member Functions inherited from caf::monitorable_actor
virtual const char * name () const
 Returns an implementation-dependent name for logging purposes, which is only valid as long as the actor is running. More...
 
void attach (attachable_ptr ptr) override
 Attaches ptr to this actor. More...
 
size_t detach (const attachable::token &what) override
 Detaches the first attached object that matches what.
 
void link_to (const actor_addr &x)
 Links this actor to x.
 
template<class ActorHandle >
void link_to (const ActorHandle &x)
 Links this actor to x.
 
void unlink_from (const actor_addr &x)
 Unlinks this actor from x.
 
template<class ActorHandle >
void unlink_from (const ActorHandle &x)
 Links this actor to x.
 
- Public Member Functions inherited from caf::abstract_actor
void * operator new (std::size_t, void *ptr)
 
actor_control_blockctrl () const
 
virtual void on_destroy ()
 Cleans up any remaining state before the destructor is called. More...
 
void enqueue (strong_actor_ptr sender, message_id mid, message msg, execution_unit *host) override
 Enqueues a new message without forwarding stack to the channel.
 
template<class F >
void attach_functor (F f)
 Convenience function that attaches the functor f to this actor. More...
 
actor_addr address () const
 Returns the logical actor address.
 
bool establish_backlink (abstract_actor *x)
 Establishes a link relation between this actor and x and returns whether the operation succeeded. More...
 
bool remove_backlink (abstract_actor *x)
 Removes the link relation between this actor and x and returns whether the operation succeeded. More...
 
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_systemhome_system () const noexcept
 Returns the system that created this actor (or proxy).
 
- Public Member Functions inherited from caf::abstract_channel
bool is_abstract_actor () const
 
bool is_abstract_group () const
 
bool is_actor_decorator () const
 

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 (execution_unit *eu, policy pol)
 Returns an actor pool without workers using the dispatch policy pol.
 
static actor make (execution_unit *eu, 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 () override
 Allows subclasses to add additional cleanup code to the critical secion in cleanup. More...
 
- Protected Member Functions inherited from caf::monitorable_actor
void bounce (mailbox_element_ptr &what)
 Sends a response message if what is a request.
 
void bounce (mailbox_element_ptr &what, const error &err)
 Sends a response message if what is a request.
 
 monitorable_actor (actor_config &cfg)
 Creates a new actor instance.
 
bool link_impl (linking_operation op, abstract_actor *other) override
 
bool establish_link_impl (abstract_actor *x)
 
bool remove_link_impl (abstract_actor *x)
 
bool establish_backlink_impl (abstract_actor *x)
 
bool remove_backlink_impl (abstract_actor *x)
 
void attach_impl (attachable_ptr &ptr)
 
bool handle_system_message (mailbox_element &x, execution_unit *ctx, bool trap_exit)
 
template<class F >
bool handle_system_message (mailbox_element &x, execution_unit *context, bool trap_exit, F &down_msg_handler)
 
template<class F >
auto exclusive_critical_section (F fun) -> decltype(fun())
 
template<class F >
auto shared_critical_section (F fun) -> decltype(fun())
 
- Protected Member Functions inherited from caf::abstract_actor
 abstract_actor (actor_config &cfg)
 Creates a new actor instance.
 
- Protected Member Functions inherited from caf::abstract_channel
int flags () const
 
void flags (int new_value)
 

Additional Inherited Members

- Static Public Attributes inherited from caf::abstract_channel
static constexpr int is_abstract_actor_flag = 0x01000000
 
static constexpr int is_abstract_group_flag = 0x02000000
 
static constexpr int is_actor_bind_decorator_flag = 0x04000000
 
static constexpr int is_actor_dot_decorator_flag = 0x08000000
 
static constexpr int is_actor_decorator_mask = 0x0C000000
 
- Static Protected Member Functions inherited from caf::monitorable_actor
static size_t detach_impl (const attachable::token &what, attachable_ptr &ptr, bool stop_on_hit=false, bool dry_run=false)
 
- Protected Attributes inherited from caf::monitorable_actor
error fail_state_
 
std::mutex mtx_
 
std::condition_variable cv_
 
attachable_ptr attachables_head_
 

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.

Attention
This feature is experimental.

Member Function Documentation

void caf::actor_pool::enqueue ( mailbox_element_ptr  what,
execution_unit host 
)
overridevirtual

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

This enqueue variant allows to define forwarding chains.

Implements caf::abstract_actor.

static actor caf::actor_pool::make ( execution_unit eu,
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.

void caf::actor_pool::on_cleanup ( )
overrideprotectedvirtual

Allows subclasses to add additional cleanup code to the critical secion in cleanup.

This member function is called inside of a critical section.

Reimplemented from caf::monitorable_actor.

template<class T , class Join , class Split = detail::nop_split>
static policy caf::actor_pool::split_join ( Join  jf,
Split  sf = Split(),
init = T() 
)
static

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
TResult type of the join step.
JoinFunction object with signature void (T&, message&).
SplitFunction 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 file: