caf::blocking_actor Class Reference

A thread-mapped or context-switching actor using a blocking receive rather than a behavior-stack based message processing. More...

#include <blocking_actor.hpp>

Inheritance diagram for caf::blocking_actor:

Classes
class	accept_one_cond
	Pseudo receive condition modeling a single receive. More...
struct	do_receive_helper
	Implementation helper for blocking_actor::do_receive. More...
class	receive_cond
	Represents pre- and postconditions for receive loops. More...
struct	receive_for_helper
	Implementation helper for blocking_actor::receive_for. More...
struct	receive_while_helper
	Implementation helper for blocking_actor::receive_while. More...

Public Types
using	super = extended_base
	Base type.
using	timeout_type = std::chrono::high_resolution_clock::time_point
	Absolute timeout type.
using	behavior_type = behavior
	Supported behavior type.
using	signatures = none_t
	Declared message passing interface.
Public Types inherited from caf::local_actor
using	clock_type = std::chrono::steady_clock
	Defines a monotonic clock suitable for measuring intervals.

Public Member Functions
	blocking_actor (actor_config &cfg)
bool	enqueue (mailbox_element_ptr, scheduler *) override
	Enqueues a new message wrapped in a mailbox_element to the actor.
mailbox_element *	peek_at_next_mailbox_element () override
	Called by the testing DSL to peek at the next element in the mailbox.
const char *	name () const override
	Returns an implementation-dependent name for logging purposes, which is only valid as long as the actor is running.
void	launch (scheduler *sched, bool lazy, bool hide) override
virtual void	act ()
	Implements the actor's behavior.
template<class... Ts>
void	receive (Ts &&... xs)
	Dequeues the next message from the mailbox that is matched by given behavior.
template<class T >
receive_for_helper< T >	receive_for (T &begin, T end)
	Receives messages for range [begin, first).
receive_while_helper	receive_while (std::function< bool()> stmt)
	Receives messages as long as stmt returns true.
receive_while_helper	receive_while (const bool &ref)
	Receives messages as long as ref is true.
template<class... Ts>
do_receive_helper	do_receive (Ts &&... xs)
	Receives messages until stmt returns true.
void	await_all_other_actors_done ()
	Blocks this actor until all other actors are done.
template<class... Ts>
void	wait_for (Ts &&... xs)
	Blocks this actor until all xs... have terminated.
void	fail_state (error err)
	Sets a user-defined exit reason err.
template<class... Args>
auto	mail (Args &&... args)
template<message_priority P = message_priority::normal, class Handle >
void	monitor (const Handle &whom)
	Adds a unidirectional monitor to whom to receive a down_msg when whom terminates.
template<class Handle >
void	demonitor (const Handle &whom)
	Removes a monitor from whom.
virtual void	await_data ()
	Blocks until at least one message is in the mailbox.
virtual bool	await_data (timeout_type timeout)
	Blocks until at least one message is in the mailbox or the absolute timeout was reached.
mailbox_element_ptr	dequeue ()
	Returns the next element from the mailbox or nullptr.
abstract_mailbox &	mailbox ()
	Returns the queue for storing incoming messages.
Public Member Functions inherited from caf::local_actor
	local_actor (actor_config &cfg)
void	on_cleanup (const error &) override
	Called from cleanup to perform extra cleanup actions for this actor.
void	setup_metrics ()
clock_type::time_point	now () const noexcept
	Returns the current time.
disposable	request_response_timeout (timespan d, message_id mid)
	Requests a new timeout for mid.
template<class... Args>
void	println (std::string_view fmt, Args &&... args)
	Adds a new line to stdout.
template<class... Args>
void	println (term color, std::string_view fmt, Args &&... args)
	Adds a new line to stdout.
template<class T , spawn_options Os = no_spawn_options, class... Ts>
infer_handle_from_class_t< T >	spawn (Ts &&... xs)
template<spawn_options Options = no_spawn_options, class CustomSpawn , class... Args>
CustomSpawn::handle_type	spawn (CustomSpawn, Args &&... args)
template<spawn_options Os = no_spawn_options, class F , class... Ts>
infer_handle_from_fun_t< F >	spawn (F fun, Ts &&... xs)
void	send_exit (const actor_addr &receiver, error reason)
	Sends an exit message to receiver.
void	send_exit (const strong_actor_ptr &receiver, error reason)
	Sends an exit message to receiver.
template<class Handle >
void	send_exit (const Handle &receiver, error reason)
	Sends an exit message to receiver.
template<message_priority Priority = message_priority::normal, class Handle , class T , class... Ts>
void	anon_send (const Handle &receiver, T &&arg, Ts &&... args)
template<message_priority Priority = message_priority::normal, class Handle , class T , class... Ts>
disposable	scheduled_anon_send (const Handle &receiver, actor_clock::time_point timeout, T &&arg, Ts &&... args)
template<message_priority Priority = message_priority::normal, class Handle , class T , class... Ts>
disposable	delayed_anon_send (const Handle &receiver, actor_clock::duration_type timeout, T &&arg, Ts &&... args)
scheduler *	context () const noexcept
	Returns the execution unit currently used by this actor.
void	context (scheduler *x) noexcept
	Sets the execution unit for this actor.
actor_system &	system () const noexcept
	Returns the hosting actor system.
const actor_system_config &	config () const noexcept
	Returns the config of the hosting actor system.
actor_clock &	clock () const noexcept
	Returns the clock of the actor system.
strong_actor_ptr &	current_sender () noexcept
	Returns a pointer to the sender of the current message.
message_id	current_message_id () noexcept
	Returns the ID of the current message.
