so_5::agent_t Class Reference

A base class for agents. More...

#include <agent.hpp>

Inheritance diagram for so_5::agent_t:

Public Types
using	context_t = so_5::agent_context_t
	Short alias for agent_context.
using	state_t = so_5::state_t
	Short alias for so_5::state_t.
template<typename T >
using	mhood_t = so_5::mhood_t< T >
	Short alias for so_5::mhood_t.
template<typename T >
using	mutable_mhood_t = so_5::mutable_mhood_t< T >
	Short alias for so_5::mutable_mhood_t.
using	initial_substate_of = so_5::initial_substate_of
	Short alias for so_5::initial_substate_of.
using	substate_of = so_5::substate_of
	Short alias for so_5::substate_of.
Public Types inherited from so_5::message_limit::message_limit_methods_mixin_t
using	any_unspecified_message

Public Member Functions
	agent_t (environment_t &env)
	Constructor.
	agent_t (environment_t &env, agent_tuning_options_t tuning_options)
	Constructor which allows specification of agent's tuning options.
	agent_t (context_t ctx)
	Constructor which simplifies agent construction with or without agent's tuning options.
virtual	~agent_t ()
const agent_t *	self_ptr () const
	Get the raw pointer of itself.
agent_t *	self_ptr ()
virtual void	so_evt_start ()
	Hook on agent start inside SObjectizer.
virtual void	so_evt_finish ()
	Hook of agent finish in SObjectizer.
const state_t &	so_current_state () const
	Access to the current agent state.
bool	so_is_active_state (const state_t &state_to_check) const noexcept
	Is a state activated?
void	so_add_nondestroyable_listener (agent_state_listener_t &state_listener)
	Add a state listener to the agent.
void	so_add_destroyable_listener (agent_state_listener_unique_ptr_t state_listener)
	Add a state listener to the agent.
virtual exception_reaction_t	so_exception_reaction () const noexcept
	A reaction from SObjectizer to an exception from agent's event.
void	so_switch_to_awaiting_deregistration_state ()
	Switching agent to special state in case of unhandled exception.
const mbox_t &	so_direct_mbox () const
	Get the agent's direct mbox.
mbox_t	so_make_new_direct_mbox ()
	Create a new direct mbox for that agent.
environment_t &	so_environment () const noexcept
	Access to the SObjectizer Environment which this agent is belong.
coop_handle_t	so_coop () const
	Get a handle of agent's coop.
void	so_bind_to_dispatcher (event_queue_t &queue) noexcept
	Binding agent to the dispatcher.
void	so_deregister_agent_coop (int dereg_reason)
	A helper method for deregistering agent's coop.
void	so_deregister_agent_coop_normally ()
	A helper method for deregistering agent's coop in case of normal deregistration.
template<typename Lambda >
decltype(auto)	so_low_level_exec_as_event_handler (Lambda &&lambda) noexcept(noexcept(lambda()))
	Helper method that allows to run a block of code as non-thread-safe event handler.
disp_binder_shptr_t	so_this_agent_disp_binder () const
	Returns the dispatcher binder that is used for binding this agent.
disp_binder_shptr_t	so_this_coop_disp_binder () const
	Returns the dispatcher binder that is used as the default binder for the agent's coop.
agent_identity_t	so_agent_name () const noexcept
	Get an optional name of the agent.
Changing agent's state.
void	so_change_state (const state_t &new_state)
	Change the current state of the agent.
void	so_deactivate_agent ()
	Deactivate the agent.
Subscription methods.
subscription_bind_t	so_subscribe (const mbox_t &mbox_ref)
	Initiate subscription.
subscription_bind_t	so_subscribe_self ()
	Initiate subscription to agent's direct mbox.
void	so_create_event_subscription (const mbox_t &mbox_ref, std::type_index type_index, const state_t &target_state, const event_handler_method_t &method, thread_safety_t thread_safety, event_handler_kind_t handler_kind)
	Create a subscription for an event.
void	so_destroy_event_subscription (const mbox_t &mbox, const std::type_index &subscription_type, const state_t &target_state)
	Destroy event subscription.
template<typename Method_Pointer >
std::enable_if< details::is_agent_method_pointer< details::method_arity::unary, Method_Pointer >::value, void >::type	so_drop_subscription (const mbox_t &mbox, const state_t &target_state, Method_Pointer)
	Drop subscription for the state specified.
template<class Message >
void	so_drop_subscription (const mbox_t &mbox, const state_t &target_state)
	Drop subscription for the state specified.
template<typename Method_Pointer >
std::enable_if< details::is_agent_method_pointer< details::method_arity::unary, Method_Pointer >::value, void >::type	so_drop_subscription (const mbox_t &mbox, Method_Pointer)
	Drop subscription for the default agent state.
template<class Message >
void	so_drop_subscription (const mbox_t &mbox)
	Drop subscription for the default agent state.
template<typename Method_Pointer >
std::enable_if< details::is_agent_method_pointer< details::method_arity::unary, Method_Pointer >::value, void >::type	so_drop_subscription_for_all_states (const mbox_t &mbox, Method_Pointer)
	Drop subscription for all states.
template<class Message >
void	so_drop_subscription_for_all_states (const mbox_t &mbox)
	Drop subscription for all states.
template<class Message >
bool	so_has_subscription (const mbox_t &mbox, const state_t &target_state) const noexcept
	Check the presence of a subscription.
template<class Message >
bool	so_has_subscription (const mbox_t &mbox) const noexcept
	Check the presence of a subscription in the default_state.
template<typename Method_Pointer >
std::enable_if< details::is_agent_method_pointer< details::method_arity::unary, Method_Pointer >::value, bool >::type	so_has_subscription (const mbox_t &mbox, const state_t &target_state, Method_Pointer) const noexcept
	Check the presence of a subscription.
template<typename Method_Pointer >
std::enable_if< details::is_agent_method_pointer< details::method_arity::unary, Method_Pointer >::value, bool >::type	so_has_subscription (const mbox_t &mbox, Method_Pointer) const noexcept
	Check the presence of a subscription.
Methods for dealing with deadletter subscriptions.
void	so_create_deadletter_subscription (const mbox_t &mbox, const std::type_index &msg_type, const event_handler_method_t &method, thread_safety_t thread_safety)
	Create a subscription for a deadletter handler.
void	so_destroy_deadletter_subscription (const mbox_t &mbox, const std::type_index &msg_type)
	Destroy a subscription for a deadletter handler.
template<typename Event_Handler >
void	so_subscribe_deadletter_handler (const so_5::mbox_t &mbox, Event_Handler &&handler, thread_safety_t thread_safety=thread_safety_t::unsafe)
	Create a subscription for deadletter handler for a specific message from a specific mbox.
template<typename Message >
void	so_drop_deadletter_handler (const so_5::mbox_t &mbox)
	Drops the subscription for deadletter handler.
template<typename Message >
bool	so_has_deadletter_handler (const so_5::mbox_t &mbox) const noexcept
	Checks the presence of deadletter handler for a message of a specific type from a specific mbox.
Methods for dealing with message delivery filters.
template<typename Message >
void	so_set_delivery_filter (const mbox_t &mbox, delivery_filter_unique_ptr_t filter)
	Set a delivery filter.
template<typename Lambda >
void	so_set_delivery_filter (const mbox_t &mbox, Lambda &&lambda)
	Set a delivery filter.
template<typename Lambda >
void	so_set_delivery_filter_for_mutable_msg (const mbox_t &mbox, Lambda &&lambda)
	Set a delivery filter for a mutable message.
template<typename Message >
void	so_drop_delivery_filter (const mbox_t &mbox) noexcept
	Drop a delivery filter.
Dealing with priority.
priority_t	so_priority () const noexcept
	Get the priority of the agent.

Static Public Member Functions
static void	call_push_event (agent_t &agent, const message_limit::control_block_t *limit, mbox_id_t mbox_id, const std::type_index &msg_type, const message_ref_t &message)
	Push an event to the agent's event queue.
static agent_tuning_options_t	tuning_options ()
	Create tuning options object with default values.
template<typename Lambda >
static custom_direct_mbox_factory_t	custom_direct_mbox_factory (Lambda &&lambda)
	Helper for creation a custom direct mbox factory.
static execution_hint_t	so_create_execution_hint (execution_demand_t &demand)
	Create execution hint for the specified demand.
Static Public Member Functions inherited from so_5::message_limit::message_limit_methods_mixin_t
template<typename Msg >
static drop_indicator_t< Msg >	limit_then_drop (unsigned int limit)
	A helper function for creating drop_indicator.
template<typename Msg >
static abort_app_indicator_t< Msg >	limit_then_abort (unsigned int limit)
	A helper function for creating abort_app_indicator.
template<typename M , typename L >
static log_then_abort_app_indicator_t< M, L >	limit_then_abort (unsigned int limit, L lambda)
	A helper function for creating log_then_abort_app_indicator.
template<typename Msg , typename Lambda >
static redirect_indicator_t< Msg, Lambda >	limit_then_redirect (unsigned int limit, Lambda dest_getter)
	A helper function for creating redirect_indicator.
template<typename Msg >
static auto	limit_then_redirect (unsigned int limit, mbox_t destination)
	A helper function for creating redirect_indicator.
template<typename Lambda >
static auto	limit_then_transform (unsigned int limit, Lambda &&transformator)
	A helper function for creating transform_indicator.
template<typename Source , typename Lambda >
static transform_indicator_t< Source >	limit_then_transform (unsigned int limit, Lambda &&transformator)
	A helper function for creating transform_indicator.
template<typename Msg , typename... Args>
static transformed_message_t< Msg >	make_transformed (mbox_t mbox, Args &&... args)
	Helper method for creating message transformation result.
Static Public Member Functions inherited from so_5::name_for_agent_methods_mixin_t
static name_for_agent_t	name_for_agent (std::string_view name)
	A helper factory for making name_for_agent_t instance.

Static Public Attributes
static constexpr const state_t::history_t	shallow_history
	Short alias for so_5::state_t::history_t::shallow.
static constexpr const state_t::history_t	deep_history
	Short alias for so_5::state_t::history_t::deep.

Protected Member Functions
Accessing the default state.
const state_t &	so_default_state () const
	Access to the agent's default state.
Agent initialization methods.
void	so_initiate_agent_definition ()
	A correct initiation of so_define_agent method call.
virtual void	so_define_agent ()
	Hook on define agent for SObjectizer.
bool	so_was_defined () const
	Is method define_agent already called?

Private Types
enum class	agent_status_t : char { not_defined_yet , defined , state_switch_in_progress }
	Enumeration of possible agent statuses. More...
using	handler_finder_t
	Type of function for searching event handler.

Private Member Functions
void	destroy_all_subscriptions_and_filters () noexcept
	Destroy all agent's subscriptions.
agent_ref_t	create_ref ()
	Make an agent reference.
void	ensure_operation_is_on_working_thread (const char *operation_name) const
	Enables operation only if it is performed on agent's working thread.
void	drop_all_delivery_filters () noexcept
	Drops all delivery filters.
void	do_set_delivery_filter (const mbox_t &mbox, const std::type_index &msg_type, delivery_filter_unique_ptr_t filter)
	Set a delivery filter.
void	do_drop_delivery_filter (const mbox_t &mbox, const std::type_index &msg_type) noexcept
	Drop a delivery filter.
void	do_change_agent_state (const state_t &state_to_be_set)
	Perform actual operations related to state switch.
void	do_state_switch (const state_t &state_to_be_set) noexcept
	Actual action for switching agent state.
void	return_to_default_state_if_possible () noexcept
	Return agent to the default state.
bool	is_agent_deactivated () const noexcept
	Is agent already deactivated.
Embedding agent into the SObjectizer Run-time.
void	bind_to_coop (coop_t &coop)
	Bind agent to the cooperation.
void	shutdown_agent () noexcept
	Agent shutdown deriver.
Subscription/unsubscription implementation details.
abstract_message_sink_t &	detect_sink_for_message_type (const std::type_index &msg_type)
	Helper function that returns a message sink to be used for subscriptions for specified message type.
void	do_drop_subscription (const mbox_t &mbox, const std::type_index &msg_type, const state_t &target_state)
	Remove subscription for the state specified.
void	do_drop_subscription_for_all_states (const mbox_t &mbox, const std::type_index &msg_type)
	Remove subscription for all states.
bool	do_check_subscription_presence (const mbox_t &mbox, const std::type_index &msg_type, const state_t &target_state) const noexcept
	Check the presence of a subscription.
bool	do_check_deadletter_presence (const mbox_t &mbox, const std::type_index &msg_type) const noexcept
	Check the presence of a deadletter handler.
Event handling implementation details.
void	push_event (const message_limit::control_block_t *limit, mbox_id_t mbox_id, const std::type_index &msg_type, const message_ref_t &message)
	Push event into the event queue.
Private Member Functions inherited from so_5::atomic_refcounted_t
	atomic_refcounted_t (const atomic_refcounted_t &)=delete
atomic_refcounted_t &	operator= (const atomic_refcounted_t &)=delete
	atomic_refcounted_t () noexcept
	Default constructor.
	~atomic_refcounted_t () noexcept=default
	Destructor.
void	inc_ref_count () noexcept
	Increments reference count.
unsigned long	dec_ref_count () noexcept
	Decrement reference count.

Static Private Member Functions
static void	process_message (current_thread_id_t working_thread_id, execution_demand_t &d, thread_safety_t thread_safety, event_handler_method_t method)
	Actual implementation of message handling.
static void	process_enveloped_msg (current_thread_id_t working_thread_id, execution_demand_t &d, const impl::event_handler_data_t *handler_data)
	Actual implementation of enveloped message handling.
static const impl::event_handler_data_t *	handler_finder_msg_tracing_disabled (execution_demand_t &demand, const char *context_marker)
	Handler finder for the case when message delivery tracing is disabled.
static const impl::event_handler_data_t *	handler_finder_msg_tracing_enabled (execution_demand_t &demand, const char *context_marker)
	Handler finder for the case when message delivery tracing is enabled.
static const impl::event_handler_data_t *	find_event_handler_for_current_state (execution_demand_t &demand)
	Actual search for event handler with respect to parent-child relationship between agent states.
static const impl::event_handler_data_t *	find_deadletter_handler (execution_demand_t &demand)
	Search for event handler between deadletter handlers.

Private Attributes
const state_t	st_default { self_ptr(), "<DEFAULT>" }
const state_t *	m_current_state_ptr
	Current agent state.
agent_status_t	m_current_status
	Current agent status.
impl::state_listener_controller_t	m_state_listener_controller
	State listeners controller.
handler_finder_t	m_handler_finder
	Function for searching event handler.
impl::subscription_storage_unique_ptr_t	m_subscriptions
	All agent's subscriptions.
std::unique_ptr< impl::sinks_storage_t >	m_message_sinks
	Holder of message sinks for that agent.
environment_t &	m_env
	SObjectizer Environment for which the agent is belong.
default_rw_spinlock_t	m_event_queue_lock
	Event queue operation protector.
event_queue_t *	m_event_queue
	A pointer to event_queue.
const mbox_t	m_direct_mbox
	A direct mbox for the agent.
so_5::current_thread_id_t	m_working_thread_id
	Working thread id.
coop_t *	m_agent_coop
	Agent is belong to this cooperation.
std::unique_ptr< impl::delivery_filter_storage_t >	m_delivery_filters
	Delivery filters for that agents.
const priority_t	m_priority
	Priority of the agent.
disp_binder_shptr_t	m_disp_binder
	Binder for this agent.
const name_for_agent_t	m_name
	Optional name for the agent.

Friends
class	subscription_bind_t
class	state_t
class	so_5::impl::mpsc_mbox_t
class	so_5::impl::state_switch_guard_t
class	so_5::impl::internal_agent_iface_t
class	so_5::enveloped_msg::impl::agent_demand_handler_invoker_t
template<typename T >
class	intrusive_ptr_t

Demand handlers.
void	ensure_binding_finished ()
	Ensures that all agents from cooperation are bound to dispatchers.
static void	demand_handler_on_start (current_thread_id_t working_thread_id, execution_demand_t &d)
	Calls so_evt_start method for agent.
static demand_handler_pfn_t	get_demand_handler_on_start_ptr () noexcept
static void	demand_handler_on_finish (current_thread_id_t working_thread_id, execution_demand_t &d)
	Calls so_evt_finish method for agent.
static demand_handler_pfn_t	get_demand_handler_on_finish_ptr () noexcept
static void	demand_handler_on_message (current_thread_id_t working_thread_id, execution_demand_t &d)
	Calls event handler for message.
static demand_handler_pfn_t	get_demand_handler_on_message_ptr () noexcept
static void	demand_handler_on_enveloped_msg (current_thread_id_t working_thread_id, execution_demand_t &d)
	Handles the enveloped message.
static demand_handler_pfn_t	get_demand_handler_on_enveloped_msg_ptr () noexcept

Detailed Description

A base class for agents.

An agent in SObjctizer must be derived from the agent_t.

The base class provides various methods whose can be splitted into the following groups:

• methods for the interaction with SObjectizer;
• predefined hook-methods which are called during: cooperation registration, starting and stopping of an agent;
• methods for the message subscription and unsubscription;
• methods for working with an agent state;

Methods for the interaction with SObjectizer

Method so_5::agent_t::so_environment() serves for the access to the SObjectizer Environment (and, therefore, to all methods of the SObjectizer Environment). This method could be called immediatelly after the agent creation. This is because agent is bound to the SObjectizer Environment during the creation process.

Hook methods

The base class defines several hook-methods. Its default implementation do nothing.

The method agent_t::so_define_agent() is called just before agent will started by SObjectizer as a part of the agent registration process. It should be reimplemented for the initial subscription of the agent to messages.

There are two hook-methods related to important agent's lifetime events: agent_t::so_evt_start() and agent_t::so_evt_finish(). They are called by SObjectizer in next circumstances:

• method so_evt_start() is called when the agent is starting its work inside of SObjectizer. At that moment all agents are defined (all their methods agent_t::so_define_agent() have executed);
• method so_evt_finish() is called during the agent's cooperation deregistration just after agent processed the last pending event.

Methods so_evt_start() and so_evt_finish() are called by SObjectizer and user can just reimplement them to implement the agent-specific logic.

Message subscription and unsubscription methods

Any method with one of the following prototypes can be used as an event handler:

return_type evt_handler( mhood_t< Message > msg );
return_type evt_handler( const mhood_t< Message > & msg );
return_type evt_handler( const Message & msg );
return_type evt_handler( Message msg );
// Since v.5.5.20:
return_type evt_handler( mhood_t< Message > msg ) const;
return_type evt_handler( const mhood_t< Message > & msg ) const;
return_type evt_handler( const Message & msg ) const;
return_type evt_handler( Message msg ) const;

Where evt_handler is a name of the event handler, Message is a message type.

The class mhood_t is a wrapper on pointer to an instance of the Message. It is very similar to std::unique_ptr. The pointer to Message can be a nullptr. It happens in case when the message has no actual data and servers just a signal about something.

Please note that handlers with the following prototypes can be used only for messages, not signals:

return_type evt_handler( const Message & msg );
return_type evt_handler( Message msg );
// Since v.5.5.20:
return_type evt_handler( const Message & msg ) const;
return_type evt_handler( Message msg ) const;

A subscription to the message is performed by the methods so_subscribe() and so_subscribe_self(). This method returns an instance of the so_5::subscription_bind_t which does all actual actions of the subscription process. This instance already knows agents and message mbox and uses the default agent state for the event subscription (binding to different state is also possible).

The presence of a subscription can be checked by so_has_subscription() method.

A subscription can be dropped (removed) by so_drop_subscription() and so_drop_subscription_for_all_states() methods.

Deadletter handlers subscription and unsubscription

Since v.5.5.21 SObjectizer supports deadletter handlers. Such handlers are called if there is no any ordinary event handler for a specific messages from a specific mbox.

Deadletter handler can be implemented by an agent method or by lambda function. Deadletter handler can have one of the following formats:

void evt_handler( mhood_t< Message > msg );
void return_type evt_handler( mhood_t< Message > msg ) const;
void return_type evt_handler( const mhood_t< Message > & msg );
void return_type evt_handler( const mhood_t< Message > & msg ) const;
void return_type evt_handler( const Message & msg );
void return_type evt_handler( const Message & msg ) const;
void return_type evt_handler( Message msg );
void return_type evt_handler( Message msg ) const;

Subscription for a deadletter handler can be created by so_subscribe_deadletter_handler() method.

The presence of a deadletter handler can be checked by so_has_deadletter_handler() method.

A deadletter can be dropped (removed) by so_drop_deadletter_handler() and so_drop_subscription_for_all_states() methods.

Methods for working with an agent state

The agent can change its state by his so_change_state() method.

An attempt to switch an agent to the state which belongs to the another agent is an error. If state is belong to the same agent there are no possibility to any run-time errors. In this case changing agent state is a very safe operation.

In some cases it is necessary to detect agent state switching. For example for application monitoring purposes. This can be done by "state listeners".

Any count of state listeners can be set for an agent. There are two methods for that:

• so_add_nondestroyable_listener() is for listeners whose lifetime are controlled by a programmer, not by SObjectizer;
• so_add_destroyable_listener() is for listeners whose lifetime must be controlled by agent itself.

Work thread identification

Since v.5.4.0 some operations for agent are enabled only on agent's work thread. They are:

• subscription management operations (creation or dropping);
• changing agent's state.

Work thread for an agent is defined as follows:

• before invocation of so_define_agent() the work thread is a thread on which agent is created (id of that thread is detected in agent's constructor);
• during cooperation registration the working thread is a thread on which so_environment::register_coop() is working;
• after successful agent registration the work thread for it is specified by the dispatcher.

Note

Some dispatchers could provide several work threads for an agent. In such case there would not be work thread id. And operations like changing agent state or creation of subscription would be prohibited after agent registration.

Accessing dispatcher binders

Since v.5.8.1 there are two methods that allow to get a dispatcher binder related to the agent or agent's coop:

• so_this_agent_disp_binder(). It returns the dispatcher binder that is used for binding the agent itself;
• so_this_coop_disp_binder(). It returns the dispatcher binder that is the default disp binder for the agent's coop.

Please note that binders returned by so_this_agent_disp_binder() and so_this_coop_disp_binder() may be different binders.

Examples

so_5/adv_thread_pool_fifo/main.cpp, so_5/agent_name/main.cpp, so_5/bind_transformer/main.cpp, so_5/blinking_led/main.cpp, so_5/chameneos_prealloc_msgs/main.cpp, so_5/chameneos_simple/main.cpp, so_5/child_soenv/main.cpp, so_5/chstate/main.cpp, so_5/chstate_msg_tracing/main.cpp, so_5/coop_listener/main.cpp, so_5/coop_notification/main.cpp, so_5/coop_user_resources/main.cpp, so_5/custom_direct_mbox/main.cpp, so_5/custom_error_logger/main.cpp, so_5/custom_work_thread_factory/main.cpp, so_5/deadletter_handler/main.cpp, so_5/default_message_limits/main.cpp, so_5/delivery_filters/main.cpp, so_5/disp/main.cpp, so_5/dispatcher_for_children/main.cpp, so_5/dispatcher_for_children_2/main.cpp, so_5/dispatcher_hello/main.cpp, so_5/dispatcher_restarts/main.cpp, so_5/exception_logger/main.cpp, so_5/exception_reaction/main.cpp, so_5/hardwork_imit/main.cpp, so_5/hello_all/main.cpp, so_5/hello_delay/main.cpp, so_5/hello_evt_handler/main.cpp, so_5/hello_evt_lambda/main.cpp, so_5/hello_periodic/main.cpp, so_5/hello_world/main.cpp, so_5/hello_world_simple_not_mtsafe/main.cpp, so_5/individual_msg_tracing/main.cpp, so_5/intercom_statechart/main.cpp, so_5/introduce_named_mbox/main.cpp, so_5/machine_control/main.cpp, so_5/make_agent_ref/main.cpp, so_5/make_new_direct_mbox/main.cpp, so_5/make_pipeline/main.cpp, so_5/many_timers/main.cpp, so_5/modify_resend_as_immutable/main.cpp, so_5/mutable_msg_agents/main.cpp, so_5/named_dispatchers_layer/main.cpp, so_5/news_board/main.cpp, so_5/nohandler_msg_tracing/main.cpp, so_5/parent_coop/main.cpp, so_5/ping_pong/main.cpp, so_5/ping_pong_minimal/main.cpp, so_5/ping_pong_with_owner/main.cpp, so_5/prio_work_stealing/main.cpp, so_5/producer_consumer_mchain/main.cpp, so_5/queue_size_stats/main.cpp, so_5/redirect_and_transform/main.cpp, so_5/selective_msg_tracing/main.cpp, so_5/simple_message_deadline/main.cpp, so_5/single_sink_binding/main.cpp, so_5/state_deep_history/main.cpp, so_5/stop_guard/main.cpp, so_5/subscriptions/main.cpp, so_5/two_handlers/main.cpp, so_5/unique_subscribers_mbox/main.cpp, and so_5/wrapped_env_demo_2/main.cpp.

Definition at line 669 of file agent.hpp.

Member Typedef Documentation

context_t

using so_5::agent_t::context_t = so_5::agent_context_t

Short alias for agent_context.

Since

v.5.5.4

Definition at line 692 of file agent.hpp.

handler_finder_t

using so_5::agent_t::handler_finder_t

private

Initial value:

 
      const impl::event_handler_data_t *(*)(
          execution_demand_t & ,
          const char *  )

Type of function for searching event handler.

Since

v.5.5.9

Definition at line 2810 of file agent.hpp.

initial_substate_of

using so_5::agent_t::initial_substate_of = so_5::initial_substate_of

Short alias for so_5::initial_substate_of.

Since

v.5.5.15

Definition at line 718 of file agent.hpp.

mhood_t

template<typename T >

using so_5::agent_t::mhood_t = so_5::mhood_t< T >

Short alias for so_5::mhood_t.

Since

v.5.5.14

Definition at line 705 of file agent.hpp.

mutable_mhood_t

template<typename T >

using so_5::agent_t::mutable_mhood_t = so_5::mutable_mhood_t< T >

Short alias for so_5::mutable_mhood_t.

Since

v.5.5.19

Definition at line 712 of file agent.hpp.

state_t

using so_5::agent_t::state_t = so_5::state_t

Short alias for so_5::state_t.

Since

v.5.5.13

Definition at line 698 of file agent.hpp.

substate_of

using so_5::agent_t::substate_of = so_5::substate_of

Short alias for so_5::substate_of.

Since

v.5.5.15

Definition at line 724 of file agent.hpp.

Member Enumeration Documentation

agent_status_t

enum class so_5::agent_t::agent_status_t : char

strongprivate

Enumeration of possible agent statuses.

Since

v.5.5.18

Enumerator
not_defined_yet	Agent is not defined yet. This is an initial agent status.
defined	Agent is defined.
state_switch_in_progress	State switch operation is in progress.

Definition at line 2784 of file agent.hpp.

Constructor & Destructor Documentation

agent_t() [1/3]

so_5::agent_t::agent_t ( environment_t & env )

explicit

Constructor.

Agent must be bound to the SObjectizer Environment during its creation. And that binding cannot be changed anymore.

Parameters

env	The Environment for this agent must exist.

Examples

so_5/bind_transformer/main.cpp, so_5/coop_listener/main.cpp, so_5/hardwork_imit/main.cpp, so_5/hello_delay/main.cpp, so_5/hello_evt_handler/main.cpp, so_5/hello_evt_lambda/main.cpp, so_5/hello_periodic/main.cpp, so_5/hello_world/main.cpp, so_5/make_new_direct_mbox/main.cpp, so_5/news_board/main.cpp, so_5/parent_coop/main.cpp, and so_5/producer_consumer_mchain/main.cpp.

Definition at line 646 of file agent.cpp.

agent_t() [2/3]

so_5::agent_t::agent_t	(	environment_t &	env,
		agent_tuning_options_t	tuning_options )

Constructor which allows specification of agent's tuning options.

Usage sample:

using namespace so_5;
class my_agent : public agent_t
{
public :
  my_agent( environment_t & env )
  : agent_t( env, agent_t::tuning_options()
      .subscription_storage_factory(
          vector_based_subscription_storage_factory() ) )
  {...}
}

Since

v.5.5.3

Definition at line 652 of file agent.cpp.

agent_t() [3/3]

so_5::agent_t::agent_t ( context_t ctx )

explicit

Constructor which simplifies agent construction with or without agent's tuning options.

Usage sample:

class my_agent : public so_5::agent_t
{
public :
  my_agent( context_t ctx )
  : so_5::agent( ctx + limit_then_drop< get_status >(1) )
  {}
 ...
};
class my_more_specific_agent : public my_agent
{
public :
  my_more_specific_agent( context_t ctx )
  : my_agent( ctx + limit_then_drop< reconfigure >(1) )
  {}
};
 
// Then somewhere in the code:
auto coop = env.make_coop();
auto a = coop->make_agent< my_agent >();
auto b = coop->make_agent< my_more_specific_agent >();

Since

v.5.5.4

Definition at line 659 of file agent.cpp.

~agent_t()

so_5::agent_t::~agent_t ( )

virtual

Definition at line 693 of file agent.cpp.

Member Function Documentation

bind_to_coop()

void so_5::agent_t::bind_to_coop ( coop_t & coop )

private

Bind agent to the cooperation.

Initializes an internal cooperation pointer.

Parameters

coop	Cooperation for that agent.

Definition at line 1023 of file agent.cpp.

call_push_event()

static void so_5::agent_t::call_push_event ( agent_t & agent, const message_limit::control_block_t * limit, mbox_id_t mbox_id, const std::type_index & msg_type, const message_ref_t & message )

inlinestatic

Push an event to the agent's event queue.

This method is used by SObjectizer for the agent's event scheduling.

Definition at line 1037 of file agent.hpp.

create_ref()

agent_ref_t so_5::agent_t::create_ref ( )

private

Make an agent reference.

This is an internal SObjectizer method. It is called when it is guaranteed that the agent is still necessary and something has reference to it.

Definition at line 1016 of file agent.cpp.

custom_direct_mbox_factory()

template<typename Lambda >

static custom_direct_mbox_factory_t so_5::agent_t::custom_direct_mbox_factory ( Lambda && lambda )

inlinestaticnodiscard

Helper for creation a custom direct mbox factory.

Usage example:

class my_agent : public so_5::agent_t {
  ...
public:
  my_agent( context_t ctx )
    : so_5::agent_t{ ctx + custom_direct_mbox_factory(
        []( so_5::partially_constructed_agent_ptr_t agent_ptr,
            so_5::mbox_t actual_mbox )
        {
          return so_5::mbox_t{ new my_custom_mbox{ agent_ptr.ptr(), std::move(actual_mbox) } };
        } )
      }
  {...}
 
  ...
};

Since

v.5.7.4

Examples

so_5/custom_direct_mbox/main.cpp.

Definition at line 1135 of file agent.hpp.

demand_handler_on_enveloped_msg()

void so_5::agent_t::demand_handler_on_enveloped_msg ( current_thread_id_t working_thread_id, execution_demand_t & d )

static

Handles the enveloped message.

Since

v.5.5.23

Definition at line 1394 of file agent.cpp.

demand_handler_on_finish()

void so_5::agent_t::demand_handler_on_finish ( current_thread_id_t working_thread_id, execution_demand_t & d )

static

Calls so_evt_finish method for agent.

Since

v.5.2.0

Definition at line 1329 of file agent.cpp.

demand_handler_on_message()

void so_5::agent_t::demand_handler_on_message ( current_thread_id_t working_thread_id, execution_demand_t & d )

static

Calls event handler for message.

Since

v.5.2.0

Definition at line 1371 of file agent.cpp.

demand_handler_on_start()

void so_5::agent_t::demand_handler_on_start ( current_thread_id_t working_thread_id, execution_demand_t & d )

static

Calls so_evt_start method for agent.

Since

v.5.2.0

Definition at line 1287 of file agent.cpp.

destroy_all_subscriptions_and_filters()

void so_5::agent_t::destroy_all_subscriptions_and_filters ( )

privatenoexcept

Destroy all agent's subscriptions.

Note

This method is intended to be used in the destructor and methods like so_deactivate_agent().

Attention

It's noexcept method because there is no way to recover in case when deletion of subscriptions throws.

Since

v.5.7.3

Definition at line 1009 of file agent.cpp.

detect_sink_for_message_type()

abstract_message_sink_t & so_5::agent_t::detect_sink_for_message_type ( const std::type_index & msg_type )

nodiscardprivate

Helper function that returns a message sink to be used for subscriptions for specified message type.

Since

v.5.8.0

Definition at line 1153 of file agent.cpp.

do_change_agent_state()

void so_5::agent_t::do_change_agent_state ( const state_t & state_to_be_set )

private

Perform actual operations related to state switch.

It throws if the agent in awaiting_deregistration_state and state_to_be_set isn't awaiting_deregistration_state.

Note

This method doesn't check the working context. It's assumed that this check has already been performed by caller.

Since

v.5.7.3

Parameters

state_to_be_set

New state to be set as the current state.

Definition at line 1637 of file agent.cpp.

do_check_deadletter_presence()

bool so_5::agent_t::do_check_deadletter_presence ( const mbox_t & mbox, const std::type_index & msg_type ) const

privatenoexcept

Check the presence of a deadletter handler.

Since

v.5.5.21

Parameters

mbox	Message's mbox.
msg_type	Message type.

Definition at line 1209 of file agent.cpp.

do_check_subscription_presence()

bool so_5::agent_t::do_check_subscription_presence ( const mbox_t & mbox, const std::type_index & msg_type, const state_t & target_state ) const

privatenoexcept

Check the presence of a subscription.

Since

v.5.5.19.5

Parameters

mbox	Message's mbox.
msg_type	Message type.
target_state	State for the subscription.

Definition at line 1199 of file agent.cpp.

do_drop_delivery_filter()

void so_5::agent_t::do_drop_delivery_filter ( const mbox_t & mbox, const std::type_index & msg_type )

privatenoexcept

Drop a delivery filter.

Since

v.5.5.5

Definition at line 1548 of file agent.cpp.

do_drop_subscription()

void so_5::agent_t::do_drop_subscription ( const mbox_t & mbox, const std::type_index & msg_type, const state_t & target_state )

private

Remove subscription for the state specified.

Since

v.5.2.3

Parameters

mbox	Message's mbox.
msg_type	Message type.
target_state	State for event.

Definition at line 1169 of file agent.cpp.

do_drop_subscription_for_all_states()

void so_5::agent_t::do_drop_subscription_for_all_states ( const mbox_t & mbox, const std::type_index & msg_type )

private

Remove subscription for all states.

Since

v.5.2.3

Parameters

mbox	Message's mbox.
msg_type	Message type.

Definition at line 1184 of file agent.cpp.

do_set_delivery_filter()

void so_5::agent_t::do_set_delivery_filter ( const mbox_t & mbox, const std::type_index & msg_type, delivery_filter_unique_ptr_t filter )

private

Set a delivery filter.

Since

v.5.5.5

Definition at line 1520 of file agent.cpp.

do_state_switch()

void so_5::agent_t::do_state_switch ( const state_t & state_to_be_set )

privatenoexcept

Actual action for switching agent state.

Since

v.5.5.15

Parameters

state_to_be_set

New state to be set as the current state.

Definition at line 1678 of file agent.cpp.

drop_all_delivery_filters()

void so_5::agent_t::drop_all_delivery_filters ( )

privatenoexcept

Drops all delivery filters.

Since

v.5.5.0

Definition at line 1510 of file agent.cpp.

ensure_binding_finished()

void so_5::agent_t::ensure_binding_finished

(

)

Ensures that all agents from cooperation are bound to dispatchers.

Since

v.5.5.8

Definition at line 1314 of file agent.cpp.

ensure_operation_is_on_working_thread()

void so_5::agent_t::ensure_operation_is_on_working_thread ( const char * operation_name ) const

private

Enables operation only if it is performed on agent's working thread.

Since

v.5.4.0

Definition at line 1485 of file agent.cpp.

find_deadletter_handler()

const impl::event_handler_data_t * so_5::agent_t::find_deadletter_handler ( execution_demand_t & demand )

staticprivate

Search for event handler between deadletter handlers.

Returns

nullptr if event handler is not found.

Since

v.5.5.21

Definition at line 1627 of file agent.cpp.

find_event_handler_for_current_state()

const impl::event_handler_data_t * so_5::agent_t::find_event_handler_for_current_state ( execution_demand_t & demand )

staticprivate

Actual search for event handler with respect to parent-child relationship between agent states.

Since

v.5.5.15

Definition at line 1606 of file agent.cpp.

get_demand_handler_on_enveloped_msg_ptr()

demand_handler_pfn_t so_5::agent_t::get_demand_handler_on_enveloped_msg_ptr ( )

staticnoexcept

Since

v.5.5.24

Definition at line 1406 of file agent.cpp.

get_demand_handler_on_finish_ptr()

demand_handler_pfn_t so_5::agent_t::get_demand_handler_on_finish_ptr ( )

staticnoexcept

Note

This method is necessary for GCC on Cygwin.

Since

v.5.4.0

Definition at line 1365 of file agent.cpp.

get_demand_handler_on_message_ptr()

demand_handler_pfn_t so_5::agent_t::get_demand_handler_on_message_ptr ( )

staticnoexcept

Note

This method is necessary for GCC on Cygwin.

Since

v.5.4.0

Definition at line 1388 of file agent.cpp.

get_demand_handler_on_start_ptr()

demand_handler_pfn_t so_5::agent_t::get_demand_handler_on_start_ptr ( )

staticnoexcept

Note

This method is necessary for GCC on Cygwin.

Since

v.5.4.0

Definition at line 1323 of file agent.cpp.

handler_finder_msg_tracing_disabled()

const impl::event_handler_data_t * so_5::agent_t::handler_finder_msg_tracing_disabled ( execution_demand_t & demand, const char * context_marker )

staticprivate

Handler finder for the case when message delivery tracing is disabled.

Since

v.5.5.9

Definition at line 1559 of file agent.cpp.

handler_finder_msg_tracing_enabled()

const impl::event_handler_data_t * so_5::agent_t::handler_finder_msg_tracing_enabled ( execution_demand_t & demand, const char * context_marker )

staticprivate

Handler finder for the case when message delivery tracing is enabled.

Since

v.5.5.9

Definition at line 1572 of file agent.cpp.

is_agent_deactivated()

bool so_5::agent_t::is_agent_deactivated ( ) const

privatenoexcept

Is agent already deactivated.

Deactivated agent is in awaiting_deregistration_state. This method checks that the current state of the agent is awaiting_deregistration_state.

Attention

This method isn't thread safe and should be used with care. A caller should guarantee that it's called from the right working thread.

Since

v.5.7.3

Definition at line 1753 of file agent.cpp.

process_enveloped_msg()

void so_5::agent_t::process_enveloped_msg ( current_thread_id_t working_thread_id, execution_demand_t & d, const impl::event_handler_data_t * handler_data )

staticprivate

Actual implementation of enveloped message handling.

Note

handler_data can be nullptr. It means that an event handler for that message type if not found and special hook will be called for the envelope.

Since

v.5.5.23

Definition at line 1445 of file agent.cpp.

process_message()

void so_5::agent_t::process_message ( current_thread_id_t working_thread_id, execution_demand_t & d, thread_safety_t thread_safety, event_handler_method_t method )

staticprivate

Actual implementation of message handling.

Note

Since v.5.5.17.1 argument method is passed as copy. It prevents deallocation of event_handler_method in the following case:

auto mbox = so_environment().create_mbox();
so_subscribe( mbox ).event< some_signal >( [this, mbox] {
  so_drop_subscription< some_signal >( mbox );
  ... // Some other actions.
} );

Attention

Implementation notes: it's important that method is passed by value. It's because subscription can be deleted during the work of process_message (due to unsubscription inside the event handler) and if pass method by a reference then that reference can become invalid.

Since

v.5.4.0

Definition at line 1412 of file agent.cpp.

push_event()

void so_5::agent_t::push_event ( const message_limit::control_block_t * limit, mbox_id_t mbox_id, const std::type_index & msg_type, const message_ref_t & message )

private

Push event into the event queue.

Parameters

limit	Optional message limit.
mbox_id	ID of mbox for this event.
msg_type	Message type for event.
message	Event message.

Definition at line 1265 of file agent.cpp.

return_to_default_state_if_possible()

void so_5::agent_t::return_to_default_state_if_possible ( )

privatenoexcept

Return agent to the default state.

Note

This method is called just before invocation of so_evt_finish() to return agent to the default state. This return will initiate invocation of on_exit handlers for all active states of the agent.

Attention

State switch is not performed if agent is already in default state or if it waits deregistration after unhandled exception.

Since

v.5.5.15

Definition at line 1741 of file agent.cpp.

self_ptr() [1/2]

agent_t * so_5::agent_t::self_ptr ( )

inline

Definition at line 840 of file agent.hpp.

self_ptr() [2/2]

const agent_t * so_5::agent_t::self_ptr ( ) const

inline

Get the raw pointer of itself.

This method is intended for use in the member initialization list instead 'this' to suppres compiler warnings. For example for an agent state initialization:

class a_sample_t : public so_5::agent_t
{
    typedef so_5::agent_t base_type_t;
 
    // Agent state.
    const so_5::state_t m_sample_state;
  public:
    a_sample_t( so_5::environment_t & env )
      :
        base_type_t( env ),
        m_sample_state( self_ptr() )
    {
      // ...
    }
 
  // ...
 
};

Definition at line 834 of file agent.hpp.

shutdown_agent()

void so_5::agent_t::shutdown_agent ( )

privatenoexcept

Agent shutdown deriver.

Method destroys all agent subscriptions.

Since

v.5.2.3

Definition at line 1029 of file agent.cpp.

so_add_destroyable_listener()

void so_5::agent_t::so_add_destroyable_listener

(

agent_state_listener_unique_ptr_t

state_listener

)

Add a state listener to the agent.

Agent takes care of the state_listener destruction.

Definition at line 737 of file agent.cpp.

so_add_nondestroyable_listener()

void so_5::agent_t::so_add_nondestroyable_listener

(

agent_state_listener_t &

state_listener

)

Add a state listener to the agent.

A programmer should guarantee that the lifetime of state_listener is exceeds lifetime of the agent.

Definition at line 728 of file agent.cpp.

so_agent_name()

agent_identity_t so_5::agent_t::so_agent_name ( ) const

nodiscardnoexcept

Get an optional name of the agent.

If agent has the name then a reference to this name will be returned. Otherwise a small object with a pointer to agent will be returned.

The result can be printed to std::ostream or converted into a string:

class my_agent final : public so_5::agent_t
{
...
  void so_evt_start() override
  {
    std::cout << so_agent_name() << ": started" << std::endl;
    ...
    so_5::send<std::string>(some_mbox, so_agent_name().to_string());
  }
  void so_evt_finished() override
  {
    std::cout << so_agent_name() << ": stopped" << std::endl;
  }
...
}

Attention

This method returns a lightweight object that just holds a reference to the agent's name (or a pointer to the agent). This object should not be stored for the long time, because the references/pointers it holds may become invalid. If you have to store the agent name for a long time please convert the returned value into std::string and store the resulting std::string object.

Since

v.5.8.2

Examples

so_5/agent_name/main.cpp.

Definition at line 1000 of file agent.cpp.

so_bind_to_dispatcher()

void so_5::agent_t::so_bind_to_dispatcher ( event_queue_t & queue )

noexcept

Binding agent to the dispatcher.

This is an actual start of agent's work in SObjectizer.

Note

This method was a de-facto noexcept in previous versions of SObjectizer. But didn't marked as noexcept because of need of support old C++ compilers. Since v.5.6.0 it is officially noexcept.

Since

v.5.4.0

Parameters

queue

Actual event queue for an agent.

Definition at line 872 of file agent.cpp.

so_change_state()

void so_5::agent_t::so_change_state

(

const state_t &

new_state

)

Change the current state of the agent.

Usage sample:

void a_sample_t::evt_smth( mhood_t< message_one_t > msg )
{
  // If something wrong with the message then we should
  // switch to the error_state.
  if( error_in_data( *msg ) )
    so_change_state( m_error_state );
}

Attention

This method has to be called from a worker thread assigned to the agent by the dispatcher. This method can't be called from thread_safe event-handlers because so_change_state() modifies the state of the agent.

Parameters

new_state

New agent state.

Definition at line 811 of file agent.cpp.

so_coop()

coop_handle_t so_5::agent_t::so_coop ( ) const

nodiscard

Get a handle of agent's coop.

Note

This method is a replacement for so_coop_name() method from previous versions of SObjectizer-5.

Attention

If this method is called when agent is not registered (e.g. there is no coop for agent) then this method will throw.

Usage example:

class parent final : public so_5::agent_t {
  ...
  void so_evt_start() override {
    // Create a child coop.
    auto coop = so_environment().make_coop(
      // We as a parent coop.
      so_coop() );
    ...; // Fill the coop.
    so_environment().register_coop( std::move(coop) );
  }
};

Since

v.5.6.0

Examples

so_5/custom_work_thread_factory/main.cpp.

Definition at line 860 of file agent.cpp.

so_create_deadletter_subscription()

void so_5::agent_t::so_create_deadletter_subscription	(	const mbox_t &	mbox,
		const std::type_index &	msg_type,
		const event_handler_method_t &	method,
		thread_safety_t	thread_safety )

Create a subscription for a deadletter handler.

Note

This is low-level method intended to be used by libraries writters. Do not call it directly if you don't understand its purpose and what its arguments mean. Use so_subscribe_deadletter_handler() instead.

This method actually creates a subscription to deadletter handler for messages/signal of type msg_type from mbox mbox.

Exceptions

so_5::exception_t

in the case when the subscription of a deadletter handler for type msg_type from mbox is already exists.

Since

v.5.5.21

Parameters

mbox	Message's mbox.
msg_type	Message type.
method	Event handler caller.
thread_safety	Thread safety of the event handler.

Definition at line 1114 of file agent.cpp.

so_create_event_subscription()

void so_5::agent_t::so_create_event_subscription	(	const mbox_t &	mbox_ref,
		std::type_index	type_index,
		const state_t &	target_state,
		const event_handler_method_t &	method,
		thread_safety_t	thread_safety,
		event_handler_kind_t	handler_kind )

Create a subscription for an event.

Note

Before v.5.5.21 it was a private method. Since v.5.5.21 it is a public method with a standard so_-prefix. It was made public to allow creation of subscriptions to agent from outside of agent.

Parameter handler_kind was introduced in v.5.7.0.

Parameters

mbox_ref	Message's mbox.
type_index	Message type.
target_state	State for event.
method	Event handler caller.
thread_safety	Thread safety of the event handler.
handler_kind	Kind of that event handler.

Definition at line 1083 of file agent.cpp.

so_create_execution_hint()

execution_hint_t so_5::agent_t::so_create_execution_hint ( execution_demand_t & demand )

static

Create execution hint for the specified demand.

The hint returned is intendent for the immediately usage. It must not be stored for the long time and used sometime in the future. It is because internal state of the agent can be changed and some references from hint object to agent's internals become invalid.

Since

v.5.4.0

Parameters

demand

Demand for execution of event handler.

Definition at line 901 of file agent.cpp.

so_current_state()

const state_t & so_5::agent_t::so_current_state ( ) const

inline

Access to the current agent state.

Note

There is a change in behaviour of this methon in v.5.5.22. If some on_enter/on_exit handler calls this method during the state change procedure this method will return the state for which this on_enter/on_exit handler is called. For example:

class demo final : public so_5::agent_t {
  state_t st_1{ this };
  state_t st_1_1{ initial_substate_of{st_1} };
  state_t st_1_2{ substate_of{st_1}};
  ...
  virtual void so_define_agent() override {
    st_1.on_enter([this]{
      assert(st_1 == so_current_state());
      ...
    });
    st_1_1.on_enter([this]{
      assert(st_1_1 == so_current_state());
      ...
    });
    ...
  }
};

Definition at line 934 of file agent.hpp.

so_deactivate_agent()

void so_5::agent_t::so_deactivate_agent

(

)

Deactivate the agent.

This method deactivates the agent:

• drops all agent's subscriptions (including deadletter handlers) and delivery filters;
• switches the agent to a special state in that the agent does nothing and just waits the deregistration.

Sometimes it is necessary to mark an agent as 'failed'. Such an agent shouldn't process anything and the only thing that is allowed is waiting for the deregistration. For example:

class some_agent final : public so_5::agent_t
{
  state_t st_working{ this, "working" };
  state_t st_failed{ this, "failed" };
  ...
  void on_enter_st_failed()
  {
    // Notify some supervisor about the failure.
    // It will deregister the whole cooperation with failed agent.
    so_5::send<msg_failure>( supervisor_mbox(), ... );
  }
  ...
  void so_define_agent() override
  {
    this >>= st_working;
 
    st_failed.on_enter( &some_agent::on_enter_st_failed );
 
    ...
  }
 
  void evt_some_event(mhood_t<some_msg> cmd)
  {
    try
    {
      do_some_processing_of(*cmd);
    }
    catch(...)
    {
      // Processing failed, agent can't continue work normally.
      // Have to switch it to the failed state and wait for
      // the deregistration.
      this >>= st_failed;
    }
  }
  ...
};

This approach works but has a couple of drawbacks:

• it's necessary to define a separate state for an agent (like st_failed shown above);
• agent still has all its subscriptions. It means that messages will be delivered to the agent's event queue and dispatched by the agent's dispatcher. They won't be handled because there are no subscriptions in a state like st_failed, but message dispatching will consume some resources, although the agent is a special 'failed' state.

To cope with those drawbacks so_deactivate_agent was introduced in v.5.7.3. That method drops all agent's subscriptions (including deadletter handlers and delivery filters) and switches the agent to a special hidden state in that the agent doesn't handle anything.

The example above now can be rewritten that way:

class some_agent final : public so_5::agent_t
{
  state_t st_working{ this, "working" };
  ...
  void switch_to_failed_state()
  {
    // Notify some supervisor about the failure.
    // It will deregister the whole cooperation with failed agent.
    so_5::send<msg_failure>( supervisor_mbox(), ... );
    // Deactivate the agent.
    so_deactivate_agent();
  }
  ...
  void so_define_agent() override
  {
    this >>= st_working;
    ...
  }
 
  void evt_some_event(mhood_t<some_msg> cmd)
  {
    try
    {
      do_some_processing_of(*cmd);
    }
    catch(...)
    {
      // Processing failed, agent can't continue work normally.
      // Have to switch it to the failed state and wait for
      // the deregistration.
      switch_to_failed_state();
    }
  }
  ...
};

Note

The method uses so_change_state(), so it has all requirements of so_change_state(). Because the agent state will be changed, so_deactivate_state() has to be called on the working thread assigned to the agent by the dispatcher, and so_deactivate_state() can't be invoked from a thread_safe event handler.

Attention

The method is not noexcept, it can throw an exception. So additional care has to be taken when it's called in catch-block and/or in noexcept contexts.

Since

v.5.7.3

Definition at line 820 of file agent.cpp.

so_default_state()

const state_t & so_5::agent_t::so_default_state ( ) const

protected

Access to the agent's default state.

Examples

so_5/chameneos_prealloc_msgs/main.cpp, so_5/chameneos_simple/main.cpp, so_5/chstate_msg_tracing/main.cpp, so_5/coop_notification/main.cpp, so_5/coop_user_resources/main.cpp, so_5/default_message_limits/main.cpp, so_5/dispatcher_for_children/main.cpp, so_5/dispatcher_for_children_2/main.cpp, so_5/dispatcher_hello/main.cpp, so_5/dispatcher_restarts/main.cpp, so_5/ping_pong_with_owner/main.cpp, so_5/queue_size_stats/main.cpp, so_5/redirect_and_transform/main.cpp, and so_5/simple_message_deadline/main.cpp.

Definition at line 775 of file agent.cpp.

so_define_agent()

void so_5::agent_t::so_define_agent ( )

protectedvirtual

Hook on define agent for SObjectizer.

This method is called by SObjectizer during the cooperation registration process before agent will be bound to its working thread.

Should be used by the agent to make necessary message subscriptions.

Usage sample;

class a_sample_t : public so_5::agent_t
{
  // ...
  virtual void
  so_define_agent();
 
  void evt_handler_1( mhood_t< message1 > msg );
  // ...
  void evt_handler_N( mhood_t< messageN > & msg );
 
};
 
void
a_sample_t::so_define_agent()
{
  // Make subscriptions...
  so_subscribe( m_mbox1 )
    .in( m_state_1 )
      .event( &a_sample_t::evt_handler_1 );
  // ...
  so_subscribe( m_mboxN )
    .in( m_state_N )
      .event( &a_sample_t::evt_handler_N );
}

Reimplemented in so_5::experimental::testing::v1::details::mbox_receives_msg_impl::a_msg_catcher_t< Msg >.

Examples

so_5/agent_name/main.cpp, so_5/chameneos_prealloc_msgs/main.cpp, so_5/chameneos_simple/main.cpp, so_5/chstate/main.cpp, so_5/chstate_msg_tracing/main.cpp, so_5/coop_notification/main.cpp, so_5/coop_user_resources/main.cpp, so_5/custom_direct_mbox/main.cpp, so_5/custom_error_logger/main.cpp, so_5/custom_work_thread_factory/main.cpp, so_5/default_message_limits/main.cpp, so_5/dispatcher_for_children/main.cpp, so_5/dispatcher_for_children_2/main.cpp, so_5/dispatcher_hello/main.cpp, so_5/dispatcher_restarts/main.cpp, so_5/hardwork_imit/main.cpp, so_5/hello_all/main.cpp, so_5/hello_delay/main.cpp, so_5/hello_evt_handler/main.cpp, so_5/hello_evt_lambda/main.cpp, so_5/hello_periodic/main.cpp, so_5/individual_msg_tracing/main.cpp, so_5/introduce_named_mbox/main.cpp, so_5/machine_control/main.cpp, so_5/make_agent_ref/main.cpp, so_5/many_timers/main.cpp, so_5/named_dispatchers_layer/main.cpp, so_5/news_board/main.cpp, so_5/parent_coop/main.cpp, so_5/ping_pong_minimal/main.cpp, so_5/ping_pong_with_owner/main.cpp, so_5/prio_work_stealing/main.cpp, so_5/producer_consumer_mchain/main.cpp, so_5/queue_size_stats/main.cpp, so_5/redirect_and_transform/main.cpp, so_5/selective_msg_tracing/main.cpp, so_5/simple_message_deadline/main.cpp, so_5/single_sink_binding/main.cpp, so_5/subscriptions/main.cpp, so_5/unique_subscribers_mbox/main.cpp, and so_5/wrapped_env_demo_2/main.cpp.

Definition at line 841 of file agent.cpp.

so_deregister_agent_coop()

void so_5::agent_t::so_deregister_agent_coop

(

int

dereg_reason

)

A helper method for deregistering agent's coop.

Usage example:

class demo : public so_5::agent_t {
...
    void on_some_event(mhood_t<some_msg> cmd) {
        try {
            ... // Some processing.
            if(no_more_work_left())
                // Normal deregistration of the coop.
                so_deregister_agent_coop_normally();
        }
        catch(...) {
            // Some error.
            // Deregister the coop with special 'exit code'.
            so_deregister_agent_coop(so_5::dereg_reason::user_defined_reason+10);
        }
    }
};

Since

v.5.4.0

Definition at line 975 of file agent.cpp.

so_deregister_agent_coop_normally()

void so_5::agent_t::so_deregister_agent_coop_normally

(

)

A helper method for deregistering agent's coop in case of normal deregistration.

Note

It is just a shorthand for:

so_deregister_agent_coop( so_5::dereg_reason::normal );

Since

v.5.4.0

Examples

so_5/agent_name/main.cpp, so_5/chstate_msg_tracing/main.cpp, so_5/coop_notification/main.cpp, so_5/coop_user_resources/main.cpp, so_5/custom_direct_mbox/main.cpp, so_5/custom_error_logger/main.cpp, so_5/custom_work_thread_factory/main.cpp, so_5/deadletter_handler/main.cpp, so_5/default_message_limits/main.cpp, so_5/dispatcher_for_children/main.cpp, so_5/dispatcher_for_children_2/main.cpp, so_5/dispatcher_hello/main.cpp, so_5/dispatcher_restarts/main.cpp, so_5/individual_msg_tracing/main.cpp, so_5/introduce_named_mbox/main.cpp, so_5/make_agent_ref/main.cpp, so_5/make_new_direct_mbox/main.cpp, so_5/many_timers/main.cpp, so_5/modify_resend_as_immutable/main.cpp, so_5/mutable_msg_agents/main.cpp, so_5/named_dispatchers_layer/main.cpp, so_5/nohandler_msg_tracing/main.cpp, so_5/parent_coop/main.cpp, so_5/ping_pong_with_owner/main.cpp, so_5/selective_msg_tracing/main.cpp, so_5/simple_message_deadline/main.cpp, so_5/single_sink_binding/main.cpp, so_5/two_handlers/main.cpp, and so_5/unique_subscribers_mbox/main.cpp.

Definition at line 982 of file agent.cpp.

so_destroy_deadletter_subscription()

void so_5::agent_t::so_destroy_deadletter_subscription	(	const mbox_t &	mbox,
		const std::type_index &	msg_type )

Destroy a subscription for a deadletter handler.

Note

This is low-level method intended to be used by libraries writters. Do not call it directly if you don't understand its purpose and what its arguments mean. Use so_drop_deadletter_handler() instead.

This method actually destroys a subscription to deadletter handler for messages/signal of type msg_type from mbox mbox.

Note

It is safe to call this method if there is no such deadletter handler. It will do nothing in such case.

Since

v.5.5.21

Parameters

mbox	Message's mbox.
msg_type	Message type.

Definition at line 1139 of file agent.cpp.

so_destroy_event_subscription()

void so_5::agent_t::so_destroy_event_subscription ( const mbox_t & mbox, const std::type_index & subscription_type, const state_t & target_state )

inline

Destroy event subscription.

Note

This method was introduced in v.5.5.21 to allow manipulation of agent's subscriptions from outside of an agent.

It is safe to try to destroy nonexistent subscription.

Since

v.5.5.21

Parameters

mbox	Message's mbox.
subscription_type	Message's type.
target_state	Target state of a subscription.

Definition at line 1461 of file agent.hpp.

so_direct_mbox()

const mbox_t & so_5::agent_t::so_direct_mbox

(

)

const

Get the agent's direct mbox.

Since

v.5.4.0

Examples

so_5/chameneos_simple/main.cpp, so_5/coop_notification/main.cpp, so_5/custom_error_logger/main.cpp, so_5/deadletter_handler/main.cpp, so_5/dispatcher_for_children_2/main.cpp, so_5/dispatcher_hello/main.cpp, so_5/dispatcher_restarts/main.cpp, so_5/introduce_named_mbox/main.cpp, so_5/named_dispatchers_layer/main.cpp, so_5/news_board/main.cpp, so_5/parent_coop/main.cpp, so_5/ping_pong_with_owner/main.cpp, so_5/producer_consumer_mchain/main.cpp, so_5/redirect_and_transform/main.cpp, so_5/simple_message_deadline/main.cpp, so_5/stop_guard/main.cpp, so_5/unique_subscribers_mbox/main.cpp, and so_5/wrapped_env_demo_2/main.cpp.

Definition at line 762 of file agent.cpp.

so_drop_deadletter_handler()

template<typename Message >

void so_5::agent_t::so_drop_deadletter_handler ( const so_5::mbox_t & mbox )

inline

Drops the subscription for deadletter handler.

A message type must be specified explicitely via template parameter.

Usage example:

class demo : public so_5::agent_t {
  void some_deadletter_handler(mhood_t<some_message> cmd) {
    ... // Do some stuff.
    // There is no need for deadletter handler.
    so_drop_deadletter_handler<some_message>(some_mbox);
  }
  ...
};

Note

Is is safe to call this method if there is no a deadletter handler for message of type Message from message box mbox.

Template Parameters

Message

Type of a message or signal for deadletter handler.

Since

v.5.5.21

Parameters

mbox	A mbox from which the message is expected.

Definition at line 2129 of file agent.hpp.

so_drop_delivery_filter()

template<typename Message >

void so_5::agent_t::so_drop_delivery_filter ( const mbox_t & mbox )

inlinenoexcept

Drop a delivery filter.

Usage example:

// For a case of an immutable message.
void some_agent::some_event(mhood_t<my_message> cmd) {
  ... // Some actions.
  // Now we want to drop the subscription and the delivery
  // filter for this message.
  so_drop_subscription_for_all_states<my_message>(source_mbox);
  so_drop_delivery_filter<my_message>(source_mbox);
}
 
// For a case of a mutable message.
void some_agent::some_event(mutable_mhood_t<my_message> cmd) {
  ... // Some actions.
  // Now we want to drop the subscription and the delivery
  // filter for this message.
  so_drop_subscription_for_all_states<so_5::mutable_msg<my_message>>(source_mbox);
  so_drop_delivery_filter<so_5::mutable_msg<my_message>>(source_mbox);
}

Template Parameters

Message

type of message filtered.

Since

v.5.5.5

Parameters

mbox	Message box to which delivery filter was set. This must be MPMC-mbox.

Definition at line 2531 of file agent.hpp.

so_drop_subscription() [1/4]

template<class Message >

void so_5::agent_t::so_drop_subscription ( const mbox_t & mbox )

inline

Drop subscription for the default agent state.

Usage example:

class demo : public so_5::agent_t {
  void on_turn_listening_on(mhood_t<turn_on> cmd) {
    // New subscription must be created.
    so_subscribe(cmd->listening_mbox())
      .event([this](mhood_t<state_change_notify> cmd) {...});
    ...
  }
 
  void on_turn_listening_off(mhood_t<turn_off> cmd) {
    // Subscription is no more needed.
    so_drop_subscription<state_change_notify>(cmd->listening_mbox());
    ...
  }
};

Note

Doesn't throw if there is no such subscription.

Since

v.5.5.3

Definition at line 1655 of file agent.hpp.

so_drop_subscription() [2/4]

template<class Message >

void so_5::agent_t::so_drop_subscription ( const mbox_t & mbox, const state_t & target_state )

inline

Drop subscription for the state specified.

Usage example:

class demo : public so_5::agent_t {
  void on_turn_listening_on(mhood_t<turn_on> cmd) {
    // New subscription must be created.
    so_subscribe(cmd->listeting_mbox()).in(some_state)
      .event([this](mhood_t<state_change_notify> cmd) {...});
    ...
  }
 
  void on_turn_listening_off(mhood_t<turn_off> cmd) {
    // Subscription is no more needed.
    so_drop_subscription<state_change_notify>(cmd->listening_mbox(), some_state);
    ...
  }
};

Note

Doesn't throw if there is no such subscription.

Since

v.5.5.3

Definition at line 1560 of file agent.hpp.

so_drop_subscription() [3/4]

template<typename Method_Pointer >

std::enable_if< details::is_agent_method_pointer< details::method_arity::unary, Method_Pointer >::value, void >::type so_5::agent_t::so_drop_subscription ( const mbox_t & mbox, const state_t & target_state, Method_Pointer  )

inline

Drop subscription for the state specified.

This overload is indended to be used when there is an event-handler in the form of agent's method. And there is a need to unsubscribe this event handler. For example:

class demo : public so_5::agent_t {
  void on_some_event(mhood_t<some_msg> cmd) {
    if(cmd->some_condition)
      // New subscription must be created.
      so_subscribe(some_mbox).in(some_state)
        .event(&demo::one_shot_message_handler);
    ...
  }
 
  void one_shot_message_handler(mhood_t<another_msg> cmd) {
    ... // Some actions.
    // Subscription is no more needed.
    so_drop_subscription(some_mbox, some_state,
      &demo::one_shot_message_handler);
  }
};

Note

Doesn't throw if there is no such subscription.

Subscription is removed even if agent was subscribed for this message type with different method pointer. The pointer to event routine is necessary only to detect MSG type.

Since

v.5.2.3

Definition at line 1516 of file agent.hpp.

so_drop_subscription() [4/4]

template<typename Method_Pointer >

std::enable_if< details::is_agent_method_pointer< details::method_arity::unary, Method_Pointer >::value, void >::type so_5::agent_t::so_drop_subscription ( const mbox_t & mbox, Method_Pointer  )

inline

Drop subscription for the default agent state.

This overload is indended to be used when there is an event-handler in the form of agent's method. And there is a need to unsubscribe this event handler. For example:

class demo : public so_5::agent_t {
  void on_some_event(mhood_t<some_msg> cmd) {
    if(cmd->some_condition)
      // New subscription must be created.
      so_subscribe(some_mbox)
        .event(&demo::one_shot_message_handler);
    ...
  }
 
  void one_shot_message_handler(mhood_t<another_msg> cmd) {
    ... // Some actions.
    // Subscription is no more needed.
    so_drop_subscription(some_mbox,
      &demo::one_shot_message_handler);
  }
};

Note

Doesn't throw if there is no such subscription.

Subscription is removed even if agent was subscribed for this message type with different method pointer. The pointer to event routine is necessary only to detect Msg type.

Since

v.5.2.3

Definition at line 1611 of file agent.hpp.

so_drop_subscription_for_all_states() [1/2]

template<class Message >

void so_5::agent_t::so_drop_subscription_for_all_states ( const mbox_t & mbox )

inline

Drop subscription for all states.

Usage example:

class demo : public so_5::agent_t {
  state_t st_working{this}, st_waiting{this}, st_stopping{this};
  ...
  void on_turn_listening_on(mhood_t<turn_on> cmd) {
    // Make subscriptions for message of type state_change_notify.
    st_working.event(cmd->listening_mbox(),
        [this](mhood_t<state_change_notify> cmd) {...});
    st_waiting.event(cmd->listening_mbox(),
        [this](mhood_t<state_change_notify> cmd) {...});
    st_waiting.event(cmd->listening_mbox(),
        [this](mhood_t<state_change_notify> cmd) {...});
    ...
  }
  void on_turn_listening_off(mhood_t<turn_off> cmd) {
    // Subscriptions are no more needed.
    // All three event handlers for state_change_notify
    // will be unsubscribed.
    so_drop_subscription_for_all_states<state_change_notify>(cmd->listening_mbox());
  }
  ...
};

Note

Doesn't throw if there is no any subscription for that mbox and message type.

Since v.5.5.21 this method also drops the subscription for a deadletter handler for that type of message/signal.

Since

v.5.5.3

Definition at line 1770 of file agent.hpp.

so_drop_subscription_for_all_states() [2/2]

template<typename Method_Pointer >

std::enable_if< details::is_agent_method_pointer< details::method_arity::unary, Method_Pointer >::value, void >::type so_5::agent_t::so_drop_subscription_for_all_states ( const mbox_t & mbox, Method_Pointer  )

inline

Drop subscription for all states.

Usage example:

class demo : public so_5::agent_t {
  state_t st_working{this}, st_waiting{this}, st_stopping{this};
  ...
  void on_turn_listening_on(mhood_t<turn_on> cmd) {
    // Make subscriptions for message of type state_change_notify.
    st_working.event(cmd->listening_mbox(),
        &demo::on_state_notify_when_working);
    st_waiting.event(cmd->listening_mbox(),
        &demo::on_state_notify_when_waiting);
    st_waiting.event(cmd->listening_mbox(),
        &demo::on_state_notify_when_stopping);
    ...
  }
  void on_turn_listening_off(mhood_t<turn_off> cmd) {
    // Subscriptions are no more needed.
    // All three event handlers for state_change_notify
    // will be unsubscribed.
    so_drop_subscription_for_all_states(cmd->listening_mbox(),
        &demo::on_state_notify_when_working);
  }
  ...
  void on_state_notify_when_working(mhood_t<state_change_notify> cmd) {...}
  void on_state_notify_when_waiting(mhood_t<state_change_notify> cmd) {...}
  void on_state_notify_when_stopping(mhood_t<state_change_notify> cmd) {...}
};

Note

Doesn't throw if there is no any subscription for that mbox and message type.

Subscription is removed even if agent was subscribed for this message type with different method pointer. The pointer to event routine is necessary only to detect Msg type.

Since v.5.5.21 this method also drops the subscription for a deadletter handler for that type of message/signal.

Since

v.5.2.3

Definition at line 1716 of file agent.hpp.

so_environment()

environment_t & so_5::agent_t::so_environment ( ) const

noexcept

Access to the SObjectizer Environment which this agent is belong.

Usage sample for other cooperation registration:

void a_sample_t::evt_on_smth( mhood_t< some_message_t > msg )
{
  so_5::coop_unique_holder_t coop = so_environment().make_coop();
 
  // Filling the cooperation...
  coop->make_agent< a_another_t >( ... );
  // ...
 
  // Registering cooperation.
  so_environment().register_coop( std::move(coop) );
}

Usage sample for the SObjectizer shutting down:

void a_sample_t::evt_last_event( mhood_t< message_one_t > msg )
{
  ...
  so_environment().stop();
}

Examples

so_5/adv_thread_pool_fifo/main.cpp, so_5/agent_name/main.cpp, so_5/chameneos_prealloc_msgs/main.cpp, so_5/chameneos_simple/main.cpp, so_5/custom_work_thread_factory/main.cpp, so_5/disp/main.cpp, so_5/dispatcher_for_children/main.cpp, so_5/dispatcher_hello/main.cpp, so_5/dispatcher_restarts/main.cpp, so_5/exception_logger/main.cpp, so_5/hardwork_imit/main.cpp, so_5/hello_evt_handler/main.cpp, so_5/hello_evt_lambda/main.cpp, so_5/hello_periodic/main.cpp, so_5/hello_world/main.cpp, so_5/individual_msg_tracing/main.cpp, so_5/make_agent_ref/main.cpp, so_5/make_pipeline/main.cpp, so_5/named_dispatchers_layer/main.cpp, so_5/ping_pong/main.cpp, so_5/ping_pong_minimal/main.cpp, so_5/ping_pong_with_owner/main.cpp, so_5/prio_work_stealing/main.cpp, so_5/producer_consumer_mchain/main.cpp, so_5/queue_size_stats/main.cpp, so_5/selective_msg_tracing/main.cpp, so_5/stop_guard/main.cpp, and so_5/wrapped_env_demo_2/main.cpp.

Definition at line 853 of file agent.cpp.

so_evt_finish()

void so_5::agent_t::so_evt_finish ( )

virtual

Hook of agent finish in SObjectizer.

It is guaranteed that this method will be called last just before deattaching agent from it's working thread.

This method should be used to perform some cleanup actions on it's working thread.

class a_sample_t : public so_5::agent_t
{
  // ...
  virtual void
  so_evt_finish();
  // ...
};
 
a_sample_t::so_evt_finish()
{
  std::cout << "last agent activity";
 
  if( so_current_state() == m_db_error_happened )
  {
    // Delete the DB connection on the same thread where
    // connection was established and where some
    // error happened.
    m_db.release();
  }
}

Examples

so_5/agent_name/main.cpp, so_5/custom_work_thread_factory/main.cpp, so_5/disp/main.cpp, so_5/hello_world/main.cpp, so_5/make_agent_ref/main.cpp, so_5/parent_coop/main.cpp, and so_5/ping_pong_with_owner/main.cpp.

Definition at line 707 of file agent.cpp.

so_evt_start()

void so_5::agent_t::so_evt_start ( )

virtual

Hook on agent start inside SObjectizer.

It is guaranteed that this method will be called first just after end of the cooperation registration process.

During cooperation registration agent is bound to some working thread. And the first method which is called for the agent on that working thread context is this method.

class a_sample_t : public so_5::agent_t
{
  // ...
  virtual void
  so_evt_start();
  // ...
};
 
a_sample_t::so_evt_start()
{
  std::cout << "first agent action on bound dispatcher" << std::endl;
  ... // Some application logic actions.
}

Examples

so_5/agent_name/main.cpp, so_5/chameneos_prealloc_msgs/main.cpp, so_5/chameneos_simple/main.cpp, so_5/chstate/main.cpp, so_5/chstate_msg_tracing/main.cpp, so_5/coop_notification/main.cpp, so_5/coop_user_resources/main.cpp, so_5/custom_direct_mbox/main.cpp, so_5/custom_error_logger/main.cpp, so_5/custom_work_thread_factory/main.cpp, so_5/deadletter_handler/main.cpp, so_5/disp/main.cpp, so_5/dispatcher_for_children/main.cpp, so_5/dispatcher_for_children_2/main.cpp, so_5/dispatcher_hello/main.cpp, so_5/dispatcher_restarts/main.cpp, so_5/exception_logger/main.cpp, so_5/exception_reaction/main.cpp, so_5/hardwork_imit/main.cpp, so_5/hello_all/main.cpp, so_5/hello_delay/main.cpp, so_5/hello_evt_handler/main.cpp, so_5/hello_evt_lambda/main.cpp, so_5/hello_periodic/main.cpp, so_5/hello_world/main.cpp, so_5/individual_msg_tracing/main.cpp, so_5/intercom_statechart/main.cpp, so_5/introduce_named_mbox/main.cpp, so_5/machine_control/main.cpp, so_5/make_agent_ref/main.cpp, so_5/make_new_direct_mbox/main.cpp, so_5/many_timers/main.cpp, so_5/named_dispatchers_layer/main.cpp, so_5/news_board/main.cpp, so_5/nohandler_msg_tracing/main.cpp, so_5/parent_coop/main.cpp, so_5/ping_pong/main.cpp, so_5/ping_pong_minimal/main.cpp, so_5/ping_pong_with_owner/main.cpp, so_5/prio_work_stealing/main.cpp, so_5/producer_consumer_mchain/main.cpp, so_5/queue_size_stats/main.cpp, so_5/redirect_and_transform/main.cpp, so_5/selective_msg_tracing/main.cpp, so_5/simple_message_deadline/main.cpp, so_5/single_sink_binding/main.cpp, so_5/state_deep_history/main.cpp, so_5/stop_guard/main.cpp, so_5/subscriptions/main.cpp, so_5/two_handlers/main.cpp, and so_5/unique_subscribers_mbox/main.cpp.

Definition at line 701 of file agent.cpp.

so_exception_reaction()

exception_reaction_t so_5::agent_t::so_exception_reaction ( ) const

virtualnoexcept

A reaction from SObjectizer to an exception from agent's event.

If an exception is going out from agent's event it will be caught by SObjectizer. Then SObjectizer will call this method and perform some actions in dependence of return value.

Note

Since v.5.3.0 default implementation calls coop_t::exception_reaction() for agent's cooperation object.

This method is noexcept since v.5.8.0.

Since

v.5.2.3

Examples

so_5/exception_logger/main.cpp, and so_5/exception_reaction/main.cpp.

Definition at line 746 of file agent.cpp.

so_has_deadletter_handler()

template<typename Message >

bool so_5::agent_t::so_has_deadletter_handler ( const so_5::mbox_t & mbox ) const

inlinenoexcept

Checks the presence of deadletter handler for a message of a specific type from a specific mbox.

Message type must be specified explicitely via template parameter Message.

Returns

true if a deadletter for a message/signal of type Message from message mbox mbox exists.

Usage example:

class demo : public so_5::agent_t {
  void on_some_request(mhood_t<request_data> cmd) {
    if(!so_has_deadletter_handler<some_message>(some_mbox))
      // There is no deadletter handler yet.
      // It should be created now.
      so_subscribe_deadletter_handler(
        some_mbox,
        [this](mhood_t<some_message> cmd) {...});
    ...
  }
};

Template Parameters

Message

Type of a message or signal for deadletter handler.

Since

v.5.5.21

Parameters

mbox	A mbox from which the message is expected.

Definition at line 2170 of file agent.hpp.

so_has_subscription() [1/4]

template<class Message >

bool so_5::agent_t::so_has_subscription ( const mbox_t & mbox ) const

inlinenoexcept

Check the presence of a subscription in the default_state.

This method can be used to avoid an exception from so_subscribe() in the case if the subscription is already present. For example:

void my_agent::evt_create_new_subscription(mhood_t<data_source> cmd)
{
  // cmd can contain mbox we have already subscribed to.
  // If we just call so_subscribe() then an exception can be thrown.
  // Because of that check the presence of subscription first.
  if(!so_has_subscription<message>(cmd->mbox()))
  {
    // There is no subscription yet. New subscription can be
    // created.
    so_subscribe(cmd->mbox()).event(...);
  }
}

Note

Please do not call this method from outside of working context of the agent.

Returns

true if subscription is present for the default_state.

Template Parameters

Message

a type of message/signal subscription to which must be checked.

Since

v.5.5.19.5

Parameters

mbox	A mbox from which message/signal of type Message is expected.

Definition at line 1856 of file agent.hpp.

so_has_subscription() [2/4]

template<class Message >

bool so_5::agent_t::so_has_subscription ( const mbox_t & mbox, const state_t & target_state ) const

inlinenoexcept

Check the presence of a subscription.

This method can be used to avoid an exception from so_subscribe() in the case if the subscription is already present. For example:

void my_agent::evt_create_new_subscription(mhood_t<data_source> cmd)
{
  // cmd can contain mbox we have already subscribed to.
  // If we just call so_subscribe() then an exception can be thrown.
  // Because of that check the presence of subscription first.
  if(!so_has_subscription<message>(cmd->mbox(), so_default_state()))
  {
    // There is no subscription yet. New subscription can be
    // created.
    so_subscribe(cmd->mbox()).event(...);
  }
}

Note

Please do not call this method from outside of working context of the agent.

Returns

true if subscription is present for target_state.

Template Parameters

Message

a type of message/signal subscription to which must be checked.

Since

v.5.5.19.5

Parameters

mbox	A mbox from which message/signal of type Message is expected.
target_state	A target state for the subscription.

Definition at line 1811 of file agent.hpp.

so_has_subscription() [3/4]

template<typename Method_Pointer >

std::enable_if< details::is_agent_method_pointer< details::method_arity::unary, Method_Pointer >::value, bool >::type so_5::agent_t::so_has_subscription ( const mbox_t & mbox, const state_t & target_state, Method_Pointer  ) const

inlinenoexcept

Check the presence of a subscription.

Type of message is deducted from event-handler signature.

Usage example:

void my_agent::evt_create_new_subscription(mhood_t<data_source> cmd)
{
  // cmd can contain mbox we have already subscribed to.
  // If we just call so_subscribe() then an exception can be thrown.
  // Because of that check the presence of subscription first.
  if(!so_has_subscription(cmd->mbox(), my_state, &my_agent::my_event))
  {
    // There is no subscription yet. New subscription can be
    // created.
    so_subscribe(cmd->mbox()).event(...);
  }
}

Note

Please do not call this method from outside of working context of the agent.

Returns

true if subscription is present for target_state.

Since

v.5.5.19.5

Parameters

mbox	A mbox from which message/signal is expected.
target_state	A target state for the subscription.

Definition at line 1901 of file agent.hpp.

so_has_subscription() [4/4]

template<typename Method_Pointer >

std::enable_if< details::is_agent_method_pointer< details::method_arity::unary, Method_Pointer >::value, bool >::type so_5::agent_t::so_has_subscription ( const mbox_t & mbox, Method_Pointer  ) const

inlinenoexcept

Check the presence of a subscription.

Subscription is checked for the default agent state.

Type of message is deducted from event-handler signature.

Usage example:

void my_agent::evt_create_new_subscription(mhood_t<data_source> cmd)
{
  // cmd can contain mbox we have already subscribed to.
  // If we just call so_subscribe() then an exception can be thrown.
  // Because of that check the presence of subscription first.
  if(!so_has_subscription(cmd->mbox(), &my_agent::my_event))
  {
    // There is no subscription yet. New subscription can be
    // created.
    so_subscribe(cmd->mbox()).event(...);
  }
}

Note

Please do not call this method from outside of working context of the agent.

Returns

true if subscription is present for the default state.

Since

v.5.5.19.5

Parameters

mbox	A mbox from which message/signal is expected.

Definition at line 1956 of file agent.hpp.

so_initiate_agent_definition()

void so_5::agent_t::so_initiate_agent_definition ( )

protected

A correct initiation of so_define_agent method call.

Before the actual so_define_agent() method it is necessary to temporary set working thread id. And then drop this id to non-actual value after so_define_agent() return.

Because of that this method must be called during cooperation registration procedure instead of direct call of so_define_agent().

Since

v.5.4.0

Definition at line 829 of file agent.cpp.

so_is_active_state()

bool so_5::agent_t::so_is_active_state ( const state_t & state_to_check ) const

noexcept

Is a state activated?

Note

Since v.5.5.15 a state can have substates. For example state A can have substates B and C. If B is the current state then so_current_state() will return a reference to B. But state A is active too because it is a superstate for B. Method so_is_active_state(A) will return true in that case:

class demo : public so_5::agent_t
{
  state_t A{ this, "A" };
  state_t B{ initial_substate_of{ A }, "B" };
  state_t C{ substate_of{ A }, "C" };
  ...
  void some_event()
  {
    this >>= C;
 
    assert( C == so_current_state() );
    assert( !( A == so_current_state() ) );
    assert( so_is_active_state(A) );
    ...
  }
};

Attention

This method is not thread safe. Be careful calling this method from outside of agent's working thread.

Returns

true if state state_to_check is the current state or if the current state is a substate of state_to_check.

Since

v.5.5.15

Definition at line 713 of file agent.cpp.

so_low_level_exec_as_event_handler()

template<typename Lambda >

decltype(auto) so_5::agent_t::so_low_level_exec_as_event_handler ( Lambda && lambda )

inlinenoexcept

Helper method that allows to run a block of code as non-thread-safe event handler.

Attention

This is a low-level method. Using it may destroy all thread-safety guarantees provided by SObjectizer. Please use it only when you know what your are doing. All responsibility rests with the user.

Use of this method may be necessary when an agent is bound to a special dispatcher that runs not only the agent's event-handlers, but also other callbacks on the same worker thread.

A good example of such a dispatcher is so5extra's asio_one_thread dispatcher. It guarantees that an IO completion handler is called on the same worker thread as agent's event-handlers. For example:

class agent_that_uses_asio : public so_5::agent_t
{
  state_t st_not_ready{this};
  state_t st_ready{this};
 
  asio::io_context & io_ctx_;
 
public:
  agent_that_uses_asio(context_t ctx, asio::io_context & io_ctx)
    : so_5::agent_t{std::move(ctx)}
    , io_ctx_{io_ctx}
  {}
  ...
  void so_define_agent() override
  {
    st_not_ready.activate();
    ...
  }
 
  void so_evt_start() override
  {
    auto resolver = std::make_shared<asio::ip::tcp::resolver>(io_ctx_);
    resolver->async_resolve("some.host.name", "",
        asio::ip::tcp::numeric_service | asio::ip::tcp::address_configured,
        // IO completion handler to be run on agent's worker thread.
        [resolver, this](auto ec, auto results) {
          // It's necessary to wrap the block of code, otherwise
          // modification of the agent's state (or managing of subscriptions)
          // will be prohibited because SObjectizer doesn't see
          // the IO completion handler as event handler.
          so_low_level_exec_as_event_handler( [&]() {
              ...
              st_ready.activate();
            });
        });
  }
}

Attention

Using this method inside a running event-handler (non-thread-safe and especially thread-safe) is undefined behavior. SObjectizer can't check such a case without a significant performance penalty, so there won't be any warnings or errors from SObjectizer's side, anything can happen.

Since

v.5.8.0

Definition at line 2630 of file agent.hpp.

so_make_new_direct_mbox()

mbox_t so_5::agent_t::so_make_new_direct_mbox

(

)

Create a new direct mbox for that agent.

This method creates a new MPSC mbox which is connected with that agent. Only agent for that so_make_new_direct_mbox() has been called can make subscriptions for a new mbox.

Note. The new mbox doesn't replaces the standard direct mbox for the agent. Old direct mbox is still here and can still be used for sending messages to the agent. But new mbox is not related to the old direct mbox: they are different mboxes and can be used for different subscriptions. For example:

class my_agent final : public so_5::agent_t {
  ...
  void so_evt_start() override {
    so_subscribe_self().event( [](mhood_t<hello>) {
      std::cout << "hello from the direct mbox" << std::endl;
    } );
 
    const auto new_mbox = so_make_new_direct_mbox();
    so_subscribe( new_mbox ).event( [](mhood_t<hello) {
      std::cout << "hello from a new mbox" << std::endl;
    }
 
    so_5::send<hello>(*this);
    so_5::send<hello>(new_mbox);
  }
};

The output will be:

hello from the direct mbox
hello from a new mbox

Since

v.5.6.0

Examples

so_5/make_new_direct_mbox/main.cpp.

Definition at line 768 of file agent.cpp.

so_priority()

priority_t so_5::agent_t::so_priority ( ) const

inlinenodiscardnoexcept

Get the priority of the agent.

Since

v.5.5.8

Definition at line 2555 of file agent.hpp.

so_set_delivery_filter() [1/2]

template<typename Message >

void so_5::agent_t::so_set_delivery_filter ( const mbox_t & mbox, delivery_filter_unique_ptr_t filter )

inline

Set a delivery filter.

Note

Since v.5.7.4 it can be used for mutable messages too (if mbox is MPSC mbox). In that case Message should be in form so_5::mutable_msg<Message>.

Template Parameters

Message

type of message to be filtered.

Since

v.5.5.5

Parameters

mbox	Message box from which message is expected. This must be MPMC-mbox.
filter	Delivery filter instance.

Examples

so_5/machine_control/main.cpp, and so_5/queue_size_stats/main.cpp.

Definition at line 2426 of file agent.hpp.

so_set_delivery_filter() [2/2]

template<typename Lambda >

void so_5::agent_t::so_set_delivery_filter	(	const mbox_t &	mbox,
		Lambda &&	lambda )

Set a delivery filter.

Template Parameters

Lambda

type of lambda-function or functional object which must be used as message filter.

Usage sample:

void my_agent::so_define_agent() {
  so_set_delivery_filter( temp_sensor,
  []( const current_temperature & msg ) {
    return !is_normal_temperature( msg );
  } );
 ...
}

Since

v.5.5.5

Parameters

mbox	Message box from which message is expected. This must be MPMC-mbox.
lambda	Delivery filter as lambda-function or functional object.

Definition at line 3410 of file agent.hpp.

so_set_delivery_filter_for_mutable_msg()

template<typename Lambda >

void so_5::agent_t::so_set_delivery_filter_for_mutable_msg	(	const mbox_t &	mbox,
		Lambda &&	lambda )

Set a delivery filter for a mutable message.

Template Parameters

Lambda

type of lambda-function or functional object which must be used as message filter.

Note

The content of the message will be passed to delivery-filter lambda-function by a const reference.

Usage sample:

void my_agent::so_define_agent() {
  so_set_delivery_filter_for_mutable_msg( temp_sensor,
  []( const current_temperature & msg ) {
    return !is_normal_temperature( msg );
  } );
 ...
}

Since

v.5.7.4

Parameters

mbox	Message box from which message is expected. This must be MPMC-mbox.
lambda	Delivery filter as lambda-function or functional object.

Definition at line 3433 of file agent.hpp.

so_subscribe()

subscription_bind_t so_5::agent_t::so_subscribe ( const mbox_t & mbox_ref )

inline

Initiate subscription.

This method starts a subscription procedure by returning an instance of subscription_bind_t. The subscription details and the completion of a subscription is controlled by this subscription_bind_t object.

Usage sample:

void a_sample_t::so_define_agent()
{
  // Subscription for state `state_one`
  so_subscribe( mbox_target )
    .in( state_one )
    .event( &a_sample_t::evt_sample_handler );
 
  // Subscription for the default state.
  so_subscribe( another_mbox )
    .event( &a_sample_t::evt_another_handler );
 
  // Subscription for several event handlers in the default state.
  so_subscribe( yet_another_mbox )
    .event( &a_sample_t::evt_yet_another_handler )
    // Lambda-function can be used as event handler too.
    .event( [this](mhood_t<some_message> cmd) {...} );
 
  // Subscription for several event handlers.
  // All of them will be subscribed for states first_state and second_state.
  so_subscribe( some_mbox )
    .in( first_state )
    .in( second_state )
    .event( &a_sample_t::evt_some_handler_1 )
    .event( &a_sample_t::evt_some_handler_2 )
    .event( &a_sample_t::evt_some_handler_3 );
}

Parameters

mbox_ref

Mbox for messages to subscribe.

Examples

so_5/adv_thread_pool_fifo/main.cpp, so_5/agent_name/main.cpp, so_5/custom_work_thread_factory/main.cpp, so_5/hello_periodic/main.cpp, so_5/individual_msg_tracing/main.cpp, so_5/introduce_named_mbox/main.cpp, so_5/machine_control/main.cpp, so_5/make_new_direct_mbox/main.cpp, so_5/news_board/main.cpp, so_5/ping_pong/main.cpp, so_5/ping_pong_minimal/main.cpp, so_5/prio_work_stealing/main.cpp, so_5/producer_consumer_mchain/main.cpp, so_5/selective_msg_tracing/main.cpp, and so_5/unique_subscribers_mbox/main.cpp.

Definition at line 1359 of file agent.hpp.

so_subscribe_deadletter_handler()

template<typename Event_Handler >

void so_5::agent_t::so_subscribe_deadletter_handler ( const so_5::mbox_t & mbox, Event_Handler && handler, thread_safety_t thread_safety = thread_safety_t::unsafe )

inline

Create a subscription for deadletter handler for a specific message from a specific mbox.

Type of a message for deadletter handler will be detected automatically from the signature of the handler.

A deadletter handler can be a pointer to method of agent or lambda-function. The handler should have one of the following format:

void deadletter_handler(message_type);
void deadletter_handler(const message_type &);
void deadletter_handler(mhood_t<message_type>);

Usage example:

class demo : public so_5::agent_t {
  void on_some_message(mhood_t<some_message> cmd) {...}
  ...
  virtual void so_define_agent() override {
    // Create deadletter handler via pointer to method.
    // Event handler will be not-thread-safe.
    so_subscribe_deadletter_handler(
      so_direct_mbox(),
      &demo::on_some_message );
 
    // Create deadletter handler via lambda-function.
    so_subscribe_deadletter_handler(
      status_mbox(), // Any mbox can be used, not only agent's direct mbox.
      [](mhood_t<status_request> cmd) {
        so_5::send<current_status>(cmd->reply_mbox, "workind");
      },
      // This handler will be thread-safe one.
      so_5::thread_safe );
  }
};

Exceptions

so_5::exception_t

in the case when the subscription of a deadletter handler for type msg_type from mbox is already exists.

Since

v.5.5.21

Examples

so_5/deadletter_handler/main.cpp.

Definition at line 2080 of file agent.hpp.

so_subscribe_self()

subscription_bind_t so_5::agent_t::so_subscribe_self ( )

inline

Initiate subscription to agent's direct mbox.

Note that is just a short form of:

void a_sample_t::so_define_agent()
{
 so_subscribe( so_direct_mbox() )
   .in( some_state )
   .in( another_state )
   .event( some_event_handler )
   .event( some_another_handler );
}

Instead of writting so_subscribe(so_direct_mbox()) it is possible to write just so_subscribe_self().

Usage sample:

void a_sample_t::so_define_agent()
{
  // Subscription for state `state_one`
  so_subscribe_self()
    .in( state_one )
    .event( &a_sample_t::evt_sample_handler );
 
  // Subscription for the default state.
  so_subscribe_self()
    .event( &a_sample_t::evt_another_handler );
 
  // Subscription for several event handlers in the default state.
  so_subscribe_self()
    .event( &a_sample_t::evt_yet_another_handler )
    // Lambda-function can be used as event handler too.
    .event( [this](mhood_t<some_message> cmd) {...} );
 
  // Subscription for several event handlers.
  // All of them will be subscribed for states first_state and second_state.
  so_subscribe_self()
    .in( first_state )
    .in( second_state )
    .event( &a_sample_t::evt_some_handler_1 )
    .event( &a_sample_t::evt_some_handler_2 )
    .event( &a_sample_t::evt_some_handler_3 );
}

Since

v.5.5.1

Examples

so_5/agent_name/main.cpp, so_5/custom_direct_mbox/main.cpp, so_5/custom_error_logger/main.cpp, so_5/custom_work_thread_factory/main.cpp, so_5/deadletter_handler/main.cpp, so_5/hardwork_imit/main.cpp, so_5/hello_evt_handler/main.cpp, so_5/hello_evt_lambda/main.cpp, so_5/individual_msg_tracing/main.cpp, so_5/introduce_named_mbox/main.cpp, so_5/machine_control/main.cpp, so_5/make_agent_ref/main.cpp, so_5/make_new_direct_mbox/main.cpp, so_5/many_timers/main.cpp, so_5/modify_resend_as_immutable/main.cpp, so_5/mutable_msg_agents/main.cpp, so_5/named_dispatchers_layer/main.cpp, so_5/news_board/main.cpp, so_5/parent_coop/main.cpp, so_5/prio_work_stealing/main.cpp, so_5/producer_consumer_mchain/main.cpp, so_5/selective_msg_tracing/main.cpp, so_5/single_sink_binding/main.cpp, so_5/stop_guard/main.cpp, so_5/two_handlers/main.cpp, and so_5/unique_subscribers_mbox/main.cpp.

Definition at line 1416 of file agent.hpp.

so_switch_to_awaiting_deregistration_state()

void so_5::agent_t::so_switch_to_awaiting_deregistration_state

(

)

Switching agent to special state in case of unhandled exception.

Note

Since v.5.7.3 it's implemented via so_deactivate_agent().

Attention

The method is not noexcept, it can throw an exception. So additional care has to be taken when it's called in catch-block and/or in noexcept contexts.

Since

5.2.3

Definition at line 756 of file agent.cpp.

so_this_agent_disp_binder()

disp_binder_shptr_t so_5::agent_t::so_this_agent_disp_binder ( ) const

inlinenodiscard

Returns the dispatcher binder that is used for binding this agent.

Attention

It's safe to use this method only while the agent is registered in a SObjectizer Environment – from the start of so_evt_start() until the completion so_evt_finish(). The calling of this method when agent it not registered (e.g. before the invocation of so_evt_start() or after the completion of so_evt_finish()) may lead to undefined behavior.

This method is intended to simplify creation of children cooperations:

void parent_agent::evt_some_command(mhood_t<msg_command> cmd) {
  ...
  // A new child coop has to be created and bound to the same
  // dispatcher as the parent agent.
  so_5::introduce_child_coop( *this,
    // Get the binder of the parent.
    so_this_agent_disp_binder(),
    [&](so_5::coop_t & coop) {
      ... // Creation of children agents.
    } );
}

Since

v.5.8.1

Examples

so_5/dispatcher_for_children_2/main.cpp.

Definition at line 2671 of file agent.hpp.

so_this_coop_disp_binder()

disp_binder_shptr_t so_5::agent_t::so_this_coop_disp_binder ( ) const

nodiscard

Returns the dispatcher binder that is used as the default binder for the agent's coop.

Attention

It's safe to use this method only while the agent is registered in a SObjectizer Environment – from the start of so_evt_start() until the completion so_evt_finish(). The calling of this method when agent it not registered (e.g. before the invocation of so_evt_start() or after the completion of so_evt_finish()) may lead to undefined behavior.

This method is intended to simplify creation of children cooperations:

void parent_agent::evt_some_command(mhood_t<msg_command> cmd) {
  ...
  // A new child coop has to be created and bound to the same
  // dispatcher as the parent agent.
  so_5::introduce_child_coop( *this,
    // Get the binder of the parent's coop.
    so_this_coop_disp_binder(),
    [&](so_5::coop_t & coop) {
      ... // Creation of children agents.
    } );
}

Note

This method may return a different binder that so_this_agent_disp_binder() in a case when the agent was bound by a separate dispatcher. For example:

// The parent coop will use thread_pool dispatcher as
// the default dispatcher.
env.introduce_coop(
  so_5::disp::thread_pool::make_dispatcher( env, 8u )
    .binder( []( auto & params ) {
        // Every agent will have a separate event queue.
        params.fifo( so_5::disp::thread_pool::fifo_t::individual );
      } ),
  [&]( so_5::coop_t & coop ) {
    // The parent agent itself will use a separate dispatcher.
    coop.make_agent_with_binder< parent_agent >(
      so_5::disp::one_thread::make_dispatcher( env ).binder(),
      ... );
 
    ... // Creation of other agents.
  } );

In that case use of so_this_agent_disp_binder() instead of so_this_coop_disp_binder() will bind children agents to the parent's one_thread dispatcher instead of coop's thread_pool dispatcher.

Since

v.5.8.1

Examples

so_5/dispatcher_for_children_2/main.cpp.

Definition at line 988 of file agent.cpp.

so_was_defined()

bool so_5::agent_t::so_was_defined ( ) const

protected

Is method define_agent already called?

Usage sample:

class a_sample_t : public so_5::agent_t
{
  // ...
 
  public:
    void
    set_target_mbox( const so_5::mbox_t & mbox )
    {
      // mbox cannot be changed after agent registration.
      if( !so_was_defined() )
      {
        m_target_mbox = mbox;
      }
    }
 
  private:
    so_5::mbox_t m_target_mbox;
};

Definition at line 847 of file agent.cpp.

tuning_options()

static agent_tuning_options_t so_5::agent_t::tuning_options ( )

inlinestatic

Create tuning options object with default values.

Since

v.5.5.3

Definition at line 1103 of file agent.hpp.

Friends And Related Symbol Documentation

intrusive_ptr_t

template<typename T >

friend class intrusive_ptr_t

friend

Definition at line 684 of file agent.hpp.

so_5::enveloped_msg::impl::agent_demand_handler_invoker_t

friend class so_5::enveloped_msg::impl::agent_demand_handler_invoker_t

friend

Definition at line 681 of file agent.hpp.

so_5::impl::internal_agent_iface_t

friend class so_5::impl::internal_agent_iface_t

friend

Definition at line 679 of file agent.hpp.

so_5::impl::mpsc_mbox_t

friend class so_5::impl::mpsc_mbox_t

friend

Definition at line 677 of file agent.hpp.

so_5::impl::state_switch_guard_t

friend class so_5::impl::state_switch_guard_t

friend

Definition at line 678 of file agent.hpp.

state_t

friend class state_t

friend

Definition at line 675 of file agent.hpp.

subscription_bind_t

friend class subscription_bind_t

friend

Definition at line 674 of file agent.hpp.

Member Data Documentation

deep_history

const state_t::history_t so_5::agent_t::deep_history

staticconstexpr

Initial value:

=
        state_t::history_t::deep

Short alias for so_5::state_t::history_t::deep.

Since

v.5.5.15

Definition at line 737 of file agent.hpp.

m_agent_coop

coop_t* so_5::agent_t::m_agent_coop

private

Agent is belong to this cooperation.

Definition at line 2902 of file agent.hpp.

m_current_state_ptr

const state_t* so_5::agent_t::m_current_state_ptr

private

Current agent state.

Definition at line 2777 of file agent.hpp.

m_current_status

agent_status_t so_5::agent_t::m_current_status

private

Current agent status.

Since

v.5.5.18

Definition at line 2800 of file agent.hpp.

m_delivery_filters

std::unique_ptr< impl::delivery_filter_storage_t > so_5::agent_t::m_delivery_filters

private

Delivery filters for that agents.

Note

Storage is created only when necessary.

Since

v.5.5.5

Definition at line 2911 of file agent.hpp.

m_direct_mbox

const mbox_t so_5::agent_t::m_direct_mbox

private

A direct mbox for the agent.

Since

v.5.4.0

Definition at line 2889 of file agent.hpp.

m_disp_binder

disp_binder_shptr_t so_5::agent_t::m_disp_binder

private

Binder for this agent.

Since v.5.7.5 disp_binder for the agent is stored inside the agent. It guarantees that disp_binder will be deleted after destruction of the agent (if there is no circular references between the agent and the disp_binder).

This value will be set by coop_t when agent is being add to the coop.

Note

Access to that field provided by so_5::impl::internal_agent_iface_t.

Since

v.5.7.5

Definition at line 2936 of file agent.hpp.

m_env

environment_t& so_5::agent_t::m_env

private

SObjectizer Environment for which the agent is belong.

Definition at line 2846 of file agent.hpp.

m_event_queue

event_queue_t* so_5::agent_t::m_event_queue

private

A pointer to event_queue.

After binding to the dispatcher is it pointed to the actual event queue.

After shutdown it is set to nullptr.

Attention

Access to m_event_queue value must be done only under acquired m_event_queue_lock.

Since

v.5.5.8

Definition at line 2882 of file agent.hpp.

m_event_queue_lock

default_rw_spinlock_t so_5::agent_t::m_event_queue_lock

private

Event queue operation protector.

Initially m_event_queue is NULL. It is changed to actual value in so_bind_to_dispatcher() method. And reset to nullptr again in shutdown_agent().

nullptr in m_event_queue means that methods push_event() will throw away any new demand.

It is necessary to provide guarantee that m_event_queue will be reset to nullptr in shutdown_agent() only if there is no working push_event() methods. To do that default_rw_spinlock_t is used. Method push_event() acquire it in read-mode and shutdown_agent() acquires it in write-mode. It means that shutdown_agent() cannot get access to m_event_queue until there is working push_event().

Since

v.5.5.8

Definition at line 2867 of file agent.hpp.

m_handler_finder

handler_finder_t so_5::agent_t::m_handler_finder

private

Function for searching event handler.

Note

The value is set only once in the constructor and doesn't changed anymore.

Since

v.5.5.9

Definition at line 2823 of file agent.hpp.

m_message_sinks

std::unique_ptr< impl::sinks_storage_t > so_5::agent_t::m_message_sinks

private

Holder of message sinks for that agent.

If message limits are defined for the agent it will be an actual storage with separate sinks for every (message_type, message_limit).

If message limits are not defined then it will be a special storage with just one message sink (that sink will be used for all subscriptions).

Since

v.5.8.0

Definition at line 2843 of file agent.hpp.

m_name

const name_for_agent_t so_5::agent_t::m_name

private

Optional name for the agent.

This value can be set in the constructor only and can't be changed later.

Empty value means that the name for the agent wasn't specified.

Since

v.5.8.2

Examples

so_5/custom_direct_mbox/main.cpp, so_5/custom_work_thread_factory/main.cpp, so_5/disp/main.cpp, so_5/make_agent_ref/main.cpp, so_5/mutable_msg_agents/main.cpp, so_5/news_board/main.cpp, so_5/producer_consumer_mchain/main.cpp, and so_5/redirect_and_transform/main.cpp.

Definition at line 2948 of file agent.hpp.

m_priority

const priority_t so_5::agent_t::m_priority

private

Priority of the agent.

Since

v.5.5.8

Definition at line 2918 of file agent.hpp.

m_state_listener_controller

impl::state_listener_controller_t so_5::agent_t::m_state_listener_controller

private

State listeners controller.

Definition at line 2803 of file agent.hpp.

m_subscriptions

impl::subscription_storage_unique_ptr_t so_5::agent_t::m_subscriptions

private

All agent's subscriptions.

Since

v.5.4.0

Definition at line 2830 of file agent.hpp.

m_working_thread_id

so_5::current_thread_id_t so_5::agent_t::m_working_thread_id

private

Working thread id.

Some actions like managing subscriptions and changing states are enabled only on working thread id.

Since

v.5.4.0

Definition at line 2899 of file agent.hpp.

shallow_history

const state_t::history_t so_5::agent_t::shallow_history

staticconstexpr

Initial value:

=
        state_t::history_t::shallow

Short alias for so_5::state_t::history_t::shallow.

Since

v.5.5.15

Definition at line 730 of file agent.hpp.

st_default

const state_t so_5::agent_t::st_default { self_ptr(), "<DEFAULT>" }

private

Definition at line 2774 of file agent.hpp.

---

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

• agent.hpp
• agent.cpp