rotor::asio::supervisor_asio_t Struct Reference

delivers rotor-messages on top of boost asio event loop using strand for serialization More...

#include <supervisor_asio.h>

Inheritance diagram for rotor::asio::supervisor_asio_t:

Classes
struct	timer_t
	boos::asio::deadline_timer with embedded timer handler More...

Public Types
using	config_t = supervisor_config_asio_t
	injects an alias for supervisor_config_asio_t
template<typename Supervisor >
using	config_builder_t = supervisor_config_asio_builder_t< Supervisor >
	injects templated supervisor_config_asio_builder_t
Public Types inherited from rotor::supervisor_t
using	plugins_list_t = std::tuple< plugin::address_maker_plugin_t, plugin::locality_plugin_t, plugin::delivery_plugin_t< plugin::default_local_delivery_t >, plugin::lifetime_plugin_t, plugin::init_shutdown_plugin_t, plugin::foreigners_support_plugin_t, plugin::child_manager_plugin_t, plugin::link_server_plugin_t, plugin::link_client_plugin_t, plugin::registry_plugin_t, plugin::resources_plugin_t, plugin::starter_plugin_t >
	the default list of plugins for an supervisor
using	config_t = supervisor_config_t
	injects an alias for supervisor_config_t
template<typename Supervisor >
using	config_builder_t = supervisor_config_builder_t< Supervisor >
	injects templated supervisor_config_builder_t
using	inbound_queue_t = boost::lockfree::queue< message_base_t * >
	lock-free queue for inbound messages
Public Types inherited from rotor::actor_base_t
using	config_t = actor_config_t
	injects an alias for actor_config_t
template<typename Actor >
using	config_builder_t = actor_config_builder_t< Actor >
	injects templated actor_config_builder_t
template<typename Handler >
using	is_handler = std::enable_if_t< std::is_member_function_pointer_v< Handler >||std::is_base_of_v< handler_base_t, Handler > >
	SFINAE handler detector.
using	plugins_list_t = std::tuple< plugin::address_maker_plugin_t, plugin::lifetime_plugin_t, plugin::init_shutdown_plugin_t, plugin::link_server_plugin_t, plugin::link_client_plugin_t, plugin::registry_plugin_t, plugin::resources_plugin_t, plugin::starter_plugin_t >
	the default list of plugins for an actor

Public Member Functions
	supervisor_asio_t (supervisor_config_asio_t &config)
	constructs new supervisor from asio supervisor config
virtual address_ptr_t	make_address () noexcept override
	creates new address_t linked with the supervisor
virtual void	start () noexcept override
	thread-safe version of do_process
virtual void	shutdown () noexcept override
	thread-safe version of do_shutdown, i.e. send shutdown request let it be processed by the supervisor
virtual void	enqueue (message_ptr_t message) noexcept override
	enqueues messages thread safe way and triggers processing
virtual void	shutdown_finish () noexcept override
	finalizes shutdown
template<typename Handler , typename ErrHandler >
auto	create_forwarder (Handler &&handler, ErrHandler &&err_handler)
	an helper for creation forwarder_t
template<typename Handler >
auto	create_forwarder (Handler &&handler)
	an helper for creation forwarder_t (no-error handler case)
asio::io_context::strand &	get_strand () noexcept
	returns execution strand
void	do_process () noexcept
	process queue of messages of locality leader
Public Member Functions inherited from rotor::supervisor_t
	supervisor_t (supervisor_config_t &config)
	constructs new supervisor with optional parent supervisor
	supervisor_t (const supervisor_t &)=delete
	supervisor_t (supervisor_t &&)=delete
virtual void	do_initialize (system_context_t *ctx) noexcept override
	early actor initialization (pre-initialization)
size_t	do_process () noexcept
	process queue of messages of locality leader
virtual void	commit_unsubscription (const subscription_info_ptr_t &info) noexcept
	removes the subscription point: local address and (foreign-or-local) handler pair
void	on_start () noexcept override
	actor is fully initialized and it's supervisor has sent signal to start
void	do_shutdown (const extended_error_ptr_t &reason={}) noexcept override
	convenient method to send actor's supervisor shutdown trigger message
void	shutdown_finish () noexcept override
	finalizes shutdown
virtual void	on_child_init (actor_base_t *actor, const extended_error_ptr_t &ec) noexcept
	supervisor hook for reaction on child actor init
virtual void	on_child_shutdown (actor_base_t *actor) noexcept
	supervisor hook for reaction on child actor shutdown
void	put (message_ptr_t message)
	puts a message into internal supervisor queue for further processing
template<typename Handler >
void	subscribe (actor_base_t &actor, Handler &&handler)
	templated version of subscribe_actor
template<typename Handler >
void	unsubscribe_actor (const address_ptr_t &addr, Handler &&handler) noexcept
	convenient templated version of `unsubscribe_actor
template<typename Actor >
auto	create_actor ()
	creates child-actor builder
template<typename T , typename... Args>
request_builder_t< T >	do_request (actor_base_t &actor, const address_ptr_t &dest_addr, const address_ptr_t &reply_to, Args &&...args) noexcept
	convenient method for request building
subscription_info_ptr_t	subscribe (const handler_ptr_t &handler, const address_ptr_t &addr, const actor_base_t *owner_ptr, owner_tag_t owner_tag) noexcept
	main subscription implementation
spawner_t	spawn (factory_t) noexcept
	returns an actor spawner
const address_ptr_t &	get_registry_address () const noexcept
	returns registry actor address (if it was defined or registry actor was created)
template<typename T >
auto &	access () noexcept
	generic non-public fields accessor
template<typename T , typename... Args>
auto	access (Args... args) noexcept
	generic non-public methods accessor
template<typename Handler >
subscription_info_ptr_t	subscribe (Handler &&h, const address_ptr_t &addr) noexcept
	subscribes actor's handler to process messages on the specified address
template<typename Handler >
subscription_info_ptr_t	subscribe (Handler &&h) noexcept
	subscribes actor's handler to process messages on the actor's "main" address
Public Member Functions inherited from rotor::actor_base_t
	actor_base_t (config_t &cfg)
	constructs actor and links it's supervisor
template<typename M , typename... Args>
void	send (const address_ptr_t &addr, Args &&...args)
	sends message to the destination address
template<typename R , typename... Args>
request_builder_t< typename request_wrapper_t< R >::request_t >	request (const address_ptr_t &dest_addr, Args &&...args)
	returns request builder for destination address using the "main" actor address
template<typename R , typename... Args>
request_builder_t< typename request_wrapper_t< R >::request_t >	request_via (const address_ptr_t &dest_addr, const address_ptr_t &reply_addr, Args &&...args)
	returns request builder for destination address using the specified address for reply
template<typename Request , typename... Args>
void	reply_to (Request &message, Args &&...args)
	convenient method for constructing and sending response to a request
template<typename Request >
void	reply_with_error (Request &message, const extended_error_ptr_t &ec)
	convenient method for constructing and sending error response to a request
template<typename Request , typename... Args>
auto	make_response (Request &message, Args &&...args)
	makes response to the request, but does not send it.
template<typename Request >
auto	make_response (Request &message, const extended_error_ptr_t &ec)
	makes error response to the request, but does not send it.
template<typename Handler >
subscription_info_ptr_t	subscribe (Handler &&h, const address_ptr_t &addr) noexcept
	subscribes actor's handler to process messages on the specified address
template<typename Handler >
subscription_info_ptr_t	subscribe (Handler &&h) noexcept
	subscribes actor's handler to process messages on the actor's "main" address
template<typename Handler , typename = is_handler<Handler>>
void	unsubscribe (Handler &&h, address_ptr_t &addr) noexcept
	unsubscribes actor's handler from process messages on the specified address
template<typename Handler , typename = is_handler<Handler>>
void	unsubscribe (Handler &&h) noexcept
	unsubscribes actor's handler from processing messages on the actor's "main" address
void	unsubscribe (const handler_ptr_t &h) noexcept
	initiates handler unsubscription from the default actor address
void	activate_plugins () noexcept
	starts plugins activation
void	commit_plugin_activation (plugin::plugin_base_t &plugin, bool success) noexcept
	finishes plugin activation, successful or not
void	deactivate_plugins () noexcept
	starts plugins deactivation
void	commit_plugin_deactivation (plugin::plugin_base_t &plugin) noexcept
	finishes plugin deactivation
void	on_subscription (message::subscription_t &message) noexcept
	propagates subscription message to corresponding actors
void	on_unsubscription (message::unsubscription_t &message) noexcept
	propagates unsubscription message to corresponding actors
void	on_unsubscription_external (message::unsubscription_external_t &message) noexcept
	propagates external unsubscription message to corresponding actors
address_ptr_t	create_address () noexcept
	creates new unique address for an actor (via address_maker plugin)
virtual void	shutdown_start () noexcept
	starts shutdown procedure, e.g. upon receiving shutdown request
void	shutdown_continue () noexcept
	polls plugins for shutdown
virtual void	init_start () noexcept
	starts initialization procedure
void	init_continue () noexcept
	polls plugins whether they completed initialization.
virtual void	init_finish () noexcept
	finalizes initialization
virtual void	configure (plugin::plugin_base_t &plugin) noexcept
	main callback for plugin configuration when it's ready
template<typename T >
auto &	access () noexcept
	generic non-public fields accessor
template<typename T , typename... Args>
auto	access (Args... args) noexcept
	generic non-public methods accessor
template<typename T >
auto &	access () const noexcept
	generic non-public fields accessor
template<typename T , typename... Args>
auto	access (Args... args) const noexcept
	generic non-public methods accessor
const address_ptr_t &	get_address () const noexcept
	returns actor's main address
supervisor_t &	get_supervisor () const noexcept
	returns actor's supervisor
template<typename Delegate , typename Method , typename = std::enable_if_t<std::is_invocable_v<Method, Delegate *, request_id_t, bool>>>
request_id_t	start_timer (const pt::time_duration &interval, Delegate &delegate, Method method) noexcept
	spawns a new one-shot timer
void	cancel_timer (request_id_t request_id) noexcept
	cancels previously started timer
const extended_error_ptr_t &	get_shutdown_reason () const noexcept
	returns actor shutdown reason
const std::string &	get_identity () const noexcept
	retuns human-readable actor identity
virtual bool	should_restart () const noexcept
	whether spawner should create a new instance of the actor
template<typename Request , typename... Args>
request_builder_t< typename request_wrapper_t< Request >::request_t >	request (const address_ptr_t &dest_addr, Args &&...args)
	makes an request to the destination address with the message constructed from args
template<typename Request , typename... Args>
request_builder_t< typename request_wrapper_t< Request >::request_t >	request_via (const address_ptr_t &dest_addr, const address_ptr_t &reply_addr, Args &&...args)
	makes an request to the destination address with the message constructed from args

Protected Types
using	timer_ptr_t = std::unique_ptr< timer_t >
	unique pointer to timer
using	timers_map_t = std::unordered_map< request_id_t, timer_ptr_t >
	timer id to timer pointer mapping type
using	guard_t = asio::executor_work_guard< asio::io_context::executor_type >
	guard type : alias for asio executor_work_guard
using	guard_ptr_t = std::unique_ptr< guard_t >
	alias for a guard
Protected Types inherited from rotor::supervisor_t
using	request_map_t = std::unordered_map< request_id_t, request_curry_t >
	timer to response with timeout procedure type
Protected Types inherited from rotor::actor_base_t
using	timers_map_t = std::unordered_map< request_id_t, timer_handler_ptr_t >
	timer-id to timer-handler map (type)
using	requests_t = std::unordered_set< request_id_t >
	list of ids of active requests (type)

Protected Member Functions
void	do_start_timer (const pt::time_duration &interval, timer_handler_base_t &handler) noexcept override
	starts non-recurring timer (to be implemented in descendants)
void	do_cancel_timer (request_id_t timer_id) noexcept override
	cancels timer (to be implemented in descendants)
Protected Member Functions inherited from rotor::supervisor_t
virtual address_ptr_t	instantiate_address (const void *locality) noexcept
	creates new address with respect to supervisor locality mark
void	on_request_trigger (request_id_t timer_id, bool cancelled) noexcept
	invoked as timer callback; creates response or just clean up for previously set request
virtual void	intercept (message_ptr_t &message, const void *tag, const continuation_t &continuation) noexcept
	intercepts message delivery for the tagged handler
Protected Member Functions inherited from rotor::actor_base_t
void	on_timer_trigger (request_id_t request_id, bool cancelled) noexcept
	triggers timer handler associated with the timer id
template<typename Delegate , typename Method >
void	start_timer (request_id_t request_id, const pt::time_duration &interval, Delegate &delegate, Method method) noexcept
	starts timer with pre-forged timer id (aka request-id
void	assign_shutdown_reason (extended_error_ptr_t reason) noexcept
	helper-method, which assigns shutdown reason if it isn't set
extended_error_ptr_t	make_error (const std::error_code &ec, const extended_error_ptr_t &next={}, const message_ptr_t &request={}) const noexcept
	makes extended error within the context of the actor
virtual bool	on_unlink (const address_ptr_t &server_addr) noexcept
	notification, when actor has been unlinked from server actor
plugin::plugin_base_t *	get_plugin (const std::type_index &) const noexcept
	finds plugin by plugin class identity

Protected Attributes
timers_map_t	timers_map
	timer id to timer pointer mapping
supervisor_config_asio_t::strand_ptr_t	strand
	config for the supervisor
guard_ptr_t	guard
	guard to control ownership of the io-context
Protected Attributes inherited from rotor::supervisor_t
system_context_t *	context
	non-owning pointer to system context.
messages_queue_t	queue
	queue of unprocessed messages
request_id_t	last_req_id
	counter for request/timer ids
request_map_t	request_map
	timer to response with timeout procedure
subscription_t	subscription_map
	main subscription support class
supervisor_t *	parent
	non-owning pointer to parent supervisor, NULL for root supervisor
plugin::delivery_plugin_base_t *	delivery = nullptr
	delivery plugin pointer
plugin::child_manager_plugin_t *	manager = nullptr
	child manager plugin pointer
supervisor_t *	locality_leader
	root supervisor for the locality
inbound_queue_t	inbound_queue
	inbound queue for external messages
size_t	inbound_queue_size
	size of inbound queue
pt::time_duration	poll_duration
	how much time spend in active inbound queue polling
const std::atomic_bool *	shutdown_flag = nullptr
	when flag is set, the supervisor will shut self down
pt::time_duration	shutdown_poll_frequency = pt::millisec{100}
	frequency to check atomic shutdown flag
Protected Attributes inherited from rotor::actor_base_t
intrusive_ptr_t< message::init_request_t >	init_request
	suspended init request message
intrusive_ptr_t< message::shutdown_request_t >	shutdown_request
	suspended shutdown request message
address_ptr_t	address
	actor address
address_ptr_t	spawner_address
	actor spawner address
std::string	identity
	actor identity, which might have some meaning for developers
supervisor_t *	supervisor
	non-owning pointer to actor's execution / infrastructure context
plugin_storage_ptr_t	plugins_storage
	opaque plugins storage (owning)
plugins_t	plugins
	non-owning list of plugins
pt::time_duration	init_timeout
	timeout for actor initialization (used by supervisor)
pt::time_duration	shutdown_timeout
	timeout for actor shutdown (used by supervisor)
state_t	state
	current actor state
plugin::address_maker_plugin_t *	address_maker = nullptr
	non-owning pointer to address_maker plugin
plugin::lifetime_plugin_t *	lifetime = nullptr
	non-owning pointer to lifetime plugin
plugin::link_server_plugin_t *	link_server = nullptr
	non-owning pointer to link_server plugin
plugin::resources_plugin_t *	resources = nullptr
	non-owning pointer to resources plugin
std::set< const std::type_index * >	activating_plugins
	set of activating plugin identities
std::set< const std::type_index * >	deactivating_plugins
	set of deactivating plugin identities
timers_map_t	timers_map
	timer-id to timer-handler map
requests_t	active_requests
	list of ids of active requests
std::uint32_t	continuation_mask = 0
	set of currently processing states, i.e. init or shutdown
extended_error_ptr_t	shutdown_reason
	explanation, why actor is been requested for shut down

Additional Inherited Members
Static Public Attributes inherited from rotor::actor_base_t
static const constexpr std::uint32_t	PROGRESS_INIT = 1 << 0
	flag to mark, that actor is already executing initialization
static const constexpr std::uint32_t	PROGRESS_SHUTDOWN = 1 << 1
	flag to mark, that actor is already executing shutdown
static const constexpr std::uint32_t	ESCALATE_FALIURE = 1 << 2
	flag to mark, that actor is already executing shutdown
static const constexpr std::uint32_t	AUTOSHUTDOWN_SUPERVISOR = 1 << 3
	flag to mark, that actor trigger supervisor shutdown

Detailed Description

delivers rotor-messages on top of boost asio event loop using strand for serialization

The boost::asio strand guarantees, that handler, which "belongs" to the same strand will be executed sequentially. It might be called on different threads, however.

The supervisor_asio_t uses that advantage to let the messages to the supervisor and it's actors be delivered sequentially.

The "sub-supervisors" can be created, but they do not extend the sequential executing context, i.e. in the execution sense the supervisors are independent.

When there is need to "uplift" the boost::asio low-level event, into high-level rotor message, the forwarder_t can be used. It uses the strand under the hood.

If there is need to change some actor's internals from boost::asio handler, the change should be performed in synchronized way, i.e. via strand.

Member Function Documentation

do_cancel_timer()

void rotor::asio::supervisor_asio_t::do_cancel_timer ( request_id_t  timer_id )

overrideprotectedvirtualnoexcept

cancels timer (to be implemented in descendants)

Implements rotor::supervisor_t.

do_start_timer()

void rotor::asio::supervisor_asio_t::do_start_timer ( const pt::time_duration &  interval, timer_handler_base_t &  handler  )

overrideprotectedvirtualnoexcept

starts non-recurring timer (to be implemented in descendants)

Implements rotor::supervisor_t.

enqueue()

virtual void rotor::asio::supervisor_asio_t::enqueue ( message_ptr_t  message )

overridevirtualnoexcept

enqueues messages thread safe way and triggers processing

This is the only method for deliver message outside of rotor context. Basically it is put and process in the event loop context.

The thread-safety should be guaranteed by derived class and/or used event-loop.

This method is used for messaging between supervisors with different localities, event loops or threads.

Implements rotor::supervisor_t.

make_address()

virtual address_ptr_t rotor::asio::supervisor_asio_t::make_address ( )

overridevirtualnoexcept

creates new address_t linked with the supervisor

Reimplemented from rotor::supervisor_t.

shutdown()

virtual void rotor::asio::supervisor_asio_t::shutdown ( )

overridevirtualnoexcept

thread-safe version of do_shutdown, i.e. send shutdown request let it be processed by the supervisor

Implements rotor::supervisor_t.

shutdown_finish()

virtual void rotor::asio::supervisor_asio_t::shutdown_finish ( )

overridevirtualnoexcept

finalizes shutdown

The shutdown response is sent and actor state is set to SHUT_DOWN.

This is the last action in the shutdown sequence. No further methods will be invoked on the actor.

All unfinished requests and untriggered timers will be cancelled by force in the method.

Reimplemented from rotor::actor_base_t.

start()

virtual void rotor::asio::supervisor_asio_t::start ( )

overridevirtualnoexcept

thread-safe version of do_process

Starts supervisor to processing messages queue in safe thread/loop context. Once it becomes empty, the method returns

Implements rotor::supervisor_t.

---

The documentation for this struct was generated from the following file:

• /home/b/development/cpp/cpp-rotor/include/rotor/asio/supervisor_asio.h