message_id	take_current_message_id () noexcept
	Returns the ID of the current message and marks the ID stored in the current mailbox element as answered.
void	drop_current_message_id () noexcept
	Marks the current message ID as answered.
mailbox_element *	current_mailbox_element () noexcept
	Returns a pointer to the currently processed mailbox element.
void	monitor (const node_id &node)
	Adds a unidirectional monitor to node.
void	demonitor (const node_id &node)
	Removes a monitor from node.
virtual void	on_exit ()
	Can be overridden to perform cleanup code after an actor finished execution.
template<class... Ts>
detail::response_promise_t< Ts... >	make_response_promise ()
	Creates a typed_response_promise to respond to a request later on.
response_promise	make_response_promise ()
	Creates a response_promise to respond to a request later on.
const char *	name () const override
	Returns an implementation-dependent name for logging purposes, which is only valid as long as the actor is running.
virtual error	save_state (serializer &sink, unsigned int version)
	Serializes the state of this actor to sink.
virtual error	load_state (deserializer &source, unsigned int version)
	Deserializes the state of this actor from source.
const error &	fail_state () const noexcept
	Returns the currently defined fail state.
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.
template<class F >
void	attach_functor (F f)
	Convenience function that attaches the functor f to this actor.
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.
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.
bool	cleanup (error &&reason, scheduler *sched)
	Called by the runtime system to perform cleanup actions for this actor.

Additional Inherited Members
Protected Member Functions inherited from caf::local_actor
void	do_send (abstract_actor *receiver, message_priority priority, message &&msg)
	Sends msg as an asynchronous message to receiver.
disposable	do_scheduled_send (strong_actor_ptr receiver, message_priority priority, actor_clock::time_point timeout, message &&msg)
	Sends msg as an asynchronous message to receiver after the timeout.
void	do_anon_send (abstract_actor *receiver, message_priority priority, message &&msg)
	Sends msg as an asynchronous message to receiver without sender information.
disposable	do_scheduled_anon_send (strong_actor_ptr receiver, message_priority priority, actor_clock::time_point timeout, message &&msg)
	Sends msg as an asynchronous message to receiver after the timeout without sender information.
void	do_monitor (abstract_actor *ptr, message_priority prio)
void	do_demonitor (const strong_actor_ptr &whom)
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).
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.
virtual bool	remove_backlink (abstract_actor *other)
	Removes an entry to other from the link table of this actor.
Protected Attributes inherited from caf::local_actor
scheduler *	context_
mailbox_element *	current_element_
message_id	last_request_id_
detail::unique_function< behavior(local_actor *)>	initial_behavior_fac_
	Factory function for returning initial behavior in function-based actors.
metrics_t	metrics_
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 .
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 Symbols inherited from caf::local_actor
constexpr keep_behavior_t	keep_behavior = keep_behavior_t{}
	Policy tag that causes event_based_actor::become to keep the current behavior available.
Related Symbols inherited from caf::abstract_actor
using	actor_id = uint64_t
	A unique actor ID.

Detailed Description

A thread-mapped or context-switching actor using a blocking receive rather than a behavior-stack based message processing.

Member Function Documentation

do_receive()

template<class... Ts>

do_receive_helper caf::blocking_actor::do_receive

(

Ts &&...

xs

)

Receives messages until stmt returns true.

Semantically equal to: do { receive(...); } while (stmt() == false);

Usage example:

int i = 0;
do_receive
(
  on<int>() >> int_fun,
  on<float>() >> float_fun
)
.until([&]() { return (++i >= 10); };

enqueue()

bool caf::blocking_actor::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.

fail_state()

void caf::blocking_actor::fail_state

(

error

err

)

Sets a user-defined exit reason err.

This reason is signalized to other actors after act() returns.

launch()

void caf::blocking_actor::launch ( scheduler * sched, bool lazy, bool hide )

overridevirtual

Implements caf::local_actor.

monitor()

template<message_priority P = message_priority::normal, class Handle >

void caf::blocking_actor::monitor

(

const Handle &

whom

)

Adds a unidirectional monitor to whom to receive a down_msg when whom terminates.

Note

Each call to monitor creates a new, independent monitor.

name()

const char * caf::blocking_actor::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.

peek_at_next_mailbox_element()

mailbox_element * caf::blocking_actor::peek_at_next_mailbox_element ( )

overridevirtual

Called by the testing DSL to peek at the next element in the mailbox.

Do not call this function in production code! The default implementation always returns nullptr.

Returns

A pointer to the next mailbox element or nullptr if the mailbox is empty or the actor does not have a mailbox.

Reimplemented from caf::abstract_actor.

receive_for()

template<class T >

receive_for_helper< T > caf::blocking_actor::receive_for	(	T &	begin,
		T	end )

Receives messages for range [begin, first).

Semantically equal to: for ( ; begin != end; ++begin) { receive(...); }.

Usage example:

int i = 0;
receive_for(i, 10) (
  [&](get_atom) {
    return i;
  }
);

receive_while() [1/2]

blocking_actor::receive_while_helper caf::blocking_actor::receive_while

(

const bool &

ref

)

Receives messages as long as ref is true.

Semantically equal to: while (ref) { receive(...); }.

Usage example:

bool running = true;
receive_while(running) (
  ...
);

receive_while() [2/2]

blocking_actor::receive_while_helper caf::blocking_actor::receive_while

(

std::function< bool()>

stmt

)

Receives messages as long as stmt returns true.

Semantically equal to: while (stmt()) { receive(...); }.

Usage example:

int i = 0;
receive_while([&]() { return (++i <= 10); }) (
  ...
);

---

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

• libcaf_core/caf/blocking_actor.hpp
• libcaf_core/caf/blocking_actor.cpp