Loading...
Searching...
No Matches
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:

## Public Types

using | uplock = upgrade_lock<detail::shared_spinlock>
using | actor_vec = std::vector<actor>
using | factory = std::function<actor ()>
using | policy

## 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.
| actor_pool (actor_config &cfg)
void | on_destroy () override
| Cleans up any remaining state before the destructor is called.
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.
void | attach (attachable_ptr ptr) override
| Attaches ptr to this actor.
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_block * | ctrl () const
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.
actor_addr | address () const
| Returns the logical actor address.
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.
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).
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.
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.

## Protected Member Functions

void | on_cleanup (const error &reason) override
| Allows subclasses to add additional cleanup code to the critical secion in cleanup.
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.
void | attach_impl (attachable_ptr &ptr)
size_t | detach_impl (const attachable::token &what, bool stop_on_hit=false, bool dry_run=false)
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)
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 constexpr int | is_hidden_flag = 0x10000000
Protected Attributes inherited from caf::monitorable_actor
error | fail_state_
std::condition_variable | cv_
attachable_ptr | attachables_head_
Protected Attributes inherited from caf::abstract_actor
std::mutex | mtx_
Related Symbols 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_v, put_atom_v, 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 Typedef Documentation

## policy

using caf::actor_pool::policy

Initial value:
std::function<void (actor_system&, uplock&, const actor_vec&,
mailbox_element_ptr&, execution_unit*)>
caf::actor_system
Actor environment including scheduler, registry, and optional components such as a middleman.
Definition actor_system.hpp:117
caf::execution_unit
Identifies an execution unit, e.g., a worker thread of the scheduler.
Definition execution_unit.hpp:29

## Member Function Documentation

## enqueue()

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

override virtual

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

This enqueue variant allows to define forwarding chains.

Implements caf::abstract_actor.

## on_cleanup()

void caf::actor_pool::on_cleanup | ( | const error & | reason | ) |

override protected virtual

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.

## on_destroy()

void caf::actor_pool::on_destroy | ( |  | ) |

override virtual

Cleans up any remaining state before the destructor is called.

This function makes sure it is safe to call virtual functions in sub classes before destroying the object, because calling virtual function in the destructor itself is not safe. Any override implementation is required to call super::destroy() at the end.

Reimplemented from caf::abstract_actor.

## split_join()

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

policy caf::actor_pool::split_join | ( | Join | jf,
|  | Split | sf = Split(),
|  | T | 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

  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 file:

- /build/actor-framework-Z9pIPl/actor-framework-0.17.6/libcaf_core/caf/actor_pool.hpp