so_5 Namespace Reference

Private part of message limit implementation. More...

Namespaces
namespace	anonymous_namespace{agent.cpp}
namespace	anonymous_namespace{environment.cpp}
namespace	anonymous_namespace{event_exception_logger.cpp}
namespace	anonymous_namespace{queue_locks_defaults_manager.cpp}
namespace	anonymous_namespace{wrapped_env.cpp}
namespace	api
	Public API functions of SObjectizer-5.
namespace	as_msink_impl
namespace	bind_then_redirect_impl
namespace	custom_mbox_details
namespace	dereg_reason
	Enumeration of cooperation deregistration reasons.
namespace	details
	Some reusable and low-level classes/functions which can be used in public header files.
namespace	disp
	Event dispatchers.
namespace	env_infrastructures
	Various implementations of environment_infrastructure.
namespace	enveloped_msg
namespace	experimental
namespace	impl
	Details of SObjectizer run-time implementations.
namespace	internal_timer_helpers
namespace	log_msg_details
	Implementation details of error_logging facility.
namespace	low_level_api
namespace	mchain_auto_close_details
namespace	mchain_props
	Various properties and parameters of message chains.
namespace	message_limit
	All stuff related to message limits.
namespace	msg_tracing
	Public part of message delivery tracing mechanism.
namespace	msinks
namespace	multi_sink_binding_impl
namespace	prio
	Helpers for working with priorities.
namespace	rt
	All code related to implementation of SObjectizer run-time.
namespace	send_functions_details
	Implementation details for send-family and request_future/value helper functions.
namespace	sink_bindings_details
namespace	stats
	All stuff related to run-time monitoring and statistics.
namespace	thread_auto_join_details
namespace	timer_thread
	Old timer thread related stuff.
namespace	timers_details
	Timers implementation details.
namespace	unique_subscribers_mbox_impl
namespace	wrapped_env_details

Classes
class	abstract_message_box_t
	Mail box class. More...
class	abstract_message_chain_t
	An interface of message chain. More...
class	abstract_message_sink_t
	Interface for message sink. More...
class	abstract_sink_owner_t
	Interface for holders of message_sink instances. More...
class	agent_context_t
	A context for agent construction and tuning. More...
class	agent_identity_t
	Helper class for holding agent's identity (name or pointer). More...
class	agent_state_listener_t
	Interface of the agent state listener. More...
class	agent_t
	A base class for agents. More...
class	agent_tuning_options_t
	A collector for agent tuning options. More...
class	atomic_refcounted_t
	The base class for the object with a reference counting. More...
class	coop_dereg_notificators_container_t
	Container for cooperation deregistration notificators. More...
class	coop_dereg_reason_t
	It's a kind of strong typedef for coop's deregistration reason. More...
class	coop_handle_t
	Type of smart handle for a cooperation. More...
class	coop_listener_t
	Interface for the cooperation listener. More...
class	coop_reg_notificators_container_t
	Container for cooperation registration notificators. More...
class	coop_t
	Agent cooperation. More...
class	coop_unique_holder_t
	A special type that plays role of unique_ptr for coop. More...
class	delivery_filter_t
	An interface of delivery filter object. More...
class	disp_binder_t
	Interface for dispatcher binders. More...
class	environment_infrastructure_t
	An interface for environment_infrastructure entity. More...
class	environment_params_t
	Parameters for the SObjectizer Environment initialization. More...
class	environment_t
	SObjectizer Environment. More...
class	error_logger_t
	An interface for logging error messages. More...
class	event_exception_logger_t
	An interface for the exception logging. More...
class	event_queue_hook_t
	Interface of event_queue_hook object. More...
class	event_queue_t
	An interface of event queue for agent. More...
class	exception_t
	The base class for all SObjectizer exceptions. More...
struct	exceptions_enabled_t
	Type that indicates that exceptions are enabled. More...
struct	execution_demand_t
	A description of event execution demand. More...
class	execution_hint_t
	A hint for a dispatcher for execution of event for the concrete execution_demand. More...
class	extensible_select_t
	Special container for holding select parameters and select cases. More...
struct	immutable_msg
	A special marker for immutable message. More...
struct	initial_substate_of
	Helper for marking initial substate of composite state. More...
class	intrusive_ptr_t
	Template class for smart reference wrapper on the atomic_refcounted_t. More...
struct	is_classical_message
	A helper class for checking that message is a classical message derived from message_t class. More...
struct	is_mutable_message
	A helper class for checking that message is a mutable message. More...
struct	is_mutable_message< mutable_msg< T > >
struct	is_signal
	A helper class for checking that message is a signal. More...
struct	is_user_type_message
	A helper for detection presence of message of user type. More...
struct	is_user_type_message< user_type_message_t< M > >
class	layer_t
	An interface of the additional SObjectizer Environment layer. More...
struct	mbox_creation_data_t
	An information which is necessary for creation of a new mbox. More...
class	mbox_namespace_name_t
	A class for the name of mbox_namespace. More...
class	mchain_bulk_processing_params_t
	Basic parameters for advanced receive from mchain and for multi chain select. More...
class	mchain_master_handle_t
	Helper class for automatic close of a mchain at the destruction of master handle instance. More...
class	mchain_params_t
	Parameters for message chain. More...
class	mchain_receive_params_t
	Parameters for advanced receive from mchain. More...
class	mchain_receive_result_t
	A result of receive from mchain. More...
class	mchain_select_params_t
	Parameters for advanced select from multiple mchains. More...
class	mchain_select_result_t
	A result of select from several mchains. More...
class	mchain_send_result_t
	A result of attempt of sending messages to a message chain. More...
class	message_holder_t
	A class for holding an instance of a message. More...
struct	message_payload_type
	A helper class for detection of payload type of message. More...
struct	message_payload_type< user_type_message_t< T > >
struct	message_payload_type_impl
	Implementation details for message_payload_type. More...
struct	message_payload_type_impl< T, false >
	Implementation details for message_payload_type. More...
class	message_t
	A base class for agent messages. More...
class	mhood_t
	A message wrapped to be used as type of argument for event handlers. More...
struct	msg_coop_deregistered
	Message about cooperation deregistration completion. More...
struct	msg_coop_registered
	Message about cooperation registration completion. More...
class	multi_sink_binding_t
	Helper class for managing multiple sink bindings. More...
struct	mutable_msg
	A special marker for mutable message. More...
struct	name_for_agent_methods_mixin_t
	Helper type with method to be mixed into agent class. More...
class	name_for_agent_t
	Type for holding agent name. More...
class	nonempty_name_t
	A class for the name which cannot be empty. More...
class	null_mutex_t
	A class which is like std::mutex but does not do any real actions. More...
class	outliving_reference_t
	Helper class for indication of long-lived reference via its type. More...
class	partially_constructed_agent_ptr_t
	Wrapper around a pointer to partially constructed agent. More...
class	pause_backoff_t
	An implementation of backoff object using assembly instruction. More...
class	prepared_receive_t
	Special container for holding receive parameters and receive cases. More...
class	prepared_select_t
	Special container for holding select parameters and select cases. More...
class	queue_locks_defaults_manager_t
	A base class for manager of default locks for event queues. More...
class	read_lock_guard_t
	Scoped guard for shared locks. More...
class	rw_spinlock_t
	A simple multi-readers/single-writer spinlock (analog of std::shared_mutex). More...
class	signal_t
	A base class for agent signals. More...
class	simple_sink_owner_t
	Implementation of abstract_sink_owner that owns an instance of message sink. More...
class	single_sink_binding_t
	Helper class for managing single sink bindings. More...
class	spinlock_t
	A simple spinlock (analog of std::mutex). More...
class	state_t
	Class for the representing agent state. More...
class	stderr_logger_t
	A standard implementation of error_logger interface. More...
class	stop_guard_t
	An interface of stop_guard entity. More...
class	subscription_bind_t
	A class for creating a subscription to messages from the mbox. More...
struct	substate_of
	Helper for marking a substate of composite state. More...
struct	terminate_if_throws_t
	Type that indicates that an exception leads to the termination of the whole application. More...
class	timer_id_t
	An indentificator for the timer. More...
class	timer_manager_t
	Timer manager interface. More...
class	timer_t
	A base class for timer identificator. More...
struct	timer_thread_stats_t
	Statistics for run-time monitoring. More...
class	timer_thread_t
	Timer thread interface. More...
class	transformed_message_t
	A result of message transformation. More...
struct	user_type_message_t
	Template class for representing object of user type as a message. More...
class	wrapped_env_t
	A wrapped environment. More...
class	yield_backoff_t
	An implementation of backoff object with usage of std::yield. More...

Typedefs
using	delivery_filter_unique_ptr_t
	An alias of unique_ptr for delivery_filter.
using	default_spinlock_t = spinlock_t< pause_backoff_t >
using	default_rw_spinlock_t = rw_spinlock_t< pause_backoff_t >
using	coop_reg_notificator_t
	Type of cooperation registration notificator.
using	coop_reg_notificators_container_ref_t
	Typedef for smart pointer to notificators_container.
using	coop_dereg_notificator_t
	Type of cooperation deregistration notificator.
using	coop_dereg_notificators_container_ref_t
	Typedef for smart pointer to notificators_container.
using	coop_listener_unique_ptr_t = std::unique_ptr< coop_listener_t >
	Typedef for the coop_listener autopointer.
using	disp_binder_shptr_t = std::shared_ptr< disp_binder_t >
	Typedef for the disp_binder smart pointer.
using	environment_infrastructure_deleter_fnptr_t
	A type for deleter for environment_infrastructure objects.
using	environment_infrastructure_unique_ptr_t
	A type of unique pointer for environment_infrastructure entity.
using	environment_infrastructure_factory_t
	Type of factory for environment infrastructure.
using	error_logger_shptr_t = std::shared_ptr< error_logger_t >
	An alias for shared_ptr to error_logger.
using	event_exception_logger_unique_ptr_t
	Typedef for the event_exception_logger autopointer.
using	event_queue_hook_deleter_fnptr_t = void (*)(event_queue_hook_t *)
	A type for deleter of event_queue_hook object.
using	event_queue_hook_unique_ptr_t
	Alias for unique pointer to event_queue_hook.
using	mbox_t = intrusive_ptr_t< abstract_message_box_t >
	Smart reference for the abstract_message_box.
using	message_ref_t = intrusive_ptr_t< message_t >
	A smart reference to the message.
using	msink_t = intrusive_ptr_t< abstract_sink_owner_t >
	Smart reference for abstract_sink_owner.
template<typename M >
using	mutable_mhood_t = mhood_t< mutable_msg<M> >
	A short name for message hood for mutable message.
using	mchain_t = intrusive_ptr_t< abstract_message_chain_t >
	Short name for smart pointer to message chain.
using	queue_locks_defaults_manager_unique_ptr_t
	An alias of unique_ptr for queue_locks_defaults_manager.
using	layer_unique_ptr_t = std::unique_ptr< layer_t >
	Typedef for the layer's autopointer.
using	layer_ref_t = std::shared_ptr< layer_t >
	Typedef for the layer's smart pointer.
using	layer_map_t = std::map< std::type_index, layer_ref_t >
	Typedef for the map from a layer typeid to the layer.
using	stop_guard_shptr_t = std::shared_ptr< stop_guard_t >
	An alias of shared_ptr for stop_guard.
using	subscription_storage_factory_t
	Type of subscription_storage factory.
using	timer_thread_unique_ptr_t = std::unique_ptr< timer_thread_t >
	Auxiliary typedef for timer_thread autopointer.
using	timer_thread_factory_t
	Type of factory for creating timer_thread objects.
using	timer_manager_unique_ptr_t = std::unique_ptr< timer_manager_t >
	Auxiliary typedef for timer_manager autopointer.
using	timer_manager_factory_t
	Type of factory for creating timer_manager objects.
using	atomic_counter_t = std::atomic_ulong
	Atomic counter type.
using	atomic_flag_t = std::atomic_ulong
	Atomic flag type.
using	mbox_id_t = unsigned long long
	A type for mbox indentifier.
using	coop_id_t = std::uint_fast64_t
	ID of cooperation.
using	coop_shptr_t = std::shared_ptr< coop_t >
	Typedef for the agent_coop smart pointer.
using	current_thread_id_t = std::thread::id
	Type of the current thread id.
using	agent_ref_t = intrusive_ptr_t< agent_t >
	A smart reference to an agent.
using	agent_state_listener_unique_ptr_t
	Typedef for the agent_state_listener autopointer.
using	event_handler_method_t = std::function< void(message_ref_t &) >
	Type of event handler method.
using	demand_handler_pfn_t
	Demand handler prototype.
using	custom_direct_mbox_factory_t
	Type of functor to be used as a factory for custom direct mbox.
using	generic_simple_init_t = std::function< void(so_5::environment_t &) >
	Generic type for a simple SObjectizer-initialization function.
using	generic_simple_so_env_params_tuner_t
	Generic type for a simple SO Environment paramenters tuning function.

Enumerations
enum	exception_reaction_t {   abort_on_exception = 1 , shutdown_sobjectizer_on_exception = 2 , deregister_coop_on_exception = 3 , ignore_exception = 4 ,   inherit_exception_reaction = 5 }
	A reaction of SObjectizer to an exception from agent event. More...
enum class	delivery_possibility_t { must_be_delivered , no_subscription , disabled_by_delivery_filter , hidden_by_envelope }
	Result of checking delivery posibility. More...
enum class	mbox_type_t { multi_producer_multi_consumer , multi_producer_single_consumer }
	Type of the message box. More...
enum class	infinite_wait_indication { infinite_wait }
	A type for special marker for infitite waiting on service request or on receive from mchain. More...
enum class	no_wait_indication { no_wait }
	A type for special marker for no waiting on service request or on receive from mchain. More...
enum class	thread_safety_t : std::uint8_t { unsafe = 0 , safe = 1 }
	Thread safety indicator. More...
enum class	work_thread_activity_tracking_t { unspecified , off , on }
	Values for dispatcher's work thread activity tracking. More...
enum class	message_mutability_t { immutable_message , mutable_message }
	A enum with variants of message mutability or immutability. More...
enum class	message_kind_t { signal , classical_message , user_type_message , enveloped_msg }
	A enum with variants of message kinds. More...
enum class	event_handler_kind_t : char { final_handler , intermediate_handler }
	Kind of an event handler. More...
enum class	message_delivery_mode_t { ordinary , nonblocking }
	Possible modes of message/signal delivery. More...
enum class	priority_t : unsigned char {   p_min = 0 , p0 = p_min , p1 , p2 ,   p3 , p4 , p5 , p6 ,   p7 , p_max = p7 }
	Definition of supported priorities. More...
enum class	message_ownership_t { autodetected , unique , shared }
	Type of ownership of a message instance inside message_holder. More...
enum class	demands_handling_on_dereg_t { normal , skip }
	How pending demands should be handled on deregistration. More...

Functions
SO_5_FUNC void	swap (name_for_agent_t &a, name_for_agent_t &b)
template<typename Derived >
intrusive_ptr_t< Derived >	make_agent_ref (Derived *agent)
	Helper function template for the creation of smart pointer to an agent.
void	operator>>= (agent_t *agent, const state_t &new_state)
	A shortcat for switching the agent state.
msink_t SO_5_FUNC	wrap_to_msink (const mbox_t &mbox, priority_t sink_priority=prio::p0)
	Helper for wrapping an existing mbox into message_sink.
template<typename... Args>
coop_unique_holder_t	create_child_coop (agent_t &owner, Args &&... args)
	A simple way for creating child cooperation.
template<typename... Args>
coop_unique_holder_t	create_child_coop (coop_handle_t parent, Args &&... args)
	A simple way for creating child cooperation when there is a reference to the parent cooperation object.
template<typename... Args>
decltype(auto)	introduce_child_coop (agent_t &owner, Args &&... args)
	A simple way for creating and registering child cooperation.
template<typename... Args>
decltype(auto)	introduce_child_coop (coop_handle_t parent, Args &&... args)
	A simple way for creating and registering child cooperation when there is a reference to parent coop.
disp_binder_shptr_t	make_default_disp_binder (environment_t &env)
	Create an instance of the default dispatcher binder.
template<typename Message , typename Target , typename... Args>
void	send (Target &&to, Args &&... args)
	A utility function for creating and delivering a message or a signal.
template<typename Target , typename Message >
std::enable_if<!is_signal< Message >::value >::type	send (Target &&to, mhood_t< Message > what)
	A version of send function for redirection of a message from exising message hood.
template<typename Target , typename Message >
std::enable_if< is_signal< Message >::value >::type	send (Target &&to, mhood_t< Message >)
	A version of send function for redirection of a signal from exising message hood.
template<typename Target , typename Message , message_ownership_t Ownership>
void	send (Target &&to, message_holder_t< Message, Ownership > what)
	A version of send function for redirection of a message from exising message_holder instance.
template<typename Message , typename Target , typename... Args>
void	send_delayed (Target &&target, std::chrono::steady_clock::duration pause, Args &&... args)
	A utility function for creating and delivering a delayed message to the specified destination.
template<typename Target , typename Message >
std::enable_if<!message_payload_type< Message >::is_signal >::type	send_delayed (Target &&to, std::chrono::steady_clock::duration pause, mhood_t< Message > msg)
	A utility function for delayed redirection of a message from existing message hood.
template<typename Target , typename Message >
std::enable_if< message_payload_type< Message >::is_signal >::type	send_delayed (Target &&to, std::chrono::steady_clock::duration pause, mhood_t< Message >)
	A utility function for delayed redirection of a signal from existing message hood.
template<typename Target , typename Message , message_ownership_t Ownership>
void	send_delayed (Target &&to, std::chrono::steady_clock::duration pause, message_holder_t< Message, Ownership > msg)
	A version of send_delayed function for redirection of a message from exising message_holder instance.
template<typename Message , typename Target , typename... Args>
timer_id_t	send_periodic (Target &&target, std::chrono::steady_clock::duration pause, std::chrono::steady_clock::duration period, Args &&... args)
	A utility function for creating and delivering a periodic message to the specified destination.
template<typename Target , typename Message >
std::enable_if<!is_signal< Message >::value, timer_id_t >::type	send_periodic (Target &&target, std::chrono::steady_clock::duration pause, std::chrono::steady_clock::duration period, mhood_t< Message > mhood)
	A utility function for delivering a periodic from an existing message hood.
template<typename Target , typename Message >
std::enable_if< is_signal< Message >::value, timer_id_t >::type	send_periodic (Target &&target, std::chrono::steady_clock::duration pause, std::chrono::steady_clock::duration period, mhood_t< Message >)
	A utility function for periodic redirection of a signal from existing message hood.
template<typename Target , typename Message , message_ownership_t Ownership>
timer_id_t	send_periodic (Target &&target, std::chrono::steady_clock::duration pause, std::chrono::steady_clock::duration period, message_holder_t< Message, Ownership > what)
	A version of send_periodic function for redirection of a message from exising message_holder instance.
SO_5_FUNC error_logger_shptr_t	create_stderr_logger ()
	A factory for creating error_logger implemenation which uses std::stderr as log stream.
SO_5_FUNC event_exception_logger_unique_ptr_t	create_std_event_exception_logger ()
	Create the default exception logger.
template<typename Hook_Type , typename... Args>
event_queue_hook_unique_ptr_t	make_event_queue_hook (event_queue_hook_deleter_fnptr_t deleter, Args &&...args)
	Helper function for simplify creation of event_queue_hook object.
event_queue_hook_unique_ptr_t	make_empty_event_queue_hook_unique_ptr ()
	Helper function for creation of empty unique_ptr for event_queue_hook.
template<class Msg >
void	ensure_not_signal ()
	A special compile-time checker to guarantee that the message class is not a signal class.
template<class Msg >
void	ensure_message_with_actual_data (const Msg *m)
	A special checker to guarantee that the message is an instance of the message_t (not signal_t) and has a not-null pointer to the message data.
template<class S >
void	ensure_not_mutable_signal ()
	A special compile-time checker to guarantee that S is not a mutable signal.
template<class Msg >
void	ensure_signal ()
	A special compile-time checker to guarantee that the Msg is derived from the signal_t.
template<typename Msg >
void	ensure_classical_message ()
	A special compile-time checker to guarantee that Msg is derived from message_t.
template<typename M >
std::enable_if<!is_signal< M >::value, mhood_t< immutable_msg< M > > >::type	to_immutable (mhood_t< mutable_msg< M > > msg)
	Transform mutable message instance into immutable.
template<typename M >
std::enable_if< is_signal< M >::value, mhood_t< immutable_msg< M > > >::type	to_immutable (mhood_t< mutable_msg< M > >)
template<typename Exceptions_Control >
void	close_drop_content (Exceptions_Control exceptions_control, const mchain_t &ch) noexcept(noexcept(details::should_terminate_if_throws_t< Exceptions_Control >::value))
	Helper function for closing a message chain with dropping all its content.
template<typename Exceptions_Control >
void	close_retain_content (Exceptions_Control exceptions_control, const mchain_t &ch) noexcept(noexcept(details::should_terminate_if_throws_t< Exceptions_Control >::value))
	Helper function for closing a message chain with retaining all its content.
template<std::size_t Index>
auto	get (const mchain_receive_result_t &result)
	part of tuple protocol for mchain_receive_result_t.
mchain_receive_params_t< mchain_props::msg_count_status_t::undefined >	from (mchain_t chain)
	A helper function for simplification of creation of mchain_receive_params instance.
template<mchain_props::msg_count_status_t Msg_Count_Status, typename... Handlers>
mchain_receive_result_t	receive (const mchain_receive_params_t< Msg_Count_Status > &params, Handlers &&... handlers)
	Advanced version of receive from mchain.
template<mchain_props::msg_count_status_t Msg_Count_Status, typename... Handlers>
prepared_receive_t< sizeof...(Handlers) >	prepare_receive (const mchain_receive_params_t< Msg_Count_Status > &params, Handlers &&... handlers)
	Create parameters for receive function to be used later.
template<std::size_t Handlers_Count>
mchain_receive_result_t	receive (const prepared_receive_t< Handlers_Count > &prepared)
	A receive operation to be done on previously prepared receive params.
SO_5_FUNC queue_locks_defaults_manager_unique_ptr_t	make_defaults_manager_for_simple_locks ()
	A factory for queue_locks_defaults_manager with generators for simple locks.
SO_5_FUNC queue_locks_defaults_manager_unique_ptr_t	make_defaults_manager_for_combined_locks ()
	A factory for queue_locks_defaults_manager with generators for combined locks.
SO_5_FUNC subscription_storage_factory_t	default_subscription_storage_factory ()
	Factory for default subscription storage object.
SO_5_FUNC subscription_storage_factory_t	hash_table_based_subscription_storage_factory ()
	Factory for default subscription storage based on std::unordered_map.
SO_5_FUNC subscription_storage_factory_t	vector_based_subscription_storage_factory (std::size_t initial_capacity)
	Factory for subscription storage based on unsorted std::vector.
SO_5_FUNC subscription_storage_factory_t	map_based_subscription_storage_factory ()
	Factory for subscription storage based on std::map.
SO_5_FUNC subscription_storage_factory_t	adaptive_subscription_storage_factory (std::size_t threshold)
	Factory for adaptive subscription storage.
SO_5_FUNC subscription_storage_factory_t	adaptive_subscription_storage_factory (std::size_t threshold, const subscription_storage_factory_t &small_storage_factory, const subscription_storage_factory_t &large_storage_factory)
	Factory for adaptive subscription storage.
SO_5_FUNC subscription_storage_factory_t	flat_set_based_subscription_storage_factory (std::size_t initial_capacity)
	Factory for subscription storage based on sorted std::vector.
mbox_id_t	null_mbox_id ()
	Default value for null mbox_id.
current_thread_id_t	query_current_thread_id ()
	Get the ID of the current thread.
current_thread_id_t	null_current_thread_id ()
	Get NULL thread id.
std::thread::id	raw_id_from_current_thread_id (const current_thread_id_t &w)
	Get the raw thread id from current_thread_id.
template<typename T >
	intrusive_ptr_t (std::unique_ptr< T >) -> intrusive_ptr_t< T >
template<typename T >
outliving_reference_t< T >	outliving_mutable (T &r)
	Make outliving_reference wrapper for mutable reference.
template<typename T >
outliving_reference_t< const T >	outliving_const (T const &r)
	Make outliving_reference wrapper for const reference.
template<typename T >
outliving_reference_t< const T >	outliving_const (outliving_reference_t< T > r)
	Make outliving_reference wrapper for const reference.
template<typename Option >
agent_context_t	operator+ (environment_t &env, Option arg)
	A plus operator for creating agent_context object from a reference to Environment and single agent tuning option.
std::size_t	to_size_t (priority_t priority)
	Helper function for conversion from priority to size_t.
priority_t	to_priority_t (std::size_t v)
	Helper function for conversion from size_t to priority.
template<typename Method_Pointer >
std::enable_if< details::is_agent_method_pointer< details::method_arity::unary, Method_Pointer >::value, details::msg_type_and_handler_pair_t >::type	preprocess_agent_event_handler (const mbox_t &mbox, agent_t &agent, Method_Pointer pfn)
	Do preprocessing and some verification of event handler and return msg_type_and_handler_pair for it.
template<typename Lambda >
std::enable_if< details::lambda_traits::is_lambda< Lambda >::value, details::msg_type_and_handler_pair_t >::type	preprocess_agent_event_handler (const mbox_t &mbox, agent_t &, Lambda &&lambda)
	Do preprocessing and some verification of event handler and return msg_type_and_handler_pair for it.
template<typename Msg , typename... Args>
transformed_message_t< Msg >	make_transformed (mbox_t mbox, Args &&... args)
	Helper function for creation of an instance of transformed_message_t.
template<typename Msg , message_ownership_t Ownership>
transformed_message_t< Msg >	make_transformed (mbox_t mbox, message_holder_t< Msg, Ownership > msg_holder)
	Helper function for creation of an instance of transformed_message_t.
SO_5_FUNC void	swap (environment_params_t &a, environment_params_t &b)
auto	make_coop_reg_notificator (mbox_t target) noexcept
	Create notificator about cooperation registration completion.
auto	make_coop_dereg_notificator (mbox_t target) noexcept
	Create notificator about cooperation deregistration completion.
template<typename Init_Routine >
void	launch (Init_Routine &&init_routine)
	Launch a SObjectizer Environment with default parameters.
template<typename Init_Routine , typename Params_Tuner >
void	launch (Init_Routine &&init_routine, Params_Tuner &&params_tuner)
	Launch a SObjectizer Environment with explicitely specified parameters.
template<typename Binding , typename Transformer >
void	bind_transformer (Binding &binding, const so_5::mbox_t &src_mbox, Transformer &&transformer)
	Helper function to add transform_then_redirect msink to a binding object.
template<typename Binding , typename Transformer , typename Delivery_Filter >
void	bind_transformer (Binding &binding, const so_5::mbox_t &src_mbox, Transformer &&transformer, Delivery_Filter &&filter)
	Helper function to add transform_then_redirect msink to a binding object (with a delivery filter).
template<typename Expected_Msg , typename Binding , typename Transformer >
void	bind_transformer (Binding &binding, const so_5::mbox_t &src_mbox, Transformer &&transformer)
	Helper function to add transform_then_redirect msink to a binding object.
template<typename Expected_Msg , typename Binding , typename Transformer , typename Delivery_Filter >
void	bind_transformer (Binding &binding, const so_5::mbox_t &src_mbox, Transformer &&transformer, Delivery_Filter &&delivery_filter)
	Helper function to add transform_then_redirect msink to a binding object (with a delivery filter).
mchain_t	create_mchain (environment_t &env, mchain_props::duration_t waiting_time, std::size_t max_size, mchain_props::memory_usage_t memory_usage, mchain_props::overflow_reaction_t overflow_reaction)
	Create size-limited chain with waiting on overflow.
mchain_t	create_mchain (wrapped_env_t &sobj, mchain_props::duration_t waiting_time, std::size_t max_size, mchain_props::memory_usage_t memory_usage, mchain_props::overflow_reaction_t overflow_reaction)
	Create size-limited chain without waiting on overflow.
template<typename... Tail>
mchain_auto_close_details::auto_closer_t< sizeof...(Tail) >	auto_close_mchains (mchain_props::close_mode_t close_mode, Tail &&... tail)
	Helper function for creation of automatic closer of mchains.
template<typename... Tail>
mchain_auto_close_details::auto_closer_t< sizeof...(Tail) >	auto_close_retain_content (Tail &&... tail)
	Helper function for automatic closing of mchains with retaining their content.
template<typename... Tail>
mchain_auto_close_details::auto_closer_t< sizeof...(Tail) >	auto_close_drop_content (Tail &&... tail)
	Helper function for automatic closing of mchains with dropping their content.
mchain_select_params_t< mchain_props::msg_count_status_t::undefined >	from_all ()
	Helper function for creation of mchain_select_params instance with default values.
template<typename... Handlers>
mchain_props::select_case_unique_ptr_t	receive_case (mchain_t chain, Handlers &&... handlers)
	A helper for creation of select_case object for one multi chain select.
template<typename Msg , message_ownership_t Ownership, typename On_Success_Handler >
mchain_props::select_case_unique_ptr_t	send_case (mchain_t chain, message_holder_t< Msg, Ownership > msg, On_Success_Handler &&handler)
	A helper for creation of select_case object for one send-case of a multi chain select.
template<mchain_props::msg_count_status_t Msg_Count_Status, typename... Cases>
mchain_select_result_t	select (const mchain_select_params_t< Msg_Count_Status > &params, Cases &&... cases)
	An advanced form of multi chain select.
template<mchain_props::msg_count_status_t Msg_Count_Status, typename... Cases>
prepared_select_t< sizeof...(Cases) >	prepare_select (mchain_select_params_t< Msg_Count_Status > params, Cases &&... cases)
	Create prepared select statement to be used later.
template<std::size_t Cases_Count>
mchain_select_result_t	select (const prepared_select_t< Cases_Count > &prepared)
	A select operation to be done on previously prepared select params.
template<mchain_props::msg_count_status_t Msg_Count_Status, typename... Cases>
extensible_select_t	make_extensible_select (mchain_select_params_t< Msg_Count_Status > params, Cases &&... cases)
	Creation of extensible-select instance.
template<typename... Cases>
void	add_select_cases (extensible_select_t &extensible_select, Cases &&... cases)
	Add a portion of cases to extensible-select instance.
mchain_select_result_t	select (const extensible_select_t &extensible_select)
	A select operation to be done on previously prepared extensible-select object.
template<typename... Tail>
thread_auto_join_details::auto_joiner_t< 1+sizeof...(Tail) >	auto_join (std::thread &first_thread, Tail &&... tail)
	Helper function for creation of automatic joiner of std::threads.
template<typename Lock_Type = std::mutex>
mbox_t	make_unique_subscribers_mbox (so_5::environment_t &env)
	Factory function for creation of a new instance of unique_subscribers mbox.
Helper functions for creating parameters for mchain.
mchain_params_t	make_unlimited_mchain_params ()
	Create parameters for size-unlimited mchain.
mchain_params_t	make_limited_without_waiting_mchain_params (std::size_t max_size, mchain_props::memory_usage_t memory_usage, mchain_props::overflow_reaction_t overflow_reaction)
	Create parameters for size-limited mchain without waiting on overflow.
mchain_params_t	make_limited_with_waiting_mchain_params (std::size_t max_size, mchain_props::memory_usage_t memory_usage, mchain_props::overflow_reaction_t overflow_reaction, mchain_props::duration_t wait_timeout)
	Create parameters for size-limited mchain with waiting on overflow.
Tools for creating timer threads.
SO_5_FUNC timer_thread_unique_ptr_t	create_timer_wheel_thread (error_logger_shptr_t logger)
	Create timer thread based on timer_wheel mechanism.
SO_5_FUNC timer_thread_unique_ptr_t	create_timer_wheel_thread (error_logger_shptr_t logger, unsigned int wheel_size, std::chrono::steady_clock::duration granuality)
	Create timer thread based on timer_wheel mechanism.
SO_5_FUNC timer_thread_unique_ptr_t	create_timer_heap_thread (error_logger_shptr_t logger)
	Create timer thread based on timer_heap mechanism.
SO_5_FUNC timer_thread_unique_ptr_t	create_timer_heap_thread (error_logger_shptr_t logger, std::size_t initial_heap_capacity)
	Create timer thread based on timer_heap mechanism.
SO_5_FUNC timer_thread_unique_ptr_t	create_timer_list_thread (error_logger_shptr_t logger)
	Create timer thread based on timer_list mechanism.
Standard timer thread factories.
timer_thread_factory_t	timer_wheel_factory ()
	Factory for timer_wheel thread with default parameters.
timer_thread_factory_t	timer_wheel_factory (unsigned int wheel_size, std::chrono::steady_clock::duration granularity)
	Factory for timer_wheel thread with explicitely specified parameters.
timer_thread_factory_t	timer_heap_factory ()
	Factory for timer_heap thread with default parameters.
timer_thread_factory_t	timer_heap_factory (std::size_t initial_heap_capacity)
	Factory for timer_heap thread with explicitely specified parameters.
timer_thread_factory_t	timer_list_factory ()
	Factory for timer_list thread with default parameters.
Tools for creating timer managers.
SO_5_FUNC timer_manager_unique_ptr_t	create_timer_wheel_manager (error_logger_shptr_t logger, outliving_reference_t< timer_manager_t::elapsed_timers_collector_t > collector)
	Create timer manager based on timer_wheel mechanism.
SO_5_FUNC timer_manager_unique_ptr_t	create_timer_wheel_manager (error_logger_shptr_t logger, outliving_reference_t< timer_manager_t::elapsed_timers_collector_t > collector, unsigned int wheel_size, std::chrono::steady_clock::duration granuality)
	Create timer manager based on timer_wheel mechanism.
SO_5_FUNC timer_manager_unique_ptr_t	create_timer_heap_manager (error_logger_shptr_t logger, outliving_reference_t< timer_manager_t::elapsed_timers_collector_t > collector)
	Create timer manager based on timer_heap mechanism.
SO_5_FUNC timer_manager_unique_ptr_t	create_timer_heap_manager (error_logger_shptr_t logger, outliving_reference_t< timer_manager_t::elapsed_timers_collector_t > collector, std::size_t initial_heap_capacity)
	Create timer manager based on timer_heap mechanism.
SO_5_FUNC timer_manager_unique_ptr_t	create_timer_list_manager (error_logger_shptr_t logger, outliving_reference_t< timer_manager_t::elapsed_timers_collector_t > collector)
	Create timer thread based on timer_list mechanism.
Standard timer manager factories.
timer_manager_factory_t	timer_wheel_manager_factory ()
	Factory for timer_wheel manager with default parameters.
timer_manager_factory_t	timer_wheel_manager_factory (unsigned int wheel_size, std::chrono::steady_clock::duration granularity)
	Factory for timer_wheel manager with explicitely specified parameters.
timer_manager_factory_t	timer_heap_manager_factory ()
	Factory for timer_heap manager with default parameters.
timer_manager_factory_t	timer_heap_manager_factory (std::size_t initial_heap_capacity)
	Factory for timer_heap manager with explicitely specified parameters.
timer_manager_factory_t	timer_list_manager_factory ()
	Factory for timer_list manager with default parameters.
Operators for tuning agent_context.
agent_context_t	operator+ (agent_context_t ctx, subscription_storage_factory_t factory)
template<class M >
agent_context_t	operator+ (agent_context_t ctx, message_limit::drop_indicator_t< M > limit)
template<class M >
agent_context_t	operator+ (agent_context_t ctx, message_limit::abort_app_indicator_t< M > limit)
template<class M , class L >
agent_context_t	operator+ (agent_context_t ctx, message_limit::log_then_abort_app_indicator_t< M, L > limit)
template<class M , class L >
agent_context_t	operator+ (agent_context_t ctx, message_limit::redirect_indicator_t< M, L > limit)
template<class M >
agent_context_t	operator+ (agent_context_t ctx, message_limit::transform_indicator_t< M > limit)
agent_context_t	operator+ (agent_context_t ctx, so_5::priority_t agent_priority)
agent_context_t	operator+ (agent_context_t ctx, custom_direct_mbox_factory_t factory)
agent_context_t	operator+ (agent_context_t ctx, name_for_agent_t agent_name)
agent_context_t	operator+ (agent_context_t ctx, demands_handling_on_dereg_t handling_mode)
Helper functions for mchain creation.
mchain_t	create_mchain (environment_t &env)
	Create size-unlimited chain.
mchain_t	create_mchain (wrapped_env_t &sobj)
	Create size-unlimited chain.
mchain_t	create_mchain (environment_t &env, std::size_t max_size, mchain_props::memory_usage_t memory_usage, mchain_props::overflow_reaction_t overflow_reaction)
	Create size-limited chain without waiting on overflow.
mchain_t	create_mchain (wrapped_env_t &sobj, std::size_t max_size, mchain_props::memory_usage_t memory_usage, mchain_props::overflow_reaction_t overflow_reaction)
	Create size-limited chain without waiting on overflow.

Variables
const infinite_wait_indication	infinite_wait
	A special indicator for infinite waiting on service request or on receive from mchain.
const no_wait_indication	no_wait = no_wait_indication::no_wait
	A special indicator for no waiting on service request or on receive from mchain.
constexpr unsigned int	max_redirection_deep = 32
	Maximum deep of message redirections.
const int	rc_environment_error = 1
	so_environment launch is failed.
const int	rc_another_state_switch_in_progress = 170
	An attempt to switch agent state when another switch operation is in progress.
const int	rc_autoshutdown_must_be_enabled = 171
	An attempt to launch environment with autoshutdown disabled in conditions where autoshutdown must be enabled.
const int	rc_mutable_msg_cannot_be_delivered_via_mpmc_mbox = 172
	An attempt to deliver mutable message via MPMC mbox.
const int	rc_mutable_msg_cannot_be_periodic = 173
	An attempt to send mutable message as a periodic message.
const int	rc_subscription_to_mutable_msg_from_mpmc_mbox = 174
	An attempt to make subscription on mutable message from MPMC mbox.
const int	rc_cannot_set_stop_guard_when_stop_is_started = 175
	An attempt to set up a new stop_guard when the stop operation is already in progress.
const int	rc_negative_value_for_pause = 176
	An attempt to use negative value for pause argument for delayed or periodic message/signal.
const int	rc_negative_value_for_period = 177
	An attempt to use negative value for period argument for periodic message/signal.
const int	rc_transfer_to_state_loop = 178
	A loop in transfer_to_state detected.
const int	rc_attempt_to_cast_to_envelope_on_nullptr = 180
	An attempt to cast message to message envelope when a pointer to message is NULL.
const int	rc_unable_to_define_new_step = 181
	New step can't be defined if testing scenario is already started or finished.
const int	rc_scenario_must_be_completed = 182
	Testing scenario must be completed before an attempt to do the current operation.
const int	rc_stored_state_name_not_found = 183
	There is no stored state name in the testing scenario.
const int	rc_coop_already_destroyed = 184
	An attempt to get a pointer to already destroyed cooperation.
const int	rc_coop_is_not_in_registered_state = 185
	An attempt to do something with coop that is not in registered state.
const int	rc_unable_to_join_thread_by_itself = 186
	An attempt to call join() from the joinable thread itself.
const int	rc_extensible_select_is_active_now = 187
	An attempt to modify or activate extensible-select when an operation on that extensible-select object is already active.
const int	rc_prepared_select_is_active_now = 188
	An attempt to activate prepared-select when an operation on that prepared-select object is already active.
const int	rc_agent_deactivated = 189
	Agent can't change state because the agent is already deactivated.
const int	rc_mpsc_mbox_expected = 190
	An instance of MPSC mbox is expected as custom direct mbox.
const int	rc_nullptr_as_delivery_filter_pointer = 191
	nullptr can't be passed as delivery_filter.
const int	rc_nullptr_as_result_of_user_mbox_factory = 192
	nullptr returned by user-provided mbox factory.
const int	rc_no_preallocated_resources_for_agent = 193
	There are no resources that must have been in place for an agent in advance.
const int	rc_disp_binder_already_set_for_agent = 194
	The dispatcher binder is already set for the agent.
const int	rc_no_disp_binder_for_agent = 195
	The dispatcher binder is not set for the agent yet.
const int	rc_empty_agent_name = 196
	Name for an agent can't be empty.
const int	rc_agent_name_too_long = 197
	Length of an agent name is too large.
const int	rc_stored_msg_inspection_result_not_found = 198
	There is no stored msg inspection result in the testing scenario.
const thread_safety_t	not_thread_safe = thread_safety_t::unsafe
	Shorthand for thread unsafety indicator.
const thread_safety_t	thread_safe = thread_safety_t::safe
	Shorthand for thread safety indicator.
constexpr exceptions_enabled_t	exceptions_enabled {}
	Value that indicates that exceptions are enabled.
constexpr terminate_if_throws_t	terminate_if_throws
	Value that indicates that an exception leads to the termination of the whole application.
constexpr demands_handling_on_dereg_t	skip_demands_on_dereg
	Marker that tells that pending demands have to be skipped on deregistration.
Error codes for agent's methods.
const int	rc_agent_unknown_state = 10
	Trying to switch to the unknown state.
const int	rc_agent_has_no_cooperation = 14
	Agent is not bound to a cooperation.
const int	rc_agent_incompatible_type_conversion = 15
	It is impossible to make a cast to that type.
const int	rc_operation_enabled_only_on_agent_working_thread = 16
	An attempt to perform an operation which is enabled only on agent's working thread.
const int	rc_no_initial_substate = 17
	An attempt to change agent state to a new composite state which have no initial state defined.
const int	rc_state_nesting_is_too_deep = 18
	Nesting of agent states is too deep.
const int	rc_initial_substate_already_defined = 19
	Initial substate for a composite state is already defined.
Error codes for cooperations of agents.
const int	rc_coop_define_agent_failed = 24
	Cooperation couldn't be registered.
const int	rc_agent_to_disp_binding_failed = 27
	Binding of agent to dispatcher failed.
const int	rc_unable_to_register_coop_during_shutdown = 28
	It is impossible to register cooperation during SObjectizer Environment shutdown.
Error codes for dispatchers.
const int	rc_disp_create_failed = 31
	Unable to create a dispatcher.
Error codes for event handlers and message interceptors registration.
const int	rc_evt_handler_already_provided = 40
	A handler for that event/mbox/state is already registered.
const int	rc_agent_is_not_the_state_owner = 43
	Agent doesn't own this state.
const int	rc_illegal_subscriber_for_mpsc_mbox = 47
	An attempt to create illegal subscription to mpsc_mbox.
const int	rc_message_has_no_limit_defined = 48
	An attempt to create subscription to message without predefined limit for that message type.
const int	rc_several_limits_for_one_message_type = 49
	An attempt to define several limits for one message type.
Error codes for mboxes.
const int	rc_null_message_data = 82
	Null message data.
Error codes for layers.
const int	rc_layer_not_binded_to_so_env = 100
	The layer is not bound to the SObjectizer Environment.
const int	rc_trying_to_add_nullptr_extra_layer = 101
	Unable to bind a layer by the null pointer to it.
const int	rc_trying_to_add_extra_layer_that_already_exists_in_default_list = 102
	The layer is already bound to the SObjectizer Environment as a default layer.
const int	rc_trying_to_add_extra_layer_that_already_exists_in_extra_list = 103
	The layer is already bound to the SObjectizer Environment as an extra layer.
const int	rc_unable_to_start_extra_layer = 104
	Layer initialization is failed.
const int	rc_layer_does_not_exist = 105
	A layer with the specified type doesn't exist.
Error codes for priorities.
const int	rc_priority_quote_illegal_value = 120
	Illegal value of quote for a priority.
Error codes for SObjectizer Environment related errors.
const int	rc_msg_tracing_disabled = 140
	Message delivery tracing is disabled and cannot be used.
Error codes for message chains.
const int	rc_msg_chain_is_empty = 160
	Attempt to get message from empty message queue.
const int	rc_msg_chain_is_full = 161
	Attempt to push a message to full message queue.
const int	rc_msg_chain_doesnt_support_subscriptions = 162
	Attempt to make subscription for message chain.
const int	rc_msg_chain_doesnt_support_delivery_filters = 163
	Attempt to set delivery_filter for message chain.
const int	rc_msg_chain_overflow = 164
const int	rc_several_handlers_for_one_message_type = 165
	Attempt to define several handlers for one msg_type.
Common error codes.
const int	rc_empty_name = 500
	The empty name doesn't allowed.
const int	rc_invalid_time_limit_for_state = 501
	Invalid value of time limit for an agent's state.
const int	rc_not_implemented = 502
	Feature or method has no implementation yet.
const int	rc_unknown_exception_type = 503
	An exception of unknown type is caught.
const int	rc_unexpected_error = 0xFFFFFF
	Unclassified error.

Detailed Description

Private part of message limit implementation.

Implementation of message sink that ignores message limits.

Implementation of message sink that handles message limits.

A base class for message sinks to be used by agents.

Main SObjectizer-5 namespace.

Public part of message limit implementation.

Since

v.5.8.0

v.5.5.4

Typedef Documentation

agent_ref_t

using so_5::agent_ref_t = intrusive_ptr_t< agent_t >

A smart reference to an agent.

Note

Defined as typedef since v.5.2.0

Definition at line 29 of file agent_ref_fwd.hpp.

agent_state_listener_unique_ptr_t

using so_5::agent_state_listener_unique_ptr_t

Initial value:

 
    std::unique_ptr< agent_state_listener_t >

Typedef for the agent_state_listener autopointer.

Definition at line 66 of file agent_state_listener.hpp.

atomic_counter_t

using so_5::atomic_counter_t = std::atomic_ulong

Atomic counter type.

Definition at line 24 of file types.hpp.

atomic_flag_t

using so_5::atomic_flag_t = std::atomic_ulong

Atomic flag type.

Definition at line 28 of file types.hpp.

coop_dereg_notificator_t

using so_5::coop_dereg_notificator_t

Initial value:

 std::function<
    void(
        environment_t &,
        const coop_handle_t &,
        const coop_dereg_reason_t &) >

Type of cooperation deregistration notificator.

Cooperation notificator should be a function with the following prototype:

void
notificator(
  // SObjectizer Environment for cooperation.
  so_5::environment_t & env,
  // Coop's handle.
  const coop_handle_t & coop,
  // Reason of deregistration.
  const so_5::coop_dereg_reason_t & reason );

Since

v.5.2.3

Definition at line 181 of file coop.hpp.

coop_dereg_notificators_container_ref_t

using so_5::coop_dereg_notificators_container_ref_t

Initial value:

 
    intrusive_ptr_t< coop_dereg_notificators_container_t >

Typedef for smart pointer to notificators_container.

Since

v.5.2.3

Definition at line 226 of file coop.hpp.

coop_id_t

using so_5::coop_id_t = std::uint_fast64_t

ID of cooperation.

Since

v.5.6.0

Definition at line 131 of file types.hpp.

coop_listener_unique_ptr_t

using so_5::coop_listener_unique_ptr_t = std::unique_ptr< coop_listener_t >

Typedef for the coop_listener autopointer.

Definition at line 80 of file coop_listener.hpp.

coop_reg_notificator_t

using so_5::coop_reg_notificator_t

Initial value:

 
    std::function< void(environment_t &, const coop_handle_t &) >

Type of cooperation registration notificator.

Cooperation notificator should be a function with the following prototype:

void
notificator(
  // SObjectizer Environment for cooperation.
  so_5::environment_t & env,
  // Coop's handle.
  const coop_handle_t & coop );

Since

v.5.2.3

Definition at line 116 of file coop.hpp.

coop_reg_notificators_container_ref_t

using so_5::coop_reg_notificators_container_ref_t

Initial value:

 
    intrusive_ptr_t< coop_reg_notificators_container_t >

Typedef for smart pointer to notificators_container.

Since

v.5.2.3

Definition at line 157 of file coop.hpp.

coop_shptr_t

using so_5::coop_shptr_t = std::shared_ptr< coop_t >

Typedef for the agent_coop smart pointer.

Definition at line 29 of file coop_handle.hpp.

current_thread_id_t

using so_5::current_thread_id_t = std::thread::id

Type of the current thread id.

Definition at line 26 of file current_thread_id.hpp.

custom_direct_mbox_factory_t

using so_5::custom_direct_mbox_factory_t

Initial value:

 std::function<
    so_5::mbox_t(partially_constructed_agent_ptr_t, so_5::mbox_t) >

Type of functor to be used as a factory for custom direct mbox.

Attention

The factory should return a valid mbox or should throw an exception. The behavior isn't defined if the factory return empty so_5::mbox_t object (the application may crash in the better case).

Since

v.5.7.4

Definition at line 57 of file agent_tuning_options.hpp.

default_rw_spinlock_t

using so_5::default_rw_spinlock_t = rw_spinlock_t< pause_backoff_t >

Definition at line 233 of file spinlocks.hpp.

default_spinlock_t

using so_5::default_spinlock_t = spinlock_t< pause_backoff_t >

Definition at line 134 of file spinlocks.hpp.

delivery_filter_unique_ptr_t

using so_5::delivery_filter_unique_ptr_t

Initial value:

 
  std::unique_ptr< delivery_filter_t >

An alias of unique_ptr for delivery_filter.

Since

v.5.5.5

Definition at line 95 of file mbox.hpp.

demand_handler_pfn_t

using so_5::demand_handler_pfn_t

Initial value:

 void (*)(
  current_thread_id_t,
  execution_demand_t & )

Demand handler prototype.

Since

v.5.2.0

Definition at line 47 of file execution_demand.hpp.

disp_binder_shptr_t

using so_5::disp_binder_shptr_t = std::shared_ptr< disp_binder_t >

Typedef for the disp_binder smart pointer.

Examples

so_5/hardwork_imit/main.cpp.

Definition at line 99 of file disp_binder.hpp.

environment_infrastructure_deleter_fnptr_t

using so_5::environment_infrastructure_deleter_fnptr_t

Initial value:

 
  void (*)(environment_infrastructure_t *)

A type for deleter for environment_infrastructure objects.

Since

v.5.5.19

Definition at line 34 of file environment_infrastructure.hpp.

environment_infrastructure_factory_t

using so_5::environment_infrastructure_factory_t

Initial value:

 
    std::function<
        environment_infrastructure_unique_ptr_t(
            environment_t &,
            environment_params_t &,
            mbox_t) >

Type of factory for environment infrastructure.

A factory must be a function with the following format:

environment_infrastructure_unique_ptr_t
factory(
  // Environment for which env_infrastructure will be created.
  environment_t & env,
  // Parameters for that environment.
  environment_params_t & params,
  // Message box for distribution of run-time statistics.
  mbox_t stats_distribution_mbox );

Since

v.5.5.19

Definition at line 290 of file environment_infrastructure.hpp.

environment_infrastructure_unique_ptr_t

using so_5::environment_infrastructure_unique_ptr_t

Initial value:

 
    std::unique_ptr<
        environment_infrastructure_t,
        environment_infrastructure_deleter_fnptr_t >

A type of unique pointer for environment_infrastructure entity.

Note

A deleter should be specified for entity object. It makes possible to create unique pointers for objects which must not be delete via delete operator. For example:

// Object is created on stack. Need not to be deleted.
my_special_infrastructure_t my( ... );
so_5::launch( [](so_5::environment_t & env) {...},
  [&](so_5::environment_params_t & p) {
    p.environment_infrastructure(
      [&](so_5::environment_t &, so_5::environment_params_t &) {
        return so_5::environment_infrastructure_unique_ptr_t(
            &my, [](so_5::environment_infrastructure_t *){} );
      } );
    ...
  } );

Since

v.5.5.19

Definition at line 265 of file environment_infrastructure.hpp.

error_logger_shptr_t

using so_5::error_logger_shptr_t = std::shared_ptr< error_logger_t >

An alias for shared_ptr to error_logger.

Since

v.5.5.0

Definition at line 71 of file error_logger.hpp.

event_exception_logger_unique_ptr_t

using so_5::event_exception_logger_unique_ptr_t

Initial value:

 
  std::unique_ptr< event_exception_logger_t >

Typedef for the event_exception_logger autopointer.

Definition at line 31 of file event_exception_logger.hpp.

event_handler_method_t

using so_5::event_handler_method_t = std::function< void(message_ref_t &) >

Type of event handler method.

Since

v.5.3.0

Definition at line 34 of file execution_demand.hpp.

event_queue_hook_deleter_fnptr_t

using so_5::event_queue_hook_deleter_fnptr_t = void (*)(event_queue_hook_t *)

A type for deleter of event_queue_hook object.

Since

v.5.5.24

Definition at line 34 of file event_queue_hook.hpp.

event_queue_hook_unique_ptr_t

using so_5::event_queue_hook_unique_ptr_t

Initial value:

 
    std::unique_ptr<
        event_queue_hook_t,
        event_queue_hook_deleter_fnptr_t >

Alias for unique pointer to event_queue_hook.

Since

v.5.5.24

Definition at line 161 of file event_queue_hook.hpp.

generic_simple_init_t

using so_5::generic_simple_init_t = std::function< void(so_5::environment_t &) >

Generic type for a simple SObjectizer-initialization function.

Since

v.5.3.0

Definition at line 64 of file api.hpp.

generic_simple_so_env_params_tuner_t

using so_5::generic_simple_so_env_params_tuner_t

Initial value:

 
    std::function< void(so_5::environment_params_t &) >

Generic type for a simple SO Environment paramenters tuning function.

Since

v.5.3.0

Definition at line 72 of file api.hpp.

layer_map_t

using so_5::layer_map_t = std::map< std::type_index, layer_ref_t >

Typedef for the map from a layer typeid to the layer.

Definition at line 95 of file so_layer.hpp.

layer_ref_t

using so_5::layer_ref_t = std::shared_ptr< layer_t >

Typedef for the layer's smart pointer.

Definition at line 92 of file so_layer.hpp.

layer_unique_ptr_t

using so_5::layer_unique_ptr_t = std::unique_ptr< layer_t >

Typedef for the layer's autopointer.

Definition at line 89 of file so_layer.hpp.

mbox_id_t

using so_5::mbox_id_t = unsigned long long

A type for mbox indentifier.

Definition at line 31 of file types.hpp.

mbox_t

using so_5::mbox_t = intrusive_ptr_t< abstract_message_box_t >

Smart reference for the abstract_message_box.

Note

Defined as typedef since v.5.2.0

Definition at line 29 of file mbox_fwd.hpp.

mchain_t

using so_5::mchain_t = intrusive_ptr_t< abstract_message_chain_t >

Short name for smart pointer to message chain.

Since

v.5.5.13

Definition at line 648 of file mchain.hpp.

message_ref_t

using so_5::message_ref_t = intrusive_ptr_t< message_t >

A smart reference to the message.

Note

Defined as typedef since v.5.2.0

Definition at line 261 of file message.hpp.

msink_t

using so_5::msink_t = intrusive_ptr_t< abstract_sink_owner_t >

Smart reference for abstract_sink_owner.

Since

v.5.8.0

Definition at line 218 of file message_sink.hpp.

mutable_mhood_t

template<typename M >

using so_5::mutable_mhood_t = mhood_t< mutable_msg<M> >

A short name for message hood for mutable message.

Since

v.5.5.19

Definition at line 630 of file mhood.hpp.

queue_locks_defaults_manager_unique_ptr_t

using so_5::queue_locks_defaults_manager_unique_ptr_t

Initial value:

 
  std::unique_ptr< queue_locks_defaults_manager_t >

An alias of unique_ptr for queue_locks_defaults_manager.

Since

v.5.5.18

Definition at line 68 of file queue_locks_defaults_manager.hpp.

stop_guard_shptr_t

using so_5::stop_guard_shptr_t = std::shared_ptr< stop_guard_t >

An alias of shared_ptr for stop_guard.

Since

v.5.5.19.2

Definition at line 87 of file stop_guard.hpp.

subscription_storage_factory_t

using so_5::subscription_storage_factory_t

Initial value:

 
    std::function<
        impl::subscription_storage_unique_ptr_t() >

Type of subscription_storage factory.

Since

v.5.5.3

Definition at line 47 of file subscription_storage_fwd.hpp.

timer_manager_factory_t

using so_5::timer_manager_factory_t

Initial value:

 std::function<
    timer_manager_unique_ptr_t(
        error_logger_shptr_t,
        outliving_reference_t< timer_manager_t::elapsed_timers_collector_t > ) >

Type of factory for creating timer_manager objects.

Since

v.5.5.19

Definition at line 557 of file timers.hpp.

timer_manager_unique_ptr_t

using so_5::timer_manager_unique_ptr_t = std::unique_ptr< timer_manager_t >

Auxiliary typedef for timer_manager autopointer.

Since

v.5.5.19

Definition at line 546 of file timers.hpp.

timer_thread_factory_t

using so_5::timer_thread_factory_t

Initial value:

 std::function<
    timer_thread_unique_ptr_t( error_logger_shptr_t ) >

Type of factory for creating timer_thread objects.

Since

v.5.5.0

Definition at line 237 of file timers.hpp.

timer_thread_unique_ptr_t

using so_5::timer_thread_unique_ptr_t = std::unique_ptr< timer_thread_t >

Auxiliary typedef for timer_thread autopointer.

Definition at line 226 of file timers.hpp.

Enumeration Type Documentation

delivery_possibility_t

enum class so_5::delivery_possibility_t

strong

Result of checking delivery posibility.

Since

v.5.5.9

Enumerator
must_be_delivered
no_subscription
disabled_by_delivery_filter
hidden_by_envelope	The actual message is hidden by an envelope. Since v.5.5.23

Definition at line 38 of file mbox.hpp.

demands_handling_on_dereg_t

enum class so_5::demands_handling_on_dereg_t

strong

How pending demands should be handled on deregistration.

Since

v.5.8.5

Enumerator
normal	Pending demands have to be handled as usual.
skip	Pending demands have to be skipped.

Definition at line 191 of file agent_tuning_options.hpp.

event_handler_kind_t

enum class so_5::event_handler_kind_t : char

strong

Kind of an event handler.

Since v.5.7.0 event handlers of an agent are devided into the following categories:

• final handler. That is an ordinary handler that takes a message and handles it. In the case of an enveloped message a final handler should take the payload of a message;
• intermediate handler. That is a special handler that doesn't handle a message by itself but delegates the handling to some other event handler or just suppresses the message. In the case of enveloped message an intermediate handler should take the whole envelope.

Since

v.5.7.0

Enumerator
final_handler	Ordinary, final event handler. That event handler should take the payload from an eveloped message.
intermediate_handler	Intermediate event handler. Doesn't handle a message itself but delegates actual processing to some other event handler. Or just skips the processing of the message. That event handler should take the whole envelope.

Definition at line 153 of file types.hpp.

exception_reaction_t

enum so_5::exception_reaction_t

A reaction of SObjectizer to an exception from agent event.

Since

v.5.2.3

Enumerator
abort_on_exception	Execution of application must be aborted immediatelly.
shutdown_sobjectizer_on_exception	Agent must be switched to special state and SObjectizer Environment will be stopped.
deregister_coop_on_exception	Agent must be switched to special state and agent's cooperation must be deregistered.
ignore_exception	Exception should be ignored and agent should continue its work.
inherit_exception_reaction	Exception reaction should be inherited from SO Environment. Since v.5.3.0

Definition at line 64 of file agent.hpp.

infinite_wait_indication

enum class so_5::infinite_wait_indication

strong

A type for special marker for infitite waiting on service request or on receive from mchain.

Since

v.5.5.13

Enumerator
infinite_wait

Definition at line 24 of file wait_indication.hpp.

mbox_type_t

enum class so_5::mbox_type_t

strong

Type of the message box.

Since

v.5.5.3

Note

This type is no more marked as deprecated.

Enumerator
multi_producer_multi_consumer	Mbox is Multi-Producer and Multi-Consumer. Anyone can send messages to it, there can be many subscribers.
multi_producer_single_consumer	Mbox is Multi-Producer and Single-Consumer. Anyone can send messages to it, there can be only one subscriber.

Definition at line 162 of file mbox.hpp.

message_delivery_mode_t

enum class so_5::message_delivery_mode_t

strong

Possible modes of message/signal delivery.

Since

v.5.8.0

Enumerator
ordinary	Ordinary delivery. The send operation can block (for example on an attempt to send a message to a full mchain).
nonblocking	Delivery that prohibit blocking. For example a delivery of a delayed/periodic can't block the current thread (because it's the timer thread and the timer thread can't be blocked). NOTE. The current version also prohibit throwing of exceptions.

Definition at line 171 of file types.hpp.

message_kind_t

enum class so_5::message_kind_t

strong

A enum with variants of message kinds.

Since

v.5.5.23

Enumerator
signal	Message is a signal. It means there is no data associated with the message instance.
classical_message	Message is a classical message. It means that message is an instance of class derived from message_t.
user_type_message	Message is an user type message.
enveloped_msg	Message is an envelope with some other message inside.

Definition at line 108 of file types.hpp.

message_mutability_t

enum class so_5::message_mutability_t

strong

A enum with variants of message mutability or immutability.

Since

v.5.5.19

Enumerator
immutable_message
mutable_message

Definition at line 93 of file types.hpp.

message_ownership_t

enum class so_5::message_ownership_t

strong

Type of ownership of a message instance inside message_holder.

This type is intended to be used as parameter for message_holder_t template.

Since

v.5.6.0

Enumerator
autodetected	Type of ownership will be automatically detected in dependency of message mutability.
unique	An instance of message_holder should be the unique holder of the message instance. In that case message_holder will be similar to unique_ptr.
shared	Several instances of message_holder can own the message instance. In that case message_holder will be similar to shared_ptr.

Definition at line 33 of file message_holder.hpp.

no_wait_indication

enum class so_5::no_wait_indication

strong

A type for special marker for no waiting on service request or on receive from mchain.

Since

v.5.5.13

Enumerator
no_wait

Definition at line 43 of file wait_indication.hpp.

priority_t

enum class so_5::priority_t : unsigned char

strong

Definition of supported priorities.

Since

v.5.5.8

Enumerator
p_min
p0
p1
p2
p3
p4
p5
p6
p7
p_max

Definition at line 27 of file priority.hpp.

thread_safety_t

enum class so_5::thread_safety_t : std::uint8_t

strong

Thread safety indicator.

Since

v.5.4.0

Enumerator
unsafe	Not thread safe.
safe	Thread safe.

Definition at line 49 of file types.hpp.

work_thread_activity_tracking_t

enum class so_5::work_thread_activity_tracking_t

strong

Values for dispatcher's work thread activity tracking.

Enumerator
unspecified	Tracking mode is specified elsewhere.
off	Tracking is disabled.
on	Tracking is enabled.

Definition at line 74 of file types.hpp.

Function Documentation

adaptive_subscription_storage_factory() [1/2]

SO_5_FUNC subscription_storage_factory_t so_5::adaptive_subscription_storage_factory ( std::size_t threshold )

nodiscard

Factory for adaptive subscription storage.

Description

This storage will use vector-based storage for small amount of subscriptions. And map-based storage for large amount of subscriptions.

More about subscription storage tuning

See so-5.5.3: Subscription storage type selection for more details about selection of appropriate subscription storage type.

Since

v.5.5.3

Parameters

threshold

Threshold for switching from small storage to the large one (and back from the large to the small in the case of subscription deletion).

Definition at line 263 of file subscr_storage_adaptive.cpp.

adaptive_subscription_storage_factory() [2/2]

SO_5_FUNC subscription_storage_factory_t so_5::adaptive_subscription_storage_factory ( std::size_t threshold, const subscription_storage_factory_t & small_storage_factory, const subscription_storage_factory_t & large_storage_factory )

nodiscard

Factory for adaptive subscription storage.

Description

This storage will use storage created by small_storage_factory for small amount of subscriptions. And storage created by large_storage_factory for large amount of subscriptions.

Cascading of storages

This function can be used for creating more complex cascades of several subscription storages. For example, the following code creates adaptive storage with three underlying objects. The first will be used for 0..10 subscriptions. The seconds will be used for 11..100 subscriptions. And the third for 100+ subscriptions:

so_5::adaptive_subscription_storage_factory(
  // First threshold for switching from the first storage to the second.
  10,
  // First storage -- simple vector-based.
  so_5::vector_based_subscription_storage_factory(10),
  // There will be another adaptive storage.
  so_5::adaptive_subscription_storage_factory(
    // Second threshold for switching from the second storage to the third.
    100,
    // Second storage.
    so_5::map_based_subscription_storage_factory(),
    // Third storage.
    so_5::hash_table_based_subscription_storage_factory() ) );

More about subscription storage tuning

See so-5.5.3: Subscription storage type selection for more details about selection of appropriate subscription storage type.

Since

v.5.5.3

Parameters

threshold	Threshold for switching from small storage to the large one (and back from the large to the small in the case of subscription deletion).
small_storage_factory	A factory for creating small storage.
large_storage_factory	A factory for creating large storage.

Definition at line 276 of file subscr_storage_adaptive.cpp.

add_select_cases()

template<typename... Cases>

void so_5::add_select_cases	(	extensible_select_t &	extensible_select,
		Cases &&...	cases )

Add a portion of cases to extensible-select instance.

Usage examples:

// Creation of extensible-select instance without initial set of cases.
auto sel2 = so_5::make_extensible_select(
  so_5::from_all().handle_n(20));
// Cases should be added later.
so_5::add_select_cases(sel2, receive_case(ch1, ...));
so_5::add_select_cases(sel2,
  receive_case(ch2, ...),
  receive_case(ch3, ...));

Note

An attempt to call this function for extensible-select object that is used in some select() call will lead to an exception.

Attention

The extensible_select object must not be empty!

Since

v.5.6.1

Parameters

extensible_select	An instance of extensible-select to be extended.
cases	Select cases.

Definition at line 2163 of file mchain_select.hpp.

auto_close_drop_content()

template<typename... Tail>

mchain_auto_close_details::auto_closer_t< sizeof...(Tail) > so_5::auto_close_drop_content

(

Tail &&...

tail

)

Helper function for automatic closing of mchains with dropping their content.

Usage example:

so_5::environment_t & env = ...;
auto ch1 = create_mchain(env);
auto ch2 = create_mchain(env);
auto ch_closer = so_5::auto_close_drop_content(ch1, ch2);
...

Note

This is just a shorthand for:

so_5::auto_close_mchains(
  so_5::mchain_props::close_mode_t::drop_content, chains... );

Attention

Since v.5.7.3 it uses so_5::terminate_if_throws calling 'close' for mchains.

Template Parameters

Tail	List of mchains.

Since

v.5.5.16

Examples

so_5/mchain_select/main.cpp, and so_5/wrapped_env_demo_3/main.cpp.

Definition at line 470 of file mchain_helper_functions.hpp.

auto_close_mchains()

template<typename... Tail>

mchain_auto_close_details::auto_closer_t< sizeof...(Tail) > so_5::auto_close_mchains	(	mchain_props::close_mode_t	close_mode,
		Tail &&...	tail )

Helper function for creation of automatic closer of mchains.

Usage examples:

so_5::environment_t & env = ...;
auto command_ch = create_mchain( env );
auto reply_ch = create_mchain( env );
std::thread worker{ [command_ch, reply_ch] {
    receive( from( command_ch ), handlers... );
  } };
// Chains must be closed automatically on any exception...
// Content of chains must be dropped.
auto channels_closer = so_5::auto_close_mchains(
    so_5::mchain_props::close_mode_t::drop_content,
    command_ch,
    reply_ch );
 
... // Some complex code here.
 
// Close command chain for worker thread. Worker will finish its work.
close_retain_content( command_ch );
// Ensure that worker finished.
worker.join();

Attention

Since v.5.7.3 it uses so_5::terminate_if_throws calling 'close' for mchains.

Since

v.5.5.16

Parameters

close_mode	Close mode for all mchains. This value will be passed to all close() calls.
tail	Chains to be closed.

Definition at line 390 of file mchain_helper_functions.hpp.

auto_close_retain_content()

template<typename... Tail>

mchain_auto_close_details::auto_closer_t< sizeof...(Tail) > so_5::auto_close_retain_content

(

Tail &&...

tail

)

Helper function for automatic closing of mchains with retaining their content.

Usage example:

so_5::environment_t & env = ...;
auto ch1 = create_mchain(env);
auto ch2 = create_mchain(env);
auto ch_closer = so_5::auto_close_retain_content(ch1, ch2);
...

Note

This is just a shorthand for:

so_5::auto_close_mchains(
  so_5::mchain_props::close_mode_t::retain_content, chains... );

Attention

Since v.5.7.3 it uses so_5::terminate_if_throws calling 'close' for mchains.

Template Parameters

Tail	List of mchains.

Since

v.5.5.16

Definition at line 434 of file mchain_helper_functions.hpp.

auto_join()

template<typename... Tail>

thread_auto_join_details::auto_joiner_t< 1+sizeof...(Tail) > so_5::auto_join	(	std::thread &	first_thread,
		Tail &&...	tail )

Helper function for creation of automatic joiner of std::threads.

Usage examples:

std::thread first_worker;
std::thread second_worker;
auto worker_joiner = so_5::auto_join( first_worker, second_worker );
 
first_worker = thread{ ... };
second_worker = thread{ ... };
...

Since

v.5.5.16

Parameters

first_thread	The first thread to be closed.
tail	Other threads to be closed.

Examples

so_5/mchain_select/main.cpp, and so_5/wrapped_env_demo_3/main.cpp.

Definition at line 133 of file thread_helper_functions.hpp.

bind_transformer() [1/4]

template<typename Binding , typename Transformer >

void so_5::bind_transformer	(	Binding &	binding,
		const so_5::mbox_t &	src_mbox,
		Transformer &&	transformer )

Helper function to add transform_then_redirect msink to a binding object.

Type of source message is automatically deduced from the type of transformer argument.

Usage example:

struct part { ... };
struct compound {
  part m_first;
  part m_second;
};
 
...
so_5::mbox_t src_mbox = ...;
so_5::mbox_t dest_mbox = ...;
 
so_5::single_sink_binding_t binding;
so_5::bind_transformer(binding, src_mbox,
  [dest_mbox](const compound & msg) {
    return so_5::make_transformed<part>(
      dest_mbox, // Destination for the transformed message.
      msg.m_first // Initializer for the new `part` instance.
    );
  });

The transformer is expected to return a so_5::transformed_message_t or std::optional<so_5::transformed_message_t>:

so_5::bind_transformer(binding, src_mbox,
  [dest_mbox](const compound & msg)
    -> std::optional<so_5::transformed_message_t<part>>
  {
    if(should_message_be_transformed(msg)) {
      return {
        so_5::make_transformed<part>(
          dest_mbox, // Destination for the transformed message.
          msg.m_first // Initializer for the new `part` instance.
      ) };
    }
    else
      return std::nullopt; // No transformation.
  });

Note

Because the type of the source message is deduced from transformer argument this helper can't be used for transforming mutable messages and signals.

Attention

The transformer can't have an argument in the form of const auto &:

// Compilation error is expected here because the type of
// the transformer argument can't be deduced.
so_5::bind_transformer(binding, src, [](const auto & msg) {...});

Template Parameters

Binding	type of binding object. It's expected to be so_5::single_sink_binding_t, so_5::multi_sink_binding_t or a similar type with the same interface.
Transformer	type of transformer functor (a lambda or free function).

Since

v.5.8.1

Parameters

binding	Binding object to be used.
src_mbox	Source mbox. It must not be nullptr.
transformer	Transformer that produced so_5::transformed_message_t instance or std::optional<so_5::transformed_message_t> instance.

Examples

so_5/bind_transformer/main.cpp.

Definition at line 98 of file bind_transformer_helpers.hpp.

bind_transformer() [2/4]

template<typename Expected_Msg , typename Binding , typename Transformer >

void so_5::bind_transformer	(	Binding &	binding,
		const so_5::mbox_t &	src_mbox,
		Transformer &&	transformer )

Helper function to add transform_then_redirect msink to a binding object.

The type of the source message is specified explicitly.

Attention

Because the source message is specified explicitly, this helper can be used for immutable, mutable messages, and signals.

Usage example:

struct part { ... };
struct compound {
  part m_first;
  part m_second;
};
 
...
so_5::mbox_t src_mbox = ...;
so_5::mbox_t dest_mbox = ...;
 
so_5::single_sink_binding_t binding;
so_5::bind_transformer< so_5::mutable_msg<compound> >(binding, src_mbox,
  [dest_mbox](compound & msg) { // or [dest_mbox](auto & msg)
    return so_5::make_transformed<part>(
      dest_mbox, // Destination for the transformed message.
      std::move(msg.m_first) // Initializer for the new `part` instance.
    );
  });

If this helper is used for signals then transformer should be a function without arguments:

struct first_signal final : public so_5::signal_t {};
struct second_signal final : public so_5::signal_t {};
 
...
so_5::mbox_t src_mbox = ...;
so_5::mbox_t dest_mbox = ...;
 
so_5::single_sink_binding_t binding;
so_5::bind_transformer< first_signal >(binding, src_mbox,
  [dest_mbox]() {
    return so_5::make_transformed<second_signal>(
      dest_mbox // Destination for the transformed message.
    );
  });

The transformer is expected to return a so_5::transformed_message_t or std::optional<so_5::transformed_message_t>:

// so_5::immutable_msg is supported as well as so_5::mutable_msg.
so_5::bind_transformer< so_5::immutable_msg<compound> >(binding, src_mbox,
  [dest_mbox](const auto & msg)
    -> std::optional<so_5::transformed_message_t<part>>
  {
    if(should_message_be_transformed(msg)) {
      return {
        so_5::make_transformed<part>(
          dest_mbox, // Destination for the transformed message.
          msg.m_first // Initializer for the new `part` instance.
      ) };
    }
    else
      return std::nullopt; // No transformation.
  });

Note

The transformer can have an argument in the form of const auto &:

so_5::bind_transformer< compound >(binding, src, [](const auto & msg) {...});

Template Parameters

Expected_Msg	type of the source message or signal. If Msg is the message type, then Msg, so_5::immutable_msg<Msg> or so_5::mutable_msg<Msg> can be used. If Msg is the signal type then Msg or so_5::immutable_msg<Msg> is allowed.
Binding	type of binding object. It's expected to be so_5::single_sink_binding_t, so_5::multi_sink_binding_t or a similar type with the same interface.
Transformer	type of transformer functor (a lambda or free function).

Since

v.5.8.1

Parameters

binding	Binding object to be used.
src_mbox	Source mbox. It must not be nullptr.
transformer	Transformer that produced so_5::transformed_message_t instance or std::optional<so_5::transformed_message_t> instance.

Definition at line 305 of file bind_transformer_helpers.hpp.

bind_transformer() [3/4]

template<typename Expected_Msg , typename Binding , typename Transformer , typename Delivery_Filter >

void so_5::bind_transformer	(	Binding &	binding,
		const so_5::mbox_t &	src_mbox,
		Transformer &&	transformer,
		Delivery_Filter &&	delivery_filter )

Helper function to add transform_then_redirect msink to a binding object (with a delivery filter).

The type of the source message is specified explicitly.

Attention

Because the source message is specified explicitly, this helper can be used for immutable and mutable messages.

This helper can't be used for signals because delivery filters are not applicable to signals.

Usage example:

struct part { ... };
struct compound {
  part m_first;
  part m_second;
};
 
...
so_5::mbox_t src_mbox = ...;
so_5::mbox_t dest_mbox = ...;
 
so_5::single_sink_binding_t binding;
so_5::bind_transformer< so_5::mutable_msg<compound> >(binding, src_mbox,
  [dest_mbox](compound & msg) { // or [dest_mbox](auto & msg)
    return so_5::make_transformed<part>(
      dest_mbox, // Destination for the transformed message.
      std::move(msg.m_first) // Initializer for the new `part` instance.
    );
  },
  // Note the use of const, delivery filter always receives a const
  // reference for a message to be filtered.
  [](const compound & msg) { // or [](const auto & msg)
    return ...; // Some predicate.
  });

The transformer is expected to return a so_5::transformed_message_t or std::optional<so_5::transformed_message_t>:

so_5::bind_transformer< so_5::mutable_msg<compound> >(binding, src_mbox,
  [dest_mbox](auto & msg)
    -> std::optional<so_5::transformed_message_t<part>>
  {
    if(should_message_be_transformed(msg)) {
      return {
        so_5::make_transformed<part>(
          dest_mbox, // Destination for the transformed message.
          std::move(msg.m_first) // Initializer for the new `part` instance.
      ) };
    }
    else
      return std::nullopt; // No transformation.
  },
  // Note the use of const, delivery filter always receives a const
  // reference for a message to be filtered.
  [](const compound & msg) { // or [](const auto & msg)
    return ...; // Some predicate.
  });

Note

The transformer can have an argument in the form of const auto &:

so_5::bind_transformer< compound >(binding, src,
  // Transformer.
  [](const auto & msg) {...},
  // Delivery filter
  [](const auto & msg) {...});

Template Parameters

Expected_Msg	type of the source message or signal. When Msg is the expected message type, then Msg, so_5::immutable_msg<Msg> or so_5::mutable_msg<Msg> can be used.
Binding	type of binding object. It's expected to be so_5::single_sink_binding_t, so_5::multi_sink_binding_t or a similar type with the same interface.
Transformer	type of transformer functor (a lambda or free function).

Since

v.5.8.1

Parameters

binding	Binding object to be used.
src_mbox	Source mbox. It must not be nullptr.
transformer	Transformer that produced so_5::transformed_message_t instance or std::optional<so_5::transformed_message_t> instance.
delivery_filter	Delivery filter for the source message.

Definition at line 414 of file bind_transformer_helpers.hpp.

bind_transformer() [4/4]

template<typename Binding , typename Transformer , typename Delivery_Filter >

void so_5::bind_transformer	(	Binding &	binding,
		const so_5::mbox_t &	src_mbox,
		Transformer &&	transformer,
		Delivery_Filter &&	filter )

Helper function to add transform_then_redirect msink to a binding object (with a delivery filter).

Type of source message is automatically deduced from the type of transformer argument.

The filter is called first and only if it return true the transformed is called for message transformation.

Usage example:

struct part { ... };
struct compound {
  part m_first;
  part m_second;
};
 
...
so_5::mbox_t src_mbox = ...;
so_5::mbox_t dest_mbox = ...;
 
so_5::single_sink_binding_t binding;
so_5::bind_transformer(binding, src_mbox,
  [dest_mbox](const compound & msg) {
    return so_5::make_transformed<part>(
      dest_mbox, // Destination for the transformed message.
      msg.m_first // Initializer for the new `part` instance.
    );
  },
  [](const compound & msg) { // or [](const auto & msg) {...}
    return ...; // Some predicate.
  });

The transformer is expected to return a so_5::transformed_message_t or std::optional<so_5::transformed_message_t>.

Note

Because the type of the source message is deduced from transformer argument this helper can't be used for transforming mutable messages and signals.

Attention

The transformer can't have an argument in the form of const auto &:

// Compilation error is expected here because the type of
// the transformer argument can't be deduced.
so_5::bind_transformer(binding, src,
  // This would lead to compilation error.
  [](const auto & msg) {...},
  // `const auto &` can be used for a delivery filter.
  [](const auto & msg) {...});

Template Parameters

Binding	type of binding object. It's expected to be so_5::single_sink_binding_t, so_5::multi_sink_binding_t or a similar type with the same interface.
Transformer	type of transformer functor (a lambda or free function).
Delivery_Filter	type of delivery filter functor (a lambda or free function).

Since

v.5.8.1

Parameters

binding	Binding object to be used.
src_mbox	Source mbox. It must not be nullptr.
transformer	Transformer that produced so_5::transformed_message_t instance or std::optional<so_5::transformed_message_t> instance.
filter	Delivery filter for the source message.

Definition at line 188 of file bind_transformer_helpers.hpp.

close_drop_content()

template<typename Exceptions_Control >

void so_5::close_drop_content ( Exceptions_Control exceptions_control, const mchain_t & ch )

inlinenoexcept

Helper function for closing a message chain with dropping all its content.

Usage example.

so_5::mchain_t & ch = ...;
... // Some work with chain.
close_drop_content( so_5::exceptions_enabled, ch );
// Or:
ch->close(
  so_5::exceptions_enabled,
  so_5::mchain_props::close_mode_t::drop_content );

Note

Because of ADL it can be used without specifying namespaces.

Template Parameters

Exceptions_Control

it is expected to be so_5::exceptions_enabled_t or so_5::terminate_if_throws_t. So the first parameter to close_drop_content has to be so_5::exceptions_enabled or so_5::terminate_if_throws.

Since

v.5.7.3

Parameters

exceptions_control	What to do with exceptions. It's expected to be so_5::exceptions_enabled or so_5::terminate_if_throws.
ch	Chain to be closed.

Definition at line 678 of file mchain.hpp.

close_retain_content()

template<typename Exceptions_Control >

void so_5::close_retain_content ( Exceptions_Control exceptions_control, const mchain_t & ch )

inlinenoexcept

Helper function for closing a message chain with retaining all its content.

Note

Because of ADL it can be used without specifying namespaces.

Usage example.

so_5::mchain_t & ch = ...;
... // Some work with chain.
close_retain_content( so_5::exceptions_enabled, ch );
// Or:
ch->close(
  so_5::exceptions_enabled,
  so_5::mchain_props::close_mode_t::retain_content );

Template Parameters

Exceptions_Control

it is expected to be so_5::exceptions_enabled_t or so_5::terminate_if_throws_t. So the first parameter to close_drop_content has to be so_5::exceptions_enabled or so_5::terminate_if_throws.

Since

v.5.7.3

Parameters

exceptions_control	What to do with exceptions. It's expected to be so_5::exceptions_enabled or so_5::terminate_if_throws.
ch	Chain to be closed.

Examples

so_5/mchain_empty_notificator/main.cpp, and so_5/mchain_empty_notificator_2/main.cpp.

Definition at line 720 of file mchain.hpp.

create_child_coop() [1/2]

template<typename... Args>

coop_unique_holder_t so_5::create_child_coop ( agent_t & owner, Args &&... args )

nodiscard

A simple way for creating child cooperation.

Since

v.5.5.3

Usage sample

class owner : public so_5::agent_t
{
public :
  ...
  virtual void
  so_evt_start() override
  {
    auto child = so_5::create_child_coop( *this );
    child->make_agent< worker >();
    ...
    so_environment().register_coop( std::move( child ) );
  }
};

Parameters

owner	Owner of the cooperation.
args	Arguments for the environment_t::make_coop() method.

Examples

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, and so_5/ping_pong_with_owner/main.cpp.

Definition at line 2222 of file environment.hpp.

create_child_coop() [2/2]

template<typename... Args>

coop_unique_holder_t so_5::create_child_coop ( coop_handle_t parent, Args &&... args )

nodiscard

A simple way for creating child cooperation when there is a reference to the parent cooperation object.

Since

v.5.5.8

Usage sample

class parent final : public so_5::agent_t {
  void on_some_event(mhood_t<some_message>) {
    auto child = so_5::create_child_coop(
        // We as the parent coop.
        so_coop(),
        // The default binder for the new coop.
        so_5::disp::one_thread::make_dispatcher(
            so_environment().binder() ) );
    ...
    so_environment().register_coop( std::move(child) );
  }
  ...
};

Parameters

parent	Parent cooperation.
args	Arguments for the environment_t::make_coop() method.

Definition at line 2261 of file environment.hpp.

create_mchain() [1/6]

mchain_t so_5::create_mchain ( environment_t & env )

inline

Create size-unlimited chain.

so_5::environment_t & env = ...;
auto ch = create_mchain( env );
 
// Or as more verbose alternative:
auto ch = env.create_mchain( so_5::make_unlimited_mchain_params() );

Since

v.5.5.16

Examples

so_5/mchain_handler_formats/main.cpp, and so_5/mchain_multi_consumers/main.cpp.

Definition at line 42 of file mchain_helper_functions.hpp.

create_mchain() [2/6]

mchain_t so_5::create_mchain ( environment_t & env, mchain_props::duration_t waiting_time, std::size_t max_size, mchain_props::memory_usage_t memory_usage, mchain_props::overflow_reaction_t overflow_reaction )

inline

Create size-limited chain with waiting on overflow.

so_5::environment_t & env = ...;
auto ch = create_mchain( env,
    // Wait for 150ms.
    std::chrono::milliseconds{150},
    // No more than 200 messages in the chain.
    200,
    // Memory will be allocated dynamically.
    so_5::mchain_props::memory_usage_t::dynamic,
    // New messages will be ignored on chain's overflow.
    so_5::mchain_props::overflow_reaction_t::drop_newest );
 
// Or as more verbose alternative:
auto ch = env.create_mchain( so_5::make_limited_with_waiting_mchain_params(
    // No more than 200 messages in the chain.
    200,
    // Memory will be allocated dynamically.
    so_5::mchain_props::memory_usage_t::dynamic,
    // New messages will be ignored on chain's overflow.
    so_5::mchain_props::overflow_reaction_t::drop_newest,
    // Wait for 150ms.
    std::chrono::milliseconds{150} ) );

Since

v.5.5.16

Parameters

env	Environment for mchain.
waiting_time	Max waiting time in case of overflow.
max_size	Max capacity of mchain.
memory_usage	Type of chain storage.
overflow_reaction	Reaction on chain overflow.

Definition at line 186 of file mchain_helper_functions.hpp.

create_mchain() [3/6]

mchain_t so_5::create_mchain ( environment_t & env, std::size_t max_size, mchain_props::memory_usage_t memory_usage, mchain_props::overflow_reaction_t overflow_reaction )

inline

Create size-limited chain without waiting on overflow.

so_5::environment_t & env = ...;
auto ch = create_mchain( env,
    // No more than 200 messages in the chain.
    200,
    // Memory will be allocated dynamically.
    so_5::mchain_props::memory_usage_t::dynamic,
    // New messages will be ignored on chain's overflow.
    so_5::mchain_props::overflow_reaction_t::drop_newest );
 
// Or as more verbose alternative:
auto ch = env.create_mchain( so_5::make_limited_without_waiting_mchain_params(
    // No more than 200 messages in the chain.
    200,
    // Memory will be allocated dynamically.
    so_5::mchain_props::memory_usage_t::dynamic,
    // New messages will be ignored on chain's overflow.
    so_5::mchain_props::overflow_reaction_t::drop_newest ) );

Since

v.5.5.16

Parameters

env	Environment for mchain.
max_size	Max capacity of mchain.
memory_usage	Type of chain storage.
overflow_reaction	Reaction on chain overflow.

Definition at line 94 of file mchain_helper_functions.hpp.

create_mchain() [4/6]

mchain_t so_5::create_mchain ( wrapped_env_t & sobj )

inline

Create size-unlimited chain.

wrapped_env_t sobj;
auto ch = create_mchain( sobj );
 
// Or as more verbose alternative:
auto ch = sobj.environment().create_mchain( make_unlimited_mchain_params() );

Since

v.5.5.16

Definition at line 62 of file mchain_helper_functions.hpp.

create_mchain() [5/6]

mchain_t so_5::create_mchain ( wrapped_env_t & sobj, mchain_props::duration_t waiting_time, std::size_t max_size, mchain_props::memory_usage_t memory_usage, mchain_props::overflow_reaction_t overflow_reaction )

inline

Create size-limited chain without waiting on overflow.

so_5::wrapped_env_t sobj;
auto ch = create_mchain( sobj,
    // Wait for 150ms.
    std::chrono::milliseconds{150},
    // No more than 200 messages in the chain.
    200,
    // Memory will be allocated dynamically.
    so_5::mchain_props::memory_usage_t::dynamic,
    // New messages will be ignored on chain's overflow.
    so_5::mchain_props::overflow_reaction_t::drop_newest );
 
// Or as more verbose alternative:
auto ch = sobj.environment().create_mchain(
    so_5::make_limited_with_waiting_mchain_params(
      // No more than 200 messages in the chain.
      200,
      // Memory will be allocated dynamically.
      so_5::mchain_props::memory_usage_t::dynamic,
      // New messages will be ignored on chain's overflow.
      so_5::mchain_props::overflow_reaction_t::drop_newest,
      // Wait for 150ms.
      std::chrono::milliseconds{150} ) );

Since

v.5.5.16

Parameters

sobj	Environment for mchain.
waiting_time	Max waiting time in case of overflow.
max_size	Max capacity of mchain.
memory_usage	Type of chain storage.
overflow_reaction	Reaction on chain overflow.

Definition at line 235 of file mchain_helper_functions.hpp.

create_mchain() [6/6]

mchain_t so_5::create_mchain ( wrapped_env_t & sobj, std::size_t max_size, mchain_props::memory_usage_t memory_usage, mchain_props::overflow_reaction_t overflow_reaction )

inline

Create size-limited chain without waiting on overflow.

so_5::wrapped_env_t sobj;
auto ch = create_mchain( sobj,
    // No more than 200 messages in the chain.
    200,
    // Memory will be allocated dynamically.
    so_5::mchain_props::memory_usage_t::dynamic,
    // New messages will be ignored on chain's overflow.
    so_5::mchain_props::overflow_reaction_t::drop_newest );
 
// Or as more verbose alternative:
auto ch = sobj.environment().create_mchain(
    so_5::make_limited_without_waiting_mchain_params(
      // No more than 200 messages in the chain.
      200,
      // Memory will be allocated dynamically.
      so_5::mchain_props::memory_usage_t::dynamic,
      // New messages will be ignored on chain's overflow.
      so_5::mchain_props::overflow_reaction_t::drop_newest ) );

Since

v.5.5.16

Parameters

sobj	Environment for mchain.
max_size	Max capacity of mchain.
memory_usage	Type of chain storage.
overflow_reaction	Reaction on chain overflow.

Definition at line 137 of file mchain_helper_functions.hpp.

create_std_event_exception_logger()

SO_5_FUNC event_exception_logger_unique_ptr_t so_5::create_std_event_exception_logger

(

)

Create the default exception logger.

Definition at line 58 of file event_exception_logger.cpp.

create_stderr_logger()

SO_5_FUNC error_logger_shptr_t so_5::create_stderr_logger

(

)

A factory for creating error_logger implemenation which uses std::stderr as log stream.

Since

v.5.5.0

Definition at line 96 of file error_logger.cpp.

create_timer_heap_manager() [1/2]

SO_5_FUNC timer_manager_unique_ptr_t so_5::create_timer_heap_manager	(	error_logger_shptr_t	logger,
		outliving_reference_t< timer_manager_t::elapsed_timers_collector_t >	collector )

Create timer manager based on timer_heap mechanism.

Since

v.5.5.0

Note

Default parameters will be used for timer manager.

Parameters

logger	A logger for handling error messages inside timer_manager.
collector	A collector for elapsed timers.

Definition at line 604 of file timers.cpp.

create_timer_heap_manager() [2/2]

SO_5_FUNC timer_manager_unique_ptr_t so_5::create_timer_heap_manager	(	error_logger_shptr_t	logger,
		outliving_reference_t< timer_manager_t::elapsed_timers_collector_t >	collector,
		std::size_t	initial_heap_capacity )

Create timer manager based on timer_heap mechanism.

Since

v.5.5.0

Note

Parameters must be specified explicitely.

Parameters

logger	A logger for handling error messages inside timer_manager.
collector	A collector for elapsed timers.
initial_heap_capacity	Initical capacity of heap array.

Definition at line 618 of file timers.cpp.

create_timer_heap_thread() [1/2]

SO_5_FUNC timer_thread_unique_ptr_t so_5::create_timer_heap_thread

(

error_logger_shptr_t

logger

)

Create timer thread based on timer_heap mechanism.

Since

v.5.5.0

Note

Default parameters will be used for timer thread.

Parameters

logger

A logger for handling error messages inside timer_thread.

Definition at line 522 of file timers.cpp.

create_timer_heap_thread() [2/2]

SO_5_FUNC timer_thread_unique_ptr_t so_5::create_timer_heap_thread	(	error_logger_shptr_t	logger,
		std::size_t	initial_heap_capacity )

Create timer thread based on timer_heap mechanism.

Since

v.5.5.0

Note

Parameters must be specified explicitely.

Parameters

logger	A logger for handling error messages inside timer_thread.
initial_heap_capacity	Initical capacity of heap array.

Definition at line 533 of file timers.cpp.

create_timer_list_manager()

SO_5_FUNC timer_manager_unique_ptr_t so_5::create_timer_list_manager	(	error_logger_shptr_t	logger,
		outliving_reference_t< timer_manager_t::elapsed_timers_collector_t >	collector )

Create timer thread based on timer_list mechanism.

Since

v.5.5.0

Parameters

logger	A logger for handling error messages inside timer_manager.
collector	A collector for elapsed timers.

Definition at line 638 of file timers.cpp.

create_timer_list_thread()

SO_5_FUNC timer_thread_unique_ptr_t so_5::create_timer_list_thread

(

error_logger_shptr_t

logger

)

Create timer thread based on timer_list mechanism.

Since

v.5.5.0

Parameters

logger

A logger for handling error messages inside timer_thread.

Definition at line 551 of file timers.cpp.

create_timer_wheel_manager() [1/2]

SO_5_FUNC timer_manager_unique_ptr_t so_5::create_timer_wheel_manager	(	error_logger_shptr_t	logger,
		outliving_reference_t< timer_manager_t::elapsed_timers_collector_t >	collector )

Create timer manager based on timer_wheel mechanism.

Note

Default parameters will be used for timer manager.

Since

v.5.5.19

Parameters

logger	A logger for handling error messages inside timer_manager.
collector	A collector for elapsed timers.

Definition at line 567 of file timers.cpp.

create_timer_wheel_manager() [2/2]

SO_5_FUNC timer_manager_unique_ptr_t so_5::create_timer_wheel_manager	(	error_logger_shptr_t	logger,
		outliving_reference_t< timer_manager_t::elapsed_timers_collector_t >	collector,
		unsigned int	wheel_size,
		std::chrono::steady_clock::duration	granuality )

Create timer manager based on timer_wheel mechanism.

Since

v.5.5.0

Note

Parameters must be specified explicitely.

Parameters

logger	A logger for handling error messages inside timer_manager.
collector	A collector for elapsed timers.
wheel_size	Size of the wheel.
granuality	A size of one time step for the wheel.

Definition at line 582 of file timers.cpp.

create_timer_wheel_thread() [1/2]

SO_5_FUNC timer_thread_unique_ptr_t so_5::create_timer_wheel_thread

(

error_logger_shptr_t

logger

)

Create timer thread based on timer_wheel mechanism.

Since

v.5.5.0

Note

Default parameters will be used for timer thread.

Parameters

logger

A logger for handling error messages inside timer_thread.

Definition at line 490 of file timers.cpp.

create_timer_wheel_thread() [2/2]

SO_5_FUNC timer_thread_unique_ptr_t so_5::create_timer_wheel_thread	(	error_logger_shptr_t	logger,
		unsigned int	wheel_size,
		std::chrono::steady_clock::duration	granuality )

Create timer thread based on timer_wheel mechanism.

Since

v.5.5.0

Note

Parameters must be specified explicitely.

Parameters

logger	A logger for handling error messages inside timer_thread.
wheel_size	Size of the wheel.
granuality	A size of one time step for the wheel.

Definition at line 502 of file timers.cpp.

default_subscription_storage_factory()

SO_5_FUNC subscription_storage_factory_t so_5::default_subscription_storage_factory ( )

nodiscard

Factory for default subscription storage object.

Note

Creates adaptive storage with vector-based storage for small amount of subscriptions and map-based storage for large amount of subscriptions.

More about subscription storage tuning

See so-5.5.3: Subscription storage type selection for more details about selection of appropriate subscription storage type.

Since

v.5.5.3

Definition at line 291 of file subscr_storage_adaptive.cpp.

ensure_classical_message()

template<typename Msg >

void so_5::ensure_classical_message

(

)

A special compile-time checker to guarantee that Msg is derived from message_t.

Template Parameters

Msg	type to be checked.

Since

v.5.5.9

Definition at line 607 of file message.hpp.

ensure_message_with_actual_data()

template<class Msg >

void so_5::ensure_message_with_actual_data

(

const Msg *

m

)

A special checker to guarantee that the message is an instance of the message_t (not signal_t) and has a not-null pointer to the message data.

Note

A check for the inheritance from the message_t is done at compile-time.

Template Parameters

Msg	message type to be checked.

Since

v.5.2.0

Definition at line 539 of file message.hpp.

ensure_not_mutable_signal()

template<class S >

void so_5::ensure_not_mutable_signal

(

)

A special compile-time checker to guarantee that S is not a mutable signal.

This check is intended to prevent usage of mutable_msg where S is a signal type.

Since

v.5.5.19

Definition at line 563 of file message.hpp.

ensure_not_signal()

template<class Msg >

void so_5::ensure_not_signal

(

)

A special compile-time checker to guarantee that the message class is not a signal class.

Since

v.5.2.0

Definition at line 517 of file message.hpp.

ensure_signal()

template<class Msg >

void so_5::ensure_signal

(

)

A special compile-time checker to guarantee that the Msg is derived from the signal_t.

Template Parameters

Msg	signal type to be checked.

Since

v.5.2.0

Definition at line 584 of file message.hpp.

flat_set_based_subscription_storage_factory()

SO_5_FUNC subscription_storage_factory_t so_5::flat_set_based_subscription_storage_factory ( std::size_t initial_capacity )

nodiscard

Factory for subscription storage based on sorted std::vector.

The capacity of the storage is not fixed, the underlaying vector will grow as needed (note that the current implementation never shrinks it down).

Note

Uses very simple working scheme: all subscriptions are stored in a sorted vector (aka "flat_set") and binary search is used for seaching and manipulating of subscriptions.

Since

v.5.8.2

Parameters

initial_capacity

Initial storage capacity.

Definition at line 526 of file subscr_storage_flat_set_based.cpp.

from()

mchain_receive_params_t< mchain_props::msg_count_status_t::undefined > so_5::from ( mchain_t chain )

inline

A helper function for simplification of creation of mchain_receive_params instance.

Attention

Since v.5.6.0 at least handle_all(), handle_n() or extract_n() should be called before passing result of from() to receive() function.

Usage examples:

so_5::mchain_t chain = env.create_mchain(...);
 
// Receive and handle 3 messages.
// If there is no 3 messages in the mchain the receive will wait infinitely.
// A return from receive will be after handling of 3 messages or
// if the mchain is closed explicitely.
receive( from(chain).handle_n( 3 ),
    handlers... );
 
// Receive and handle 3 messages.
// If there is no 3 messages in the mchain the receive will wait
// no more that 200ms.
// A return from receive will be after handling of 3 messages or
// if the mchain is closed explicitely, or if there is no messages
// for more than 200ms.
receive( from(chain).handle_n( 3 ).empty_timeout( milliseconds(200) ),
    handlers... );
 
// Receive all messages from the chain.
// If there is no message in the chain then wait no more than 500ms.
// A return from receive will be after explicit close of the chain
// or if there is no messages for more than 500ms.
receive( from(chain).handle_all().empty_timeout( milliseconds(500) ),
    handlers... );
 
// Receve any number of messages from the chain but do waiting and
// handling for no more than 2s.
receive( from(chain).handle_all().total_time( seconds(2) ),
    handlers... );
 
// Receve 1000 messages from the chain but do waiting and
// handling for no more than 2s.
receive( from(chain).extract_n( 1000 ).total_time( seconds(2) ),
    handlers... );

Since

v.5.5.13

Examples

so_5/mchain_empty_notificator/main.cpp, so_5/mchain_empty_notificator_2/main.cpp, and so_5/producer_consumer_mchain/main.cpp.

Definition at line 1595 of file mchain.hpp.

from_all()

mchain_select_params_t< mchain_props::msg_count_status_t::undefined > so_5::from_all ( )

inline

Helper function for creation of mchain_select_params instance with default values.

Attention

Since v.5.6.0 at least handle_all(), handle_n() or extract_n() should be called before passing result of from_all() to select() or prepare_select() functions.

Usage example:

select( so_5::from_all().handle_n(3).empty_timeout(3s), ... );

Examples

so_5/mchain_empty_notificator_2/main.cpp, and so_5/mchain_select/main.cpp.

Definition at line 214 of file mchain_select.hpp.

get()

template<std::size_t Index>

auto so_5::get

(

const mchain_receive_result_t &

result

)

part of tuple protocol for mchain_receive_result_t.

Since

v.5.8.5

Examples

so_5/named_dispatchers_layer/main.cpp.

Definition at line 1014 of file mchain.hpp.

hash_table_based_subscription_storage_factory()

SO_5_FUNC subscription_storage_factory_t so_5::hash_table_based_subscription_storage_factory ( )

nodiscard

Factory for default subscription storage based on std::unordered_map.

Note

This storage is efficient only in the cases of very large amount of subscriptions (from several hundreds to thousands). For smaller amounts map-based and vector-based storages are more appropriate.

More about subscription storage tuning

See so-5.5.3: Subscription storage type selection for more details about selection of appropriate subscription storage type.

Since

v.5.5.3

Definition at line 544 of file subscr_storage_hash_table_based.cpp.

introduce_child_coop() [1/2]

template<typename... Args>

decltype(auto) so_5::introduce_child_coop	(	agent_t &	owner,
		Args &&...	args )

A simple way for creating and registering child cooperation.

Since

v.5.5.5

Usage sample

class owner : public so_5::agent_t
{
public :
  ...
  virtual void
  so_evt_start() override
  {
    so_5::introduce_child_coop( *this, []( so_5::coop_t & coop ) {
      coop.make_agent< worker >();
    } );
  }
};

Note

This function is just a tiny wrapper around so_5::environment_t::introduce_coop() helper method. For more examples with usage of introduce_coop() please see description of that method.

Parameters

owner	Owner of the cooperation.
args	Arguments for the environment_t::introduce_coop() method.

Examples

so_5/child_soenv/main.cpp, so_5/coop_notification/main.cpp, so_5/coop_user_resources/main.cpp, so_5/dispatcher_for_children/main.cpp, so_5/dispatcher_for_children_2/main.cpp, so_5/individual_msg_tracing/main.cpp, so_5/named_dispatchers_layer/main.cpp, so_5/parent_coop/main.cpp, so_5/prio_work_stealing/main.cpp, so_5/selective_msg_tracing/main.cpp, and so_5/wrapped_env_demo_2/main.cpp.

Definition at line 2300 of file environment.hpp.

introduce_child_coop() [2/2]

template<typename... Args>

decltype(auto) so_5::introduce_child_coop	(	coop_handle_t	parent,
		Args &&...	args )

A simple way for creating and registering child cooperation when there is a reference to parent coop.

Since

v.5.5.8

Usage sample

class owner : public so_5::agent_t
{
public :
  ...
  virtual void
  so_evt_start() override
  {
    so_5::introduce_child_coop( so_coop(), []( so_5::coop_t & coop ) {
      coop.make_agent< worker >();
    } );
  }
};

Note

This function is just a tiny wrapper around so_5::environment_t::introduce_coop() helper method. For more examples with usage of introduce_coop() please see description of that method.

Parameters

parent	Parent cooperation.
args	Arguments for the environment_t::introduce_coop() method.

Definition at line 2341 of file environment.hpp.

intrusive_ptr_t()

template<typename T >

so_5::intrusive_ptr_t

(

std::unique_ptr< T >

)

-> intrusive_ptr_t< T >

Deduction rule for C++17 compiler.

Since

v.5.6.0

launch() [1/2]

template<typename Init_Routine >

void so_5::launch

(

Init_Routine &&

init_routine

)

Launch a SObjectizer Environment with default parameters.

Example with free function as initializer:

void init( so_5::environment_t & env )
{
  env.register_agent_as_coop( "main_coop", new my_agent_t( env ) );
}
 
int main()
{
  so_5::launch( &init );
 
  return 0;
}

Example with lambda-function as initializer:

int main()
{
  so_5::launch( []( so_5::environment_t & env )
    {
      env.register_agent_as_coop( "main_coop", new my_agent_t( env ) );
    } );
 
  return 0;
}

Example with object method as initializer:

class application_t
{
public :
  void
  init( so_5::environment_t & env )
  {
    env.register_agent_as_coop( "main_coop", new my_agent_t( env ) );
  }
  ...
};
 
int main()
{
  using namespace std;
  using namespace std::placeholders;
 
  application_t app;
 
  so_5::launch( bind( &application_t::init, &app, _1 ) );
 
  return 0;
}

Template Parameters

Init_Routine

Type of initialization routine. It can be a pointer to function or functional object that accepts a reference to so_5::environment_t.

Parameters

init_routine

Initialization routine.

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/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/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 142 of file api.hpp.

launch() [2/2]

template<typename Init_Routine , typename Params_Tuner >

void so_5::launch ( Init_Routine && init_routine, Params_Tuner && params_tuner )

inline

Launch a SObjectizer Environment with explicitely specified parameters.

Example with free functions as initializers:

void init( so_5::environment_t & env )
{
  env.register_agent_as_coop(
      "main_coop",
      new my_agent_t( env ),
      so_5::disp::active_obj::create_disp_binder( "active_obj" ) );
}
 
void params_setter( so_5::environment_params_t & params )
{
  params.disable_autoshutdown();
}
 
int main()
{
  so_5::launch( &init, &params_setter );
 
  return 0;
}

Example with lambda-functions as initializers:

int main()
{
  so_5::launch(
    []( so_5::environment_t & env )
    {
      env.register_agent_as_coop(
          "main_coop",
          new my_agent_t( env ),
          so_5::disp::active_obj::create_disp_binder( "active_obj" ) );
    },
    []( so_5::environment_params_t & params )
    {
      params.disable_autoshutdown();
    } );
 
  return 0;
}

Template Parameters

Init_Routine	Type of initialization routine. It can be a pointer to function or functional object that accepts a reference to so_5::environment_t.
Params_Tuner	Type of routine for tuning environment's parameters. It can be a pointer to function or functional object that accepts a reference to so_5::environment_params_t.

Parameters

init_routine	Initialization routine.
params_tuner	Parameters setting routine.

Definition at line 212 of file api.hpp.

make_agent_ref()

template<typename Derived >

intrusive_ptr_t< Derived > so_5::make_agent_ref ( Derived * agent )

nodiscard

Helper function template for the creation of smart pointer to an agent.

This function can be useful if a pointer to an agent should be passed somewhere with the guarantee that this pointer will remain valid even if the agent will be deregistered.

This could be necessary, for example, if a pointer to an agent is passed to some callback (like it is done in Asio):

void my_agent::on_some_event(mhood_t<some_msg> cmd) {
  connection_.async_read_some(input_buffer_,
    [self = so_5::make_agent_ref(this)](
      const asio::error_code & ec,
      std::size_t bytes_transferred )
    {
      if(!ec)
        self->handle_incoming_data(bytes_transferred);
    }
  );
}

Since

v.5.7.1

Examples

so_5/make_agent_ref/main.cpp.

Definition at line 3567 of file agent.hpp.

make_coop_dereg_notificator()

auto so_5::make_coop_dereg_notificator ( mbox_t target )

inlinenoexcept

Create notificator about cooperation deregistration completion.

Since

v.5.2.3

Attention

Since v.5.6.0 dereg_notificators should be noexcept functions/functors. But this notificator uses so_5::send() function inside. This function can throw (for example std::bad_alloc can be raised if there is no enough memory available). It means that if so_5::send() throws inside this notificator the whole application will be aborted via std::terminate().

Parameters

target

A mbox to which msg_coop_deregistered will be sent.

Examples

so_5/coop_notification/main.cpp, and so_5/dispatcher_restarts/main.cpp.

Definition at line 140 of file agent_coop_notifications.hpp.

make_coop_reg_notificator()

auto so_5::make_coop_reg_notificator ( mbox_t target )

inlinenoexcept

Create notificator about cooperation registration completion.

Since

v.5.2.3

Attention

Since v.5.6.0 reg_notificators should be noexcept functions/functors. But this notificator uses so_5::send() function inside. This function can throw (for example std::bad_alloc can be raised if there is no enough memory available). It means that if so_5::send() throws inside this notificator the whole application will be aborted via std::terminate().

Parameters

target

A mbox to which msg_coop_registered will be sent.

Examples

so_5/coop_notification/main.cpp.

Definition at line 98 of file agent_coop_notifications.hpp.

make_default_disp_binder()

disp_binder_shptr_t so_5::make_default_disp_binder ( environment_t & env )

inline

Create an instance of the default dispatcher binder.

Note

This function takes into account a possibility to have different types of environment infrastructures (introduced in v.5.5.19) and creates a default dispatcher binder with respect to the actual environment infrastructure type.

Usage example:

so_5::launch( [](so_5::environment_t & env) {
  env.introduce_coop(
    // Agents from that coop will be bound to the default dispatcher.
    so_5::make_default_disp_binder(env),
    [](so_5::coop_t & coop) {
      coop.make_agent<...>(...);
    } );
} );

Since

v.5.5.19

Examples

so_5/ping_pong/main.cpp, so_5/producer_consumer_mchain/main.cpp, and so_5/selective_msg_tracing/main.cpp.

Definition at line 2379 of file environment.hpp.

make_defaults_manager_for_combined_locks()

SO_5_FUNC queue_locks_defaults_manager_unique_ptr_t so_5::make_defaults_manager_for_combined_locks

(

)

A factory for queue_locks_defaults_manager with generators for combined locks.

Since

v.5.5.18

Definition at line 76 of file queue_locks_defaults_manager.cpp.

make_defaults_manager_for_simple_locks()

SO_5_FUNC queue_locks_defaults_manager_unique_ptr_t so_5::make_defaults_manager_for_simple_locks

(

)

A factory for queue_locks_defaults_manager with generators for simple locks.

Since

v.5.5.18

Definition at line 67 of file queue_locks_defaults_manager.cpp.

make_empty_event_queue_hook_unique_ptr()

event_queue_hook_unique_ptr_t so_5::make_empty_event_queue_hook_unique_ptr ( )

inlinenodiscard

Helper function for creation of empty unique_ptr for event_queue_hook.

This function allows to write:

auto hook = so_5::make_empty_event_queue_hook_unique_ptr();

instead of

so_5::event_queue_hook_unique_ptr_t hook{nullptr, so_5::event_queue_hook_t::default_deleter};

Since

v.5.5.24

Definition at line 218 of file event_queue_hook.hpp.

make_event_queue_hook()

template<typename Hook_Type , typename... Args>

event_queue_hook_unique_ptr_t so_5::make_event_queue_hook	(	event_queue_hook_deleter_fnptr_t	deleter,
		Args &&...	args )

Helper function for simplify creation of event_queue_hook object.

This helper function allows to write:

auto hook = so_5::make_event_queue_hook<my_hook>(
  so_5::event_queue_hook_t::default_deleter,
  ...); // Some arguments for my_hook's constructor.

instead of:

so_5::event_queue_hook_unique_ptr_t hook{
  new my_hook{...}, // Some arguments for my_hook's constructor.
  so_5::event_queue_hook_t::default_deleter };

Since

v.5.5.24

Definition at line 191 of file event_queue_hook.hpp.

make_extensible_select()

template<mchain_props::msg_count_status_t Msg_Count_Status, typename... Cases>

extensible_select_t so_5::make_extensible_select ( mchain_select_params_t< Msg_Count_Status > params, Cases &&... cases )

nodiscard

Creation of extensible-select instance.

This function creates an instance of extensible-select object that can be used for subsequent calls to add_select_cases() and select().

Usage examples:

// Creation of extensible-select instance with initial set of cases.
auto sel = so_5::make_extensible_select(
  so_5::from_all().handle_n(10),
  receive_case(ch1, ...),
  receive_case(ch2, ...));
 
// Creation of extensible-select instance without initial set of cases.
auto sel2 = so_5::make_extensible_select(
  so_5::from_all().handle_n(20));
// Cases should be added later.
so_5::add_select_cases(sel2, receive_case(ch1, ...));
so_5::add_select_cases(sel2,
  receive_case(ch2, ...),
  receive_case(ch3, ...));

Note

Since v.5.8.4 the value of empty_timeout (or no_wait_on_empty) is taken into account when total_time is specified. It means that in the following example the select() returns immediately if all mchains are empty:

// Creation of extensible-select instance with initial set of cases.
auto sel = so_5::make_extensible_select(
  so_5::from_all().handle_n(10).no_wait_on_empty().total_time(6s),
  receive_case(ch1, ...),
  receive_case(ch2, ...));
...
so_5::add_select_cases(sel, ...);
...
auto r = select(sel);

Since

v.5.6.1

Parameters

params	Parameters for advanced select.
cases	Select cases.

Definition at line 2112 of file mchain_select.hpp.

make_limited_with_waiting_mchain_params()

mchain_params_t so_5::make_limited_with_waiting_mchain_params ( std::size_t max_size, mchain_props::memory_usage_t memory_usage, mchain_props::overflow_reaction_t overflow_reaction, mchain_props::duration_t wait_timeout )

inline

Create parameters for size-limited mchain with waiting on overflow.

Usage example:

so_5::environment_t & env = ...;
auto chain = env.create_mchain( so_5::make_limited_with_waiting_mchain_params(
    // No more than 200 messages in the chain.
    200,
    // Memory will be preallocated.
    so_5::mchain_props::memory_usage_t::preallocated,
    // New messages will be ignored on chain's overflow.
    so_5::mchain_props::overflow_reaction_t::drop_newest,
    // But before dropping a new message there will be 500ms timeout
    std::chrono::milliseconds(500) ) );

Note

Since v.5.5.18 there is an important difference in mchain behavior. If an ordinary send is used for message pushing then there will be waiting for free space if the message chain is full. But if message push is performed from timer thread (it means that message is a delayed or a periodic message) then there will not be any waiting. It is because the context of timer thread is very special: there is no possibility to spend some time on waiting for some free space in message chain. All operations on the context of timer thread must be done as fast as possible.

Since

v.5.5.13

Parameters

max_size	Max size of the chain.
memory_usage	Type of chain storage.
overflow_reaction	Reaction on chain overflow.
wait_timeout	Waiting time on full message chain.

Examples

so_5/producer_consumer_mchain/main.cpp.

Definition at line 930 of file mchain.hpp.

make_limited_without_waiting_mchain_params()

mchain_params_t so_5::make_limited_without_waiting_mchain_params ( std::size_t max_size, mchain_props::memory_usage_t memory_usage, mchain_props::overflow_reaction_t overflow_reaction )

inline

Create parameters for size-limited mchain without waiting on overflow.

Usage example:

so_5::environment_t & env = ...;
auto chain = env.create_mchain( so_5::make_limited_without_waiting_mchain_params(
    // No more than 200 messages in the chain.
    200,
    // Memory will be allocated dynamically.
    so_5::mchain_props::memory_usage_t::dynamic,
    // New messages will be ignored on chain's overflow.
    so_5::mchain_props::overflow_reaction_t::drop_newest ) );

Since

v.5.5.13

Parameters

max_size	Max capacity of mchain.
memory_usage	Type of chain storage.
overflow_reaction	Reaction on chain overflow.

Examples

so_5/mchain_empty_notificator/main.cpp, and so_5/mchain_empty_notificator_2/main.cpp.

Definition at line 883 of file mchain.hpp.

make_transformed() [1/2]

template<typename Msg , typename... Args>

transformed_message_t< Msg > so_5::make_transformed ( mbox_t mbox, Args &&... args )

nodiscard

Helper function for creation of an instance of transformed_message_t.

It's just a simple way of calling transformed_message_t<Msg>::make().

Usage example:

// For a case of messages.
struct my_source_msg { ... };
struct my_result_msg { ... };
 
so_5::bind_transformer< my_source_msg >(binding, src_mbox,
  [dest_mbox](const auto & msg) {
    // We can make a mutable message.
    return so_5::make_transformed< so_5::mutable_msg< my_result_msg > >(
        dest_mbox, // The first parameter is the destination mbox.
        ... // Remaining parameters will be forwarded to
            // the so_5::transformed_message_t< so_5::mutable_msg<my_result_msg> > constructor.
      );
  });
 
// For a case of signals.
struct my_source_sig { ... };
struct my_result_sig { ... };
 
so_5::bind_transformer< my_source_sig >(binding, src_mbox,
  [dest_mbox]() { // NOTE: no args for transformer lambda!
    return so_5::make_transformed< my_result_sig >(
        dest_mbox // The first parameter is the destination mbox.
        // No more parameters for a signal.
      );
  });

Template Parameters

Msg	type of the transformed (result) message.
Args	type of arguments to be passed to the transformed_message_t<Msg>::make(). If Msg is a signal type then Args has to be an empty type list.

Parameters

mbox	The destination mbox.
args	Parameters to be used for constructing an instance of Msg type. This can be an empty parameters list.

Examples

so_5/bind_transformer/main.cpp.

Definition at line 222 of file transformed_message.hpp.

make_transformed() [2/2]

template<typename Msg , message_ownership_t Ownership>

transformed_message_t< Msg > so_5::make_transformed ( mbox_t mbox, message_holder_t< Msg, Ownership > msg_holder )

nodiscard

Helper function for creation of an instance of transformed_message_t.

It's just a simple way of calling transformed_message_t<Msg>::make().

Note

This function has to be used when the result message is represented as so_5::message_holder_t.

Usage example:

// For a case of messages.
struct my_source_msg { ... };
struct my_result_msg { ... };
 
so_5::bind_transformer< my_source_msg >(binding, src_mbox,
  [dest_mbox](const auto & msg) {
    // We can make a mutable message.
    auto result = so_5::message_holder_t< so_5::mutable_msg<my_result_msg> >::make(
      ... // Parameters to be used for my_result_msg construction.
      );
    return so_5::make_transformed(
        dest_mbox, // The first parameter is the destination mbox.
        std::move(result) // The transformed message.
      );
  });

Attention

This function can't be used for signals because signals are not supported by so_5::message_holder_t.

Template Parameters

Msg	type of the transformed (result) message.
Ownership	ownership of message instance in msg_holder (see so_5::message_ownership_t for more details).

Parameters

mbox	The destination mbox.
msg_holder	Already constructed message. It is expected that msg_holder isn't an empty holder.

Definition at line 276 of file transformed_message.hpp.

make_unique_subscribers_mbox()

template<typename Lock_Type = std::mutex>

mbox_t so_5::make_unique_subscribers_mbox ( so_5::environment_t & env )

nodiscard

Factory function for creation of a new instance of unique_subscribers mbox.

Usage examples:

Create a mbox with std::mutex as Lock_Type (this mbox can safely be used in multi-threaded environments):

so_5::environment_t & env = ...;
auto mbox = so_5::make_unique_subscribers_mbox(env);

Create a mbox with so_5::null_mutex_t as Lock_Type (this mbox can only be used in single-threaded environments):

so_5::environment_t & env = ...;
auto mbox = so_5::make_unique_subscribers_mbox<so_5::null_mutex_t>(env);

Template Parameters

Lock_Type

type of lock to be used for thread safety. It can be std::mutex or so_5::null_mutex_t (or any other type which can be used with std::lock_quard).

Since

v.5.8.0

Examples

so_5/introduce_named_mbox/main.cpp, and so_5/unique_subscribers_mbox/main.cpp.

Definition at line 368 of file unique_subscribers_mbox.hpp.

make_unlimited_mchain_params()

mchain_params_t so_5::make_unlimited_mchain_params ( )

inline

Create parameters for size-unlimited mchain.

Usage example:

so_5::environment_t & env = ...;
auto chain = env.create_mchain( so_5::make_unlimited_mchain_params() );

Since

v.5.5.13

Definition at line 860 of file mchain.hpp.

map_based_subscription_storage_factory()

SO_5_FUNC subscription_storage_factory_t so_5::map_based_subscription_storage_factory ( )

nodiscard

Factory for subscription storage based on std::map.

Note

Uses std::map as an underlying storage. And very efficient when count of subscription in measured in dozens. For very large amount of subscriptions the hash-table-based storage is more efficient.

More about subscription storage tuning

See so-5.5.3: Subscription storage type selection for more details about selection of appropriate subscription storage type.

Since

v.5.5.3

Definition at line 480 of file subscr_storage_map_based.cpp.

null_current_thread_id()

current_thread_id_t so_5::null_current_thread_id ( )

inline

Get NULL thread id.

Definition at line 37 of file current_thread_id.hpp.

null_mbox_id()

mbox_id_t so_5::null_mbox_id ( )

inline

Default value for null mbox_id.

Since

v.5.5.4.1

Definition at line 39 of file types.hpp.

operator+() [1/11]

agent_context_t so_5::operator+ ( agent_context_t ctx, custom_direct_mbox_factory_t factory )

inline

Definition at line 188 of file agent_context.hpp.

operator+() [2/11]

agent_context_t so_5::operator+ ( agent_context_t ctx, demands_handling_on_dereg_t handling_mode )

inline

Definition at line 206 of file agent_context.hpp.

operator+() [3/11]

template<class M >

agent_context_t so_5::operator+	(	agent_context_t	ctx,
		message_limit::abort_app_indicator_t< M >	limit )

Definition at line 140 of file agent_context.hpp.

operator+() [4/11]

template<class M >

agent_context_t so_5::operator+	(	agent_context_t	ctx,
		message_limit::drop_indicator_t< M >	limit )

Definition at line 130 of file agent_context.hpp.

operator+() [5/11]

template<class M , class L >

agent_context_t so_5::operator+	(	agent_context_t	ctx,
		message_limit::log_then_abort_app_indicator_t< M, L >	limit )

Definition at line 150 of file agent_context.hpp.

operator+() [6/11]

template<class M , class L >

agent_context_t so_5::operator+	(	agent_context_t	ctx,
		message_limit::redirect_indicator_t< M, L >	limit )

Definition at line 160 of file agent_context.hpp.

operator+() [7/11]

template<class M >

agent_context_t so_5::operator+	(	agent_context_t	ctx,
		message_limit::transform_indicator_t< M >	limit )

Definition at line 170 of file agent_context.hpp.

operator+() [8/11]

agent_context_t so_5::operator+ ( agent_context_t ctx, name_for_agent_t agent_name )

inline

Definition at line 197 of file agent_context.hpp.

operator+() [9/11]

agent_context_t so_5::operator+ ( agent_context_t ctx, so_5::priority_t agent_priority )

inline

Definition at line 179 of file agent_context.hpp.

operator+() [10/11]

agent_context_t so_5::operator+ ( agent_context_t ctx, subscription_storage_factory_t factory )

inline

Definition at line 120 of file agent_context.hpp.

operator+() [11/11]

template<typename Option >

agent_context_t so_5::operator+	(	environment_t &	env,
		Option	arg )

A plus operator for creating agent_context object from a reference to Environment and single agent tuning option.

Since

v.5.5.4

Definition at line 109 of file agent_context.hpp.

operator>>=()

void so_5::operator>>= ( agent_t * agent, const state_t & new_state )

inline

A shortcat for switching the agent state.

Usage example.

class my_agent : public so_5::agent_t
{
  const so_5::state_t st_normal = so_make_state();
  const so_5::state_t st_error = so_make_state();
  ...
public :
  virtual void so_define_agent() override
  {
    this >>= st_normal;
 
    st_normal.handle( [=]( const msg_failure & evt ) {
      this >>= st_error;
      ...
    });
    ...
  };
  ...
};

Since

v.5.5.1

Definition at line 4120 of file agent.hpp.

outliving_const() [1/2]

template<typename T >

outliving_reference_t< const T > so_5::outliving_const

(

outliving_reference_t< T >

r

)

Make outliving_reference wrapper for const reference.

See also

outliving_reference_t

Since

v.5.5.22

Definition at line 155 of file outliving.hpp.

outliving_const() [2/2]

template<typename T >

outliving_reference_t< const T > so_5::outliving_const

(

T const &

r

)

Make outliving_reference wrapper for const reference.

See also

outliving_reference_t

Since

v.5.5.19

Definition at line 143 of file outliving.hpp.

outliving_mutable()

template<typename T >

outliving_reference_t< T > so_5::outliving_mutable

(

T &

r

)

Make outliving_reference wrapper for mutable reference.

See also

outliving_reference_t

Since

v.5.5.19

Definition at line 131 of file outliving.hpp.

prepare_receive()

template<mchain_props::msg_count_status_t Msg_Count_Status, typename... Handlers>

prepared_receive_t< sizeof...(Handlers) > so_5::prepare_receive	(	const mchain_receive_params_t< Msg_Count_Status > &	params,
		Handlers &&...	handlers )

Create parameters for receive function to be used later.

Attention

Since v.5.6.0 at least handle_all(), handle_n() or extract_n() should be called before passing result of from() to prepare_receive() function.

Accepts all parameters as advanced receive() version. For example:

// Receive and handle 3 messages.
// If there is no 3 messages in the mchain the receive will wait
// no more that 200ms.
// A return from receive will be after handling of 3 messages or
// if the mchain is closed explicitely, or if there is no messages
// for more than 200ms.
auto prepared1 = prepare_receive(
    from(chain).handle_n( 3 ).empty_timeout( milliseconds(200) ),
    []( const first_message_type & msg ) { ... },
    []( const second_message_type & msg ) { ... }, ... );
 
// Receive all messages from the chain.
// If there is no message in the chain then wait no more than 500ms.
// A return from receive will be after explicit close of the chain
// or if there is no messages for more than 500ms.
auto prepared2 = prepare_receive(
    from(chain).handle_all().empty_timeout( milliseconds(500) ),
    []( const first_message_type & msg ) { ... },
    []( const second_message_type & msg ) { ... }, ... );

Note

Since v.5.8.4 the value of empty_timeout (or no_wait_on_empty) is taken into account when total_time is specified. It means that in the following example the receive() returns immediately if the mchain is empty:

auto prepared = prepare_receive(
 from(ch).handle_n(5).no_wait_on_empty().total_time(6s),
 [](const my_message & msg) {...});
...
auto r = so_5::receive(prepared);

Since

v.5.5.17

Parameters

params	Parameters for advanced receive.
handlers	Handlers

Definition at line 2045 of file mchain.hpp.

prepare_select()

template<mchain_props::msg_count_status_t Msg_Count_Status, typename... Cases>

prepared_select_t< sizeof...(Cases) > so_5::prepare_select	(	mchain_select_params_t< Msg_Count_Status >	params,
		Cases &&...	cases )

Create prepared select statement to be used later.

Attention

Since v.5.6.0 at least handle_all(), handle_n() or extract_n() should be called before passing result of from_all() to prepare_select() function.

Accepts all parameters as advanced select() version. For example:

// Receive and handle 3 messages.
// If there is no 3 messages in chains the select will wait
// no more that 200ms.
// A return from select will be after handling of 3 messages or
// if all mchains are closed explicitely, or if there is no messages
// for more than 200ms.
auto prepared1 = prepare_select(
  so_5::from_all().handle_n( 3 ).empty_timeout( milliseconds(200) ),
  receive_case( ch1,
      []( const first_message_type & msg ) { ... },
      []( const second_message_type & msg ) { ... } ),
  receive_case( ch2,
      []( const third_message_type & msg ) { ... },
      handler< some_signal_type >( []{ ... ] ),
      ... ) );
 
// Receive all messages from mchains.
// If there is no message in any of mchains then wait no more than 500ms.
// A return from select will be after explicit close of all mchains
// or if there is no messages for more than 500ms.
auto prepared2 = prepare_select(
  so_5::from_all().handle_all().empty_timeout( milliseconds(500) ),
  receive_case( ch1,
      []( const first_message_type & msg ) { ... },
      []( const second_message_type & msg ) { ... } ),
  receive_case( ch2,
      []( const third_message_type & msg ) { ... },
      handler< some_signal_type >( []{ ... ] ),
      ... ) );

Note

Since v.5.8.4 the value of empty_timeout (or no_wait_on_empty) is taken into account when total_time is specified. It means that in the following example the select() returns immediately if all mchains are empty:

auto prepared = prepare_select(
 from_all().handle_n(5).no_wait_on_empty().total_time(6s),
 receive_case( ch1, ...),
 receive_case( ch2, ...) );
...
so_5::select(prepared);

Since

v.5.5.17

Parameters

params	Parameters for advanced select.
cases	Select cases.

Definition at line 1888 of file mchain_select.hpp.

preprocess_agent_event_handler() [1/2]

template<typename Lambda >

std::enable_if< details::lambda_traits::is_lambda< Lambda >::value, details::msg_type_and_handler_pair_t >::type so_5::preprocess_agent_event_handler	(	const mbox_t &	mbox,
		agent_t &	,
		Lambda &&	lambda )

Do preprocessing and some verification of event handler and return msg_type_and_handler_pair for it.

This overload is intended to be used for lambdas or functional objects.

Attention

Only lambda functions or functional objects in the following format are supported:

ret_type (message_type);
ret_type (const message_type &);
ret_type (mhood_t<message_type>);

Since

v.5.5.21

Definition at line 389 of file handler_makers.hpp.

preprocess_agent_event_handler() [2/2]

template<typename Method_Pointer >

std::enable_if< details::is_agent_method_pointer< details::method_arity::unary, Method_Pointer >::value, details::msg_type_and_handler_pair_t >::type so_5::preprocess_agent_event_handler	(	const mbox_t &	mbox,
		agent_t &	agent,
		Method_Pointer	pfn )

Do preprocessing and some verification of event handler and return msg_type_and_handler_pair for it.

This overload is intended to be used for pointers to members.

Note

Throws is handler can't be used with this type of mbox (for example: handler is for mutable message but mbox is Multi-Consumer one).

Since

v.5.5.21

Definition at line 343 of file handler_makers.hpp.

query_current_thread_id()

current_thread_id_t so_5::query_current_thread_id ( )

inline

Get the ID of the current thread.

Examples

so_5/selective_msg_tracing/main.cpp.

Definition at line 30 of file current_thread_id.hpp.

raw_id_from_current_thread_id()

std::thread::id so_5::raw_id_from_current_thread_id ( const current_thread_id_t & w )

inline

Get the raw thread id from current_thread_id.

Since

v.5.5.18

Definition at line 49 of file current_thread_id.hpp.

receive() [1/2]

template<mchain_props::msg_count_status_t Msg_Count_Status, typename... Handlers>

mchain_receive_result_t so_5::receive ( const mchain_receive_params_t< Msg_Count_Status > & params, Handlers &&... handlers )

inline

Advanced version of receive from mchain.

Attention

It is an error if there are more than one handler for the same message type in handlers.

Since v.5.6.0 at least handle_all(), handle_n() or extract_n() should be called before passing result of from() to receive() function.

Usage examples:

so_5::mchain_t chain = env.create_mchain(...);
 
// Receive and handle 3 messages.
// If there is no 3 messages in the mchain the receive will wait infinitely.
// A return from receive will be after handling of 3 messages or
// if the mchain is closed explicitely.
receive( from(chain).handle_n( 3 ),
    []( const first_message_type & msg ) { ... },
    []( const second_message_type & msg ) { ... }, ... );
 
// Receive and handle 3 messages.
// If there is no 3 messages in the mchain the receive will wait
// no more that 200ms.
// A return from receive will be after handling of 3 messages or
// if the mchain is closed explicitely, or if there is no messages
// for more than 200ms.
receive( from(chain).handle_n( 3 ).empty_timeout( milliseconds(200) ),
    []( const first_message_type & msg ) { ... },
    []( const second_message_type & msg ) { ... }, ... );
 
// Receive all messages from the chain.
// If there is no message in the chain then wait no more than 500ms.
// A return from receive will be after explicit close of the chain
// or if there is no messages for more than 500ms.
receive( from(chain).handle_all().empty_timeout( milliseconds(500) ),
    []( const first_message_type & msg ) { ... },
    []( const second_message_type & msg ) { ... }, ... );
 
// Receve any number of messages from the chain but do waiting and
// handling for no more than 2s.
receive( from(chain).handle_all().total_time( seconds(2) ),
    []( const first_message_type & msg ) { ... },
    []( const second_message_type & msg ) { ... }, ... );
 
// Receve 1000 messages from the chain but do waiting and
// handling for no more than 2s.
receive( from(chain).extract_n( 1000 ).total_time( seconds(2) ),
    []( const first_message_type & msg ) { ... },
    []( const second_message_type & msg ) { ... }, ... );

Handlers format examples:

receive( from(ch).handle_n(1),
  // Message instance by const reference.
  []( const std::string & v ) {...},
  // Message instance by value (efficient for small types like int).
  []( int v ) {...},
  // Message instance via mhood_t value.
  []( so_5::mhood_t< some_message > v ) {...},
  // Message instance via const reference to mhood_t.
  []( const so_5::mhood_t< some_another_message > & v ) {...},
  // Explicitly specified signal handler.
  so_5::handler< some_signal >( []{...} ),
  // Signal handler via mhood_t value.
  []( so_5::mhood_t< some_another_signal > ) {...},
  // Signal handler via const reference to mhood_t.
  []( const so_5::mhood_t< yet_another_signal > & ) {...} );

Note

Since v.5.8.4 the value of empty_timeout (or no_wait_on_empty) is taken into account when total_time is specified. It means that in the following example the receive() returns immediately if the mchain is empty:

receive(
 from(ch).handle_n(5).no_wait_on_empty().total_time(6s),
 [](const my_message & msg) {...});

Since

v.5.5.13

Parameters

params	Parameters for receive.
handlers	Handlers for message processing.

Examples

so_5/mchain_empty_notificator/main.cpp, so_5/mchain_empty_notificator_2/main.cpp, and so_5/producer_consumer_mchain/main.cpp.

Definition at line 1883 of file mchain.hpp.

receive() [2/2]

template<std::size_t Handlers_Count>

mchain_receive_result_t so_5::receive

(

const prepared_receive_t< Handlers_Count > &

prepared

)

A receive operation to be done on previously prepared receive params.

Usage of ordinary forms of receive() functions inside loops could be inefficient because of wasting resources on constructions of internal objects with descriptions of handlers on each receive() call. More efficient way is preparation of all receive params and reusing them later. A combination of so_5::prepare_receive() and so_5::receive(prepared_receive_t) allows to do that.

Usage example:

auto prepared = so_5::prepare_receive(
  so_5::from(ch).extract_n(10).empty_timeout(200ms),
  some_handlers... );
...
while( !some_condition )
{
  auto r = so_5::receive( prepared );
  ...
}

Since

v.5.5.17

Definition at line 2088 of file mchain.hpp.

receive_case()

template<typename... Handlers>

mchain_props::select_case_unique_ptr_t so_5::receive_case ( mchain_t chain, Handlers &&... handlers )

nodiscard

A helper for creation of select_case object for one multi chain select.

Attention

It is an error if there are more than one handler for the same message type in handlers.

See also

so_5::select()

Since

v.5.5.16

Parameters

chain	Message chain to be used in select.
handlers	Message handlers for messages extracted from that chain.

Definition at line 1534 of file mchain_select.hpp.

select() [1/3]

mchain_select_result_t so_5::select ( const extensible_select_t & extensible_select )

inline

A select operation to be done on previously prepared extensible-select object.

Usage example:

void handle_messages_from(const std::vector<so_5::mchain_t> & chains) {
  auto sel = so_5::make_extensible_select(so_5::from_all().handle_all());
 
  for(auto & ch : chains)
    so_5::add_select_cases(receive_case(ch, ...));
 
  auto r = so_5::select(sel);
  ... // Handing of the select() result.
}

Note

An attempt to call this function for extensible-select object that is used in some select() call will lead to an exception.

Attention

The extensible_select object must not be empty!

Since

v.5.6.1

Definition at line 2207 of file mchain_select.hpp.

select() [2/3]

template<mchain_props::msg_count_status_t Msg_Count_Status, typename... Cases>

mchain_select_result_t so_5::select	(	const mchain_select_params_t< Msg_Count_Status > &	params,
		Cases &&...	cases )

An advanced form of multi chain select.

Attention

The behaviour is not defined if a mchain is used in different select_cases.

Since v.5.6.0 at least handle_all(), handle_n() or extract_n() should be called before passing result of from_all() to select() function.

Usage examples:

using namespace so_5;
 
mchain_t ch1 = env.create_mchain(...);
mchain_t ch2 = env.create_mchain(...);
 
// Receive and handle 3 messages.
// It could be 3 messages from ch1. Or 2 messages from ch1 and 1 message
// from ch2. Or 1 message from ch1 and 2 messages from ch2. And so on...
//
// If there is no 3 messages in mchains the select will wait infinitely.
// A return from select will be after handling of 3 messages or
// if all mchains are closed explicitely.
select( from_all().handle_n( 3 ),
  receive_case( ch1,
      []( const first_message_type & msg ) { ... },
      []( const second_message_type & msg ) { ... } ),
  receive_case( ch2,
      []( const third_message_type & msg ) { ... },
      handler< some_signal_type >( []{ ... ] ),
      ... ) );
 
// Receive and handle 3 messages.
// If there is no 3 messages in chains the select will wait
// no more that 200ms.
// A return from select will be after handling of 3 messages or
// if all mchains are closed explicitely, or if there is no messages
// for more than 200ms.
select( from_all().handle_n( 3 ).empty_timeout( milliseconds(200) ),
  receive_case( ch1,
      []( const first_message_type & msg ) { ... },
      []( const second_message_type & msg ) { ... } ),
  receive_case( ch2,
      []( const third_message_type & msg ) { ... },
      handler< some_signal_type >( []{ ... ] ),
      ... ) );
 
// Receive all messages from mchains.
// If there is no message in any of mchains then wait no more than 500ms.
// A return from select will be after explicit close of all mchains
// or if there is no messages for more than 500ms.
select( from_all().handle_all().empty_timeout( milliseconds(500) ),
  receive_case( ch1,
      []( const first_message_type & msg ) { ... },
      []( const second_message_type & msg ) { ... } ),
  receive_case( ch2,
      []( const third_message_type & msg ) { ... },
      handler< some_signal_type >( []{ ... ] ),
      ... ) );
 
// Receve any number of messages from mchains but do waiting and
// handling for no more than 2s.
select( from_all().handle_all().total_time( seconds(2) ),
  receive_case( ch1,
      []( const first_message_type & msg ) { ... },
      []( const second_message_type & msg ) { ... } ),
  receive_case( ch2,
      []( const third_message_type & msg ) { ... },
      handler< some_signal_type >( []{ ... ] ),
      ... ) );
 
// Receve 1000 messages from chains but do waiting and
// handling for no more than 2s.
select( from_all().extract_n( 1000 ).total_time( seconds(2) ),
  receive_case( ch1,
      []( const first_message_type & msg ) { ... },
      []( const second_message_type & msg ) { ... } ),
  receive_case( ch2,
      []( const third_message_type & msg ) { ... },
      handler< some_signal_type >( []{ ... ] ),
      ... ) );

Note

Since v.5.8.4 the value of empty_timeout (or no_wait_on_empty) is taken into account when total_time is specified. It means that in the following example the select() returns immediately if all mchains are empty:

select(
 from_all().handle_n(5).no_wait_on_empty().total_time(6s),
 receive_case( ch1, ...),
 receive_case( ch2, ...) );

Since

v.5.5.16

Parameters

params	Parameters for advanced select.
cases	Select cases.

Examples

so_5/mchain_empty_notificator_2/main.cpp.

Definition at line 1691 of file mchain_select.hpp.

select() [3/3]

template<std::size_t Cases_Count>

mchain_select_result_t so_5::select

(

const prepared_select_t< Cases_Count > &

prepared

)

A select operation to be done on previously prepared select params.

Usage of ordinary forms of select() functions inside loops could be inefficient because of wasting resources on constructions of internal objects with descriptions of select cases on each select() call. More efficient way is preparation of all select params and reusing them later. A combination of so_5::prepare_select() and so_5::select(prepared_select_t) allows to do that.

Usage example:

auto prepared = so_5::prepare_select(
  so_5::from_all().extract_n(10).empty_timeout(200ms),
  receive_case( ch1, some_handlers... ),
  receive_case( ch2, more_handlers... ),
  receive_case( ch3, yet_more_handlers... ) );
...
while( !some_condition )
{
  auto r = so_5::select( prepared );
  ...
}

Attention

Since v.5.6.1 there is a check for usage of prepared-select object in parallel/nested calls to select(). If such call detected then an exception is thrown.

Since

v.5.5.17

Definition at line 1938 of file mchain_select.hpp.

send() [1/4]

template<typename Message , typename Target , typename... Args>

void so_5::send	(	Target &&	to,
		Args &&...	args )

A utility function for creating and delivering a message or a signal.

Since

v.5.5.1

Note

Since v.5.5.13 can send also a signal.

Template Parameters

Message	type of message to be sent.
Target	identification of request processor. Could be reference to so_5::mbox_t, to so_5::agent_t (the later case agent's direct mbox will be used).
Args	arguments for Message's constructor.

Usage samples:

struct hello_msg { std::string greeting; std::string who };
 
// Send to mbox.
so_5::send< hello_msg >( env.create_mbox( "hello" ), "Hello", "World!" );
 
// Send to agent.
class demo_agent : public so_5::agent_t
{
public :
  ...
  virtual void so_evt_start() override
  {
    ...
    so_5::send< hello_msg >( *this, "Hello", "World!" );
  }
};
 
struct turn_on : public so_5::signal_t {};
 
// Send to mbox.
so_5::send< turn_on >( env.create_mbox( "engine" ) );
 
// Send to agent.
class engine_agent : public so_5::agent_t
{
public :
  ...
  virtual void so_evt_start() override
  {
    ...
    so_5::send< turn_on >( *this );
  }
};

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/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/hardwork_imit/main.cpp, so_5/hello_all/main.cpp, so_5/hello_evt_handler/main.cpp, so_5/hello_evt_lambda/main.cpp, so_5/intercom_statechart/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/make_pipeline/main.cpp, so_5/mchain_empty_notificator/main.cpp, so_5/mchain_empty_notificator_2/main.cpp, so_5/mchain_handler_formats/main.cpp, so_5/mchain_multi_consumers/main.cpp, so_5/mchain_select/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/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, so_5/wrapped_env_demo_2/main.cpp, and so_5/wrapped_env_demo_3/main.cpp.

Definition at line 228 of file send_functions.hpp.

send() [2/4]

template<typename Target , typename Message , message_ownership_t Ownership>

void so_5::send	(	Target &&	to,
		message_holder_t< Message, Ownership >	what )

A version of send function for redirection of a message from exising message_holder instance.

Usage example:

class preallocated_messages_owner final : public so_5::agent_t {
  so_5::message_holder_t<some_message> first_;
  so_5::message_holder_t<so_5::mutable_msg<another_message>> second_;
  ...
  void on_some_event(mhood_t<some_event>) {
    // It is time to send preallocated messages.
 
    // This message will be sent as immutable message.
    so_5::send(dest, first_);
 
    // This message will be sent as mutable message.
    so_5::send(dest, std::move(second_));
  }
};

Attention

An attempt to call this function for empty message_holder object is UB.

Since

v.5.6.0

Parameters

to	Destination for the message.
what	Message to be sent.

Definition at line 337 of file send_functions.hpp.

send() [3/4]

template<typename Target , typename Message >

std::enable_if<!is_signal< Message >::value >::type so_5::send	(	Target &&	to,
		mhood_t< Message >	what )

A version of send function for redirection of a message from exising message hood.

Template Parameters

Message

a type of message to be redirected (it can be in form of Msg, so_5::immutable_msg<Msg> or so_5::mutable_msg<Msg>).

Usage example:

class redirector : public so_5::agent_t {
  ...
  void on_some_immutable_message(mhood_t<first_msg> cmd) {
    so_5::send(another_mbox, cmd);
    ...
  }
 
  void on_some_mutable_message(mhood_t<mutable_msg<second_msg>> cmd) {
    so_5::send(another_mbox, std::move(cmd));
    // Note: cmd is nullptr now, it can't be used anymore.
    ...
  }
};

Since

v.5.5.19

Definition at line 264 of file send_functions.hpp.

send() [4/4]

template<typename Target , typename Message >

std::enable_if< is_signal< Message >::value >::type so_5::send	(	Target &&	to,
		mhood_t< Message >	)

A version of send function for redirection of a signal from exising message hood.

Template Parameters

Message

a type of signal to be redirected (it can be in form of Sig or so_5::immutable_msg<Sig>).

Usage example:

class redirector : public so_5::agent_t {
  ...
  void on_some_immutable_signal(mhood_t<some_signal> cmd) {
    so_5::send(another_mbox, cmd);
    ...
  }
};

Since

v.5.5.19

Definition at line 298 of file send_functions.hpp.

send_case()

template<typename Msg , message_ownership_t Ownership, typename On_Success_Handler >

mchain_props::select_case_unique_ptr_t so_5::send_case ( mchain_t chain, message_holder_t< Msg, Ownership > msg, On_Success_Handler && handler )

nodiscard

A helper for creation of select_case object for one send-case of a multi chain select.

See also

so_5::select()

Since

v.5.7.0

Parameters

chain	Message chain to be used in select.
msg	Message instance to be sent.

Examples

so_5/mchain_empty_notificator_2/main.cpp.

Definition at line 1566 of file mchain_select.hpp.

send_delayed() [1/4]

template<typename Message , typename Target , typename... Args>

void so_5::send_delayed	(	Target &&	target,
		std::chrono::steady_clock::duration	pause,
		Args &&...	args )

A utility function for creating and delivering a delayed message to the specified destination.

Agent or mchain can be used as target.

Attention

Value of pause should be non-negative.

Template Parameters

Message	type of message or signal to be sent.
Target	can be so_5::agent_t or so_5::mchain_t.
Args	list of arguments for Message's constructor.

Since

v.5.5.19

Parameters

target	A target for delayed message.
pause	Pause for message delaying.
args	Message constructor parameters.

Examples

so_5/agent_name/main.cpp, so_5/child_soenv/main.cpp, so_5/custom_work_thread_factory/main.cpp, so_5/hello_delay/main.cpp, so_5/individual_msg_tracing/main.cpp, so_5/make_agent_ref/main.cpp, so_5/many_timers/main.cpp, so_5/mchain_empty_notificator/main.cpp, so_5/mchain_handler_formats/main.cpp, so_5/news_board/main.cpp, so_5/parent_coop/main.cpp, so_5/ping_pong_with_owner/main.cpp, so_5/prio_work_stealing/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/stop_guard/main.cpp, and so_5/wrapped_env_demo_3/main.cpp.

Definition at line 370 of file send_functions.hpp.

send_delayed() [2/4]

template<typename Target , typename Message , message_ownership_t Ownership>

void so_5::send_delayed	(	Target &&	to,
		std::chrono::steady_clock::duration	pause,
		message_holder_t< Message, Ownership >	msg )

A version of send_delayed function for redirection of a message from exising message_holder instance.

Usage example:

class preallocated_messages_owner final : public so_5::agent_t {
  so_5::message_holder_t<some_message> first_;
  so_5::message_holder_t<so_5::mutable_msg<another_message>> second_;
  ...
  void on_some_event(mhood_t<some_event>) {
    // It is time to send preallocated messages.
 
    // This message will be sent as immutable message.
    so_5::send_delayed(dest, 15s, first_);
 
    // This message will be sent as mutable message.
    so_5::send_delayed(dest, 15s, std::move(second_));
  }
};

Attention

An attempt to call this function for empty message_holder object is UB.

Since

v.5.6.0

Parameters

to	Destination for the message.
pause	Pause for message delaying.
msg	Message to be sent

Definition at line 557 of file send_functions.hpp.

send_delayed() [3/4]

template<typename Target , typename Message >

std::enable_if<!message_payload_type< Message >::is_signal >::type so_5::send_delayed	(	Target &&	to,
		std::chrono::steady_clock::duration	pause,
		mhood_t< Message >	msg )

A utility function for delayed redirection of a message from existing message hood.

Template Parameters

Target	a type of destination of the message. It can be an agent, a mbox or mchain.
Message	a type of message to be redirected (it can be in form of Msg, so_5::immutable_msg<Msg> or so_5::mutable_msg<Msg>).

Usage example:

class redirector : public so_5::agent_t {
  ...
  void on_some_immutable_message(mhood_t<first_msg> cmd) {
    so_5::send_delayed(another_mbox, std::chrono::seconds(1), cmd);
    ...
  }
 
  void on_some_mutable_message(mhood_t<mutable_msg<second_msg>> cmd) {
    so_5::send_delayed(another_mbox, std::chrono::seconds(1), std::move(cmd));
    // Note: cmd is nullptr now, it can't be used anymore.
    ...
  }
};

A redirection to the direct mbox of some agent can looks like:

void some_agent::on_some_message(mhood_t<some_message> cmd) {
 // Redirect to itself but with a pause.
 so_5::send_delayed(*this, std::chrono::seconds(2), cmd);
}
// For the case of mutable message.
void another_agent::on_another_msg(mutable_mhood_t<another_msg> cmd) {
 // Redirect to itself but with a pause.
 so_5::send_delayed(*this, std::chrono::seconds(2), std::move(cmd));
 // Note: cmd is nullptr now, it can't be used anymore.
}

A redirection to a mchain can looks like:

so_5::mchain_t first = ...;
so_5::mchain_t second = ...;
so_5::receive(so_5::from(first).handle_n(1),
 [second](so_5::mhood_t<some_message> cmd) {
   so_5::send_delayed(second, std::chrono::seconds(1), cmd);
 },
 [second](so_5::mutable_mhood_t<another_message> cmd) {
   so_5::send_delayed(second, std::chrono::seconds(1), std::move(cmd));
   // Note: cmd is nullptr now, it can't be used anymore.
 });

Attention

Value of pause should be non-negative.

Since

v.5.5.19

Parameters

to	Destination for the message.
pause	Pause for message delaying.
msg	Message instance owner.

Definition at line 446 of file send_functions.hpp.

send_delayed() [4/4]

template<typename Target , typename Message >

std::enable_if< message_payload_type< Message >::is_signal >::type so_5::send_delayed	(	Target &&	to,
		std::chrono::steady_clock::duration	pause,
		mhood_t< Message >	)

A utility function for delayed redirection of a signal from existing message hood.

Template Parameters

Target	a type of destination of the signal. It can be an agent, a mbox or mchain.
Message	a type of signal to be redirected (it can be in form of Sig or so_5::immutable_msg<Sig>).

Usage example:

class redirector : public so_5::agent_t {
  ...
  void on_some_immutable_signal(mhood_t<some_signal> cmd) {
    so_5::send_delayed(another_mbox, std::chrono::seconds(1), cmd);
    ...
  }
};

A redirection to the direct mbox of some agent can looks like:

void some_agent::on_some_signal(mhood_t<some_signal> cmd) {
 // Redirect to itself but with a pause.
 so_5::send_delayed(*this, std::chrono::seconds(2), cmd);
}

A redirection to a mchain can looks like:

so_5::mchain_t first = ...;
so_5::mchain_t second = ...;
so_5::receive(so_5::from(first).handle_n(1),
 [second](so_5::mhood_t<some_signal> cmd) {
   so_5::send_delayed(second, std::chrono::seconds(1), cmd);
 });

Attention

Value of pause should be non-negative.

Since

v.5.5.19

Parameters

to	Destination for the message.
pause	Pause for message delaying.

Definition at line 507 of file send_functions.hpp.

send_periodic() [1/4]

template<typename Message , typename Target , typename... Args>

timer_id_t so_5::send_periodic ( Target && target, std::chrono::steady_clock::duration pause, std::chrono::steady_clock::duration period, Args &&... args )

nodiscard

A utility function for creating and delivering a periodic message to the specified destination.

Agent or mchain can be used as target.

Note

Message chains with overload control must be used for periodic messages with additional care: so-5.5.18: Overloaded mchains and delayed/periodic messages delivery.

Attention

Values of pause and period should be non-negative.

Template Parameters

Message	type of message or signal to be sent.
Target	can be so_5::agent_t or so_5::mchain_t.
Args	list of arguments for Message's constructor.

Since

v.5.5.19

Parameters

target	A destination for the periodic message.
pause	Pause for message delaying.
period	Period of message repetitions.
args	Message constructor parameters.

Examples

so_5/agent_name/main.cpp, so_5/bind_transformer/main.cpp, so_5/child_soenv/main.cpp, so_5/chstate/main.cpp, so_5/chstate_msg_tracing/main.cpp, so_5/hello_periodic/main.cpp, so_5/intercom_statechart/main.cpp, so_5/machine_control/main.cpp, so_5/mchain_empty_notificator_2/main.cpp, so_5/mchain_handler_formats/main.cpp, and so_5/stop_guard/main.cpp.

Definition at line 596 of file send_functions.hpp.

send_periodic() [2/4]

template<typename Target , typename Message , message_ownership_t Ownership>

timer_id_t so_5::send_periodic ( Target && target, std::chrono::steady_clock::duration pause, std::chrono::steady_clock::duration period, message_holder_t< Message, Ownership > what )

nodiscard

A version of send_periodic function for redirection of a message from exising message_holder instance.

Note

Note that an attempt to call with function with non-zero period argument for a mutable messages will lead to an exception. It is because mutable message can't be sent as periodic message.

Usage example:

class preallocated_messages_owner final : public so_5::agent_t {
  so_5::message_holder_t<some_message> msg_;
  so_5::timer_id_t msg_timer_;
  ...
  void on_some_event(mhood_t<some_event>) {
    // It is time to send preallocated message.
    // This message will be sent as immutable message.
    msg_timer_ = so_5::send_periodic(dest, 15s, 20s, msg_);
  }
};

Attention

An attempt to call this function for empty message_holder object is UB.

Since

v.5.6.0

Parameters

target	A destination for the periodic message.
pause	Pause for message delaying.
period	Period of message repetitions.
what	Message to be sent.

Definition at line 817 of file send_functions.hpp.

send_periodic() [3/4]

template<typename Target , typename Message >

std::enable_if<!is_signal< Message >::value, timer_id_t >::type so_5::send_periodic ( Target && target, std::chrono::steady_clock::duration pause, std::chrono::steady_clock::duration period, mhood_t< Message > mhood )

nodiscard

A utility function for delivering a periodic from an existing message hood.

Attention

Message must not be a mutable message if period is not 0. Otherwise an exception will be thrown.

Template Parameters

Target	a type of destination of the message. It can be an agent, a mbox or mchain.
Message	a type of message to be redirected (it can be in form of Msg, so_5::immutable_msg<Msg> or so_5::mutable_msg<Msg>).

Usage example:

class redirector : public so_5::agent_t {
  ...
  void on_some_immutable_message(mhood_t<first_msg> cmd) {
    timer_id = so_5::send_periodic(another_mbox,
        std::chrono::seconds(1),
        std::chrono::seconds(15),
        cmd);
    ...
  }
 
  void on_some_mutable_message(mhood_t<mutable_msg<second_msg>> cmd) {
    timer_id = so_5::send_periodic(another_mbox,
        std::chrono::seconds(1),
        std::chrono::seconds::zero(), // Note: period is 0!
        std::move(cmd));
    // Note: cmd is nullptr now, it can't be used anymore.
    ...
  }
};

A redirection to the direct mbox of some agent can looks like:

void some_agent::on_some_message(mhood_t<some_message> cmd) {
 // Redirect to itself but with a pause and a period.
 timer_id = so_5::send_periodic(*this,
     std::chrono::seconds(2),
     std::chrono::seconds(5),
     cmd);
}

A redirection to a mchain can looks like:

so_5::mchain_t first = ...;
so_5::mchain_t second = ...;
so_5::timer_id_t timer_id;
so_5::receive(so_5::from(first).handle_n(1),
 [&](so_5::mhood_t<some_message> cmd) {
   timer_id = so_5::send_periodic(
       second,
       std::chrono::seconds(2),
       std::chrono::seconds(5),
       cmd);
 });

Note

Message chains with overload control must be used for periodic messages with additional care: so-5.5.18: Overloaded mchains and delayed/periodic messages delivery.

Attention

Values of pause and period should be non-negative.

Since

v.5.5.19

Parameters

target	A destination for the periodic message.
pause	Pause for message delaying.
period	Period of message repetitions.
mhood	Existing message hood for message to be sent.

Definition at line 685 of file send_functions.hpp.

send_periodic() [4/4]

template<typename Target , typename Message >

std::enable_if< is_signal< Message >::value, timer_id_t >::type so_5::send_periodic ( Target && target, std::chrono::steady_clock::duration pause, std::chrono::steady_clock::duration period, mhood_t< Message >  )

nodiscard

A utility function for periodic redirection of a signal from existing message hood.

Template Parameters

Target	a type of destination of the signal. It can be an agent, a mbox or mchain.
Message	a type of signal to be redirected (it can be in form of Sig or so_5::immutable_msg<Sig>).

Usage example:

class redirector : public so_5::agent_t {
  ...
  void on_some_immutable_signal(mhood_t<some_signal> cmd) {
    timer_id = so_5::send_periodic(another_mbox,
        std::chrono::seconds(1),
        std::chrono::seconds(10),
        cmd);
    ...
  }
};

A redirection to the direct mbox of some agent can looks like:

void some_agent::on_some_message(mhood_t<some_signal> cmd) {
 // Redirect to itself but with a pause and a period.
 timer_id = so_5::send_periodic(*this,
     std::chrono::seconds(2),
     std::chrono::seconds(5),
     cmd);
}

A redirection to a mchain can looks like:

so_5::mchain_t first = ...;
so_5::mchain_t second = ...;
so_5::timer_id_t timer_id;
so_5::receive(so_5::from(first).handle_n(1),
 [&](so_5::mhood_t<some_signal> cmd) {
   timer_id = so_5::send_periodic(
       second,
       std::chrono::seconds(2),
       std::chrono::seconds(5),
       cmd);
 });

Note

Message chains with overload control must be used for periodic messages with additional care: so-5.5.18: Overloaded mchains and delayed/periodic messages delivery.

Attention

Values of pause and period should be non-negative.

Since

v.5.5.19

Parameters

target	A destination for the periodic message.
pause	Pause for message delaying.
period	Period of message repetitions.

Definition at line 763 of file send_functions.hpp.

swap() [1/2]

SO_5_FUNC void so_5::swap ( environment_params_t & a, environment_params_t & b )

noexcept

Since

v.5.2.3

Definition at line 85 of file environment.cpp.

swap() [2/2]

SO_5_FUNC void so_5::swap ( name_for_agent_t & a, name_for_agent_t & b )

noexcept

Definition at line 150 of file agent.cpp.

timer_heap_factory() [1/2]

timer_thread_factory_t so_5::timer_heap_factory ( )

inline

Factory for timer_heap thread with default parameters.

Since

v.5.5.0

Examples

so_5/many_timers/main.cpp.

Definition at line 365 of file timers.hpp.

timer_heap_factory() [2/2]

timer_thread_factory_t so_5::timer_heap_factory ( std::size_t initial_heap_capacity )

inline

Factory for timer_heap thread with explicitely specified parameters.

Since

v.5.5.0

Parameters

initial_heap_capacity

Initial capacity of heap array.

Definition at line 380 of file timers.hpp.

timer_heap_manager_factory() [1/2]

timer_manager_factory_t so_5::timer_heap_manager_factory ( )

inline

Factory for timer_heap manager with default parameters.

Since

v.5.5.0

Definition at line 709 of file timers.hpp.

timer_heap_manager_factory() [2/2]

timer_manager_factory_t so_5::timer_heap_manager_factory ( std::size_t initial_heap_capacity )

inline

Factory for timer_heap manager with explicitely specified parameters.

Since

v.5.5.0

Parameters

initial_heap_capacity

Initial capacity of heap array.

Definition at line 727 of file timers.hpp.

timer_list_factory()

timer_thread_factory_t so_5::timer_list_factory ( )

inline

Factory for timer_list thread with default parameters.

Since

v.5.5.0

Examples

so_5/many_timers/main.cpp.

Definition at line 401 of file timers.hpp.

timer_list_manager_factory()

timer_manager_factory_t so_5::timer_list_manager_factory ( )

inline

Factory for timer_list manager with default parameters.

Since

v.5.5.0

Definition at line 753 of file timers.hpp.

timer_wheel_factory() [1/2]

timer_thread_factory_t so_5::timer_wheel_factory ( )

inline

Factory for timer_wheel thread with default parameters.

Since

v.5.5.0

Examples

so_5/many_timers/main.cpp.

Definition at line 323 of file timers.hpp.

timer_wheel_factory() [2/2]

timer_thread_factory_t so_5::timer_wheel_factory ( unsigned int wheel_size, std::chrono::steady_clock::duration granularity )

inline

Factory for timer_wheel thread with explicitely specified parameters.

Since

v.5.5.0

Parameters

wheel_size	Size of the wheel.
granularity	A size of one time step for the wheel.

Definition at line 338 of file timers.hpp.

timer_wheel_manager_factory() [1/2]

timer_manager_factory_t so_5::timer_wheel_manager_factory ( )

inline

Factory for timer_wheel manager with default parameters.

Since

v.5.5.0

Definition at line 660 of file timers.hpp.

timer_wheel_manager_factory() [2/2]

timer_manager_factory_t so_5::timer_wheel_manager_factory ( unsigned int wheel_size, std::chrono::steady_clock::duration granularity )

inline

Factory for timer_wheel manager with explicitely specified parameters.

Since

v.5.5.0

Parameters

wheel_size	Size of the wheel.
granularity	A size of one time step for the wheel.

Definition at line 679 of file timers.hpp.

to_immutable() [1/2]

template<typename M >

std::enable_if<!is_signal< M >::value, mhood_t< immutable_msg< M > > >::type so_5::to_immutable

(

mhood_t< mutable_msg< M > >

msg

)

Transform mutable message instance into immutable.

Attention

Moves all content from msg into new object and leaves msg object in nullptr state.

Usage example:

void on_hello_mut( mhood_t< so_5::mutable_msg< hello > > cmd )
{
  cmd->m_content = "bye";
  send( another_mbox, to_immutable( std::move(cmd) ) );
}

Since

v.5.5.19

Examples

so_5/modify_resend_as_immutable/main.cpp.

Definition at line 597 of file mhood.hpp.

to_immutable() [2/2]

template<typename M >

std::enable_if< is_signal< M >::value, mhood_t< immutable_msg< M > > >::type so_5::to_immutable

(

mhood_t< mutable_msg< M > >

)

Definition at line 607 of file mhood.hpp.

to_priority_t()

priority_t so_5::to_priority_t ( std::size_t v )

inline

Helper function for conversion from size_t to priority.

Since

v.5.5.8

Exceptions

std::invalid_argument

if v is out of range.

Examples

so_5/prio_work_stealing/main.cpp.

Definition at line 62 of file priority.hpp.

to_size_t()

std::size_t so_5::to_size_t ( priority_t priority )

inline

Helper function for conversion from priority to size_t.

Since

v.5.5.8

Examples

so_5/prio_work_stealing/main.cpp.

Definition at line 48 of file priority.hpp.

vector_based_subscription_storage_factory()

SO_5_FUNC subscription_storage_factory_t so_5::vector_based_subscription_storage_factory ( std::size_t initial_capacity )

nodiscard

Factory for subscription storage based on unsorted std::vector.

Note

Uses very simple working scheme: all subscriptions are stored in the linear vector and simpliest linear search is used for seaching and manipulating of subscriptions. Because of that vector-based storage must be used only with very small amount of subscriptions.

More about subscription storage tuning

See so-5.5.3: Subscription storage type selection for more details about selection of appropriate subscription storage type.

Since

v.5.5.3

Parameters

initial_capacity

Initial storage capacity.

Definition at line 429 of file subscr_storage_vector_based.cpp.

wrap_to_msink()

msink_t so_5::wrap_to_msink ( const mbox_t & mbox, so_5::priority_t sink_priority = prio::p0 )

nodiscard

Helper for wrapping an existing mbox into message_sink.

Usage example:

const so_5::mbox_t source = ...;
const so_5::mbox_t dest = ...;
 
so_5::single_sink_binding_t source_to_dest_binding;
source_to_dest_binding.bind<my_message>(
  // Source mbox has to be specified as is.
  source,
  // The destination has to be wrapped into a msink.
  so_5::wrap_to_msink(dest));

Attention

The mbox is expected to be not-null.

Examples

so_5/single_sink_binding/main.cpp.

Definition at line 109 of file mbox.cpp.

Variable Documentation

exceptions_enabled

exceptions_enabled_t so_5::exceptions_enabled {}

inlineconstexpr

Value that indicates that exceptions are enabled.

Usage example:

auto ch = so_5::create_mchain(env);
...
so_5::close_drop_content( so_5::exceptions_enabled, ch );

Since

v.5.7.3

Examples

so_5/mchain_empty_notificator/main.cpp, so_5/mchain_empty_notificator_2/main.cpp, so_5/mchain_handler_formats/main.cpp, so_5/mchain_multi_consumers/main.cpp, and so_5/mchain_select/main.cpp.

Definition at line 36 of file exception_control_flags.hpp.

infinite_wait

const infinite_wait_indication so_5::infinite_wait

Initial value:

=
    infinite_wait_indication::infinite_wait

A special indicator for infinite waiting on service request or on receive from mchain.

Since

v.5.5.13

Definition at line 33 of file wait_indication.hpp.

max_redirection_deep

unsigned int so_5::max_redirection_deep = 32

constexpr

Maximum deep of message redirections.

Examples for message redirections:

• message limits are used and so_5::agent_t::limit_then_redirect is used for pushing a message to another mbox;
• a custom message sink is used for transfering messages from one mbox to another.

Such redirections could lead to infinite loops. SObjectizer cannot detect such loops so it uses a primitive protection method: the limit for a number of redirections. If message delivery attempt exceeds this limit then the delivery must be cancelled (with or without an exception).

Since

v.5.8.0

Definition at line 42 of file message_sink.hpp.

no_wait

const no_wait_indication so_5::no_wait = no_wait_indication::no_wait

A special indicator for no waiting on service request or on receive from mchain.

Since

v.5.5.13

Definition at line 52 of file wait_indication.hpp.

not_thread_safe

const thread_safety_t so_5::not_thread_safe = thread_safety_t::unsafe

Shorthand for thread unsafety indicator.

Since

v.5.4.0

Definition at line 62 of file types.hpp.

rc_agent_deactivated

const int so_5::rc_agent_deactivated = 189

Agent can't change state because the agent is already deactivated.

There is a special state for an agent in that agent can't handle events and only waits for the deregistration. An agent is switched to that state due to unhandled exception (with exception reaction set to so_5::deregister_coop_on_exception) or after by a call to agent_t::so_deactivate_agent(). It is impossible to change the state of the agent if the agent is in that state already.

Since

v.5.7.3

Definition at line 432 of file ret_code.hpp.

rc_agent_has_no_cooperation

const int so_5::rc_agent_has_no_cooperation = 14

Agent is not bound to a cooperation.

Definition at line 33 of file ret_code.hpp.

rc_agent_incompatible_type_conversion

const int so_5::rc_agent_incompatible_type_conversion = 15

It is impossible to make a cast to that type.

Definition at line 36 of file ret_code.hpp.

rc_agent_is_not_the_state_owner

const int so_5::rc_agent_is_not_the_state_owner = 43

Agent doesn't own this state.

Definition at line 108 of file ret_code.hpp.

rc_agent_name_too_long

const int so_5::rc_agent_name_too_long = 197

Length of an agent name is too large.

Since

v.5.8.2

Definition at line 519 of file ret_code.hpp.

rc_agent_to_disp_binding_failed

const int so_5::rc_agent_to_disp_binding_failed = 27

Binding of agent to dispatcher failed.

Since

v.5.4.0

Definition at line 81 of file ret_code.hpp.

rc_agent_unknown_state

const int so_5::rc_agent_unknown_state = 10

Trying to switch to the unknown state.

Definition at line 30 of file ret_code.hpp.

rc_another_state_switch_in_progress

const int so_5::rc_another_state_switch_in_progress = 170

An attempt to switch agent state when another switch operation is in progress.

Since

v.5.5.18

Definition at line 216 of file ret_code.hpp.

rc_attempt_to_cast_to_envelope_on_nullptr

const int so_5::rc_attempt_to_cast_to_envelope_on_nullptr = 180

An attempt to cast message to message envelope when a pointer to message is NULL.

Envelopes were introduced in v.5.5.23. Envelopes are sent and delivered as ordinary messages (it means that pointer to envelope will be sent as pointer to message_t). For processing of an envelope it is necessary to cast a pointer from message_t to envelope_t. But it is impossible if a pointer to message_t is null.

Since

v.5.5.23

Definition at line 351 of file ret_code.hpp.

rc_autoshutdown_must_be_enabled

const int so_5::rc_autoshutdown_must_be_enabled = 171

An attempt to launch environment with autoshutdown disabled in conditions where autoshutdown must be enabled.

For example so_5::env_infrastructures::simple_not_mtsafe requires autoshutdown feature.

Since

v.5.5.19

Definition at line 227 of file ret_code.hpp.

rc_cannot_set_stop_guard_when_stop_is_started

const int so_5::rc_cannot_set_stop_guard_when_stop_is_started = 175

An attempt to set up a new stop_guard when the stop operation is already in progress.

Since

v.5.5.19.2

Definition at line 259 of file ret_code.hpp.

rc_coop_already_destroyed

const int so_5::rc_coop_already_destroyed = 184

An attempt to get a pointer to already destroyed cooperation.

This error can be reported when a coop_handle instance for already destroyed coop is used.

Since

v.5.6.0

Definition at line 384 of file ret_code.hpp.

rc_coop_define_agent_failed

const int so_5::rc_coop_define_agent_failed = 24

Cooperation couldn't be registered.

Definition at line 74 of file ret_code.hpp.

rc_coop_is_not_in_registered_state

const int so_5::rc_coop_is_not_in_registered_state = 185

An attempt to do something with coop that is not in registered state.

For example if can be an attempt to add a new child coop when the parent coop is being deregistered.

Since

v.5.6.0

Definition at line 395 of file ret_code.hpp.

rc_disp_binder_already_set_for_agent

const int so_5::rc_disp_binder_already_set_for_agent = 194

The dispatcher binder is already set for the agent.

Since v.5.7.5 disp_binder is stored inside the agent. Only one disp_binder can be set for an agent. An attempt to set disp_binder when the agent already has one is an error.

Since

v.5.7.5

Definition at line 492 of file ret_code.hpp.

rc_disp_create_failed

const int so_5::rc_disp_create_failed = 31

Unable to create a dispatcher.

Definition at line 97 of file ret_code.hpp.

rc_empty_agent_name

const int so_5::rc_empty_agent_name = 196

Name for an agent can't be empty.

Since

v.5.8.2

Definition at line 512 of file ret_code.hpp.

rc_empty_name

const int so_5::rc_empty_name = 500

The empty name doesn't allowed.

Definition at line 532 of file ret_code.hpp.

rc_environment_error

const int so_5::rc_environment_error = 1

so_environment launch is failed.

Definition at line 24 of file ret_code.hpp.

rc_evt_handler_already_provided

const int so_5::rc_evt_handler_already_provided = 40

A handler for that event/mbox/state is already registered.

Definition at line 105 of file ret_code.hpp.

rc_extensible_select_is_active_now

const int so_5::rc_extensible_select_is_active_now = 187

An attempt to modify or activate extensible-select when an operation on that extensible-select object is already active.

Since

v.5.6.1

Definition at line 410 of file ret_code.hpp.

rc_illegal_subscriber_for_mpsc_mbox

const int so_5::rc_illegal_subscriber_for_mpsc_mbox = 47

An attempt to create illegal subscription to mpsc_mbox.

Since

v.5.4.0

Definition at line 115 of file ret_code.hpp.

rc_initial_substate_already_defined

const int so_5::rc_initial_substate_already_defined = 19

Initial substate for a composite state is already defined.

Since

v.5.5.15

Definition at line 66 of file ret_code.hpp.

rc_invalid_time_limit_for_state

const int so_5::rc_invalid_time_limit_for_state = 501

Invalid value of time limit for an agent's state.

Since

v.5.5.15

Definition at line 539 of file ret_code.hpp.

rc_layer_does_not_exist

const int so_5::rc_layer_does_not_exist = 105

A layer with the specified type doesn't exist.

Definition at line 167 of file ret_code.hpp.

rc_layer_not_binded_to_so_env

const int so_5::rc_layer_not_binded_to_so_env = 100

The layer is not bound to the SObjectizer Environment.

Definition at line 152 of file ret_code.hpp.

rc_message_has_no_limit_defined

const int so_5::rc_message_has_no_limit_defined = 48

An attempt to create subscription to message without predefined limit for that message type.

Since

v.5.5.4

Definition at line 123 of file ret_code.hpp.

rc_mpsc_mbox_expected

const int so_5::rc_mpsc_mbox_expected = 190

An instance of MPSC mbox is expected as custom direct mbox.

Version 5.7.4 allows to set a custom mbox as the direct mbox for an agent. That mbox has to be MPSC mbox. An attempt to set MPMC mbox as the direct mbox will lead to this error.

Since

v.5.7.4

Definition at line 443 of file ret_code.hpp.

rc_msg_chain_doesnt_support_delivery_filters

const int so_5::rc_msg_chain_doesnt_support_delivery_filters = 163

Attempt to set delivery_filter for message chain.

Definition at line 199 of file ret_code.hpp.

rc_msg_chain_doesnt_support_subscriptions

const int so_5::rc_msg_chain_doesnt_support_subscriptions = 162

Attempt to make subscription for message chain.

Definition at line 196 of file ret_code.hpp.

rc_msg_chain_is_empty

const int so_5::rc_msg_chain_is_empty = 160

Attempt to get message from empty message queue.

Definition at line 190 of file ret_code.hpp.

rc_msg_chain_is_full

const int so_5::rc_msg_chain_is_full = 161

Attempt to push a message to full message queue.

Definition at line 193 of file ret_code.hpp.

rc_msg_chain_overflow

const int so_5::rc_msg_chain_overflow = 164

Attempt to added a message to full message chain when throw_exception overflow reaction is used.

Definition at line 203 of file ret_code.hpp.

rc_msg_tracing_disabled

const int so_5::rc_msg_tracing_disabled = 140

Message delivery tracing is disabled and cannot be used.

Definition at line 182 of file ret_code.hpp.

rc_mutable_msg_cannot_be_delivered_via_mpmc_mbox

const int so_5::rc_mutable_msg_cannot_be_delivered_via_mpmc_mbox = 172

An attempt to deliver mutable message via MPMC mbox.

Since

v.5.5.19

Definition at line 234 of file ret_code.hpp.

rc_mutable_msg_cannot_be_periodic

const int so_5::rc_mutable_msg_cannot_be_periodic = 173

An attempt to send mutable message as a periodic message.

Since

v.5.5.19

Definition at line 241 of file ret_code.hpp.

rc_negative_value_for_pause

const int so_5::rc_negative_value_for_pause = 176

An attempt to use negative value for pause argument for delayed or periodic message/signal.

A value of pause argument for so_5::send_delayed() and so_5::send_periodic() must be non-negative.

Since

v.5.5.21

Definition at line 270 of file ret_code.hpp.

rc_negative_value_for_period

const int so_5::rc_negative_value_for_period = 177

An attempt to use negative value for period argument for periodic message/signal.

A value of pause argument for so_5::send_periodic() must be non-negative.

Since

v.5.5.21

Definition at line 280 of file ret_code.hpp.

rc_no_disp_binder_for_agent

const int so_5::rc_no_disp_binder_for_agent = 195

The dispatcher binder is not set for the agent yet.

Since v.5.7.5 disp_binder is stored inside the agent. A disp_binder must be set for an agent during addition of the agent to a coop. It means that if agent is added to coop the agent should have non-null pointer to the disp_binder. If this pointer is still null then it's an error.

Since

v.5.7.5

Definition at line 505 of file ret_code.hpp.

rc_no_initial_substate

const int so_5::rc_no_initial_substate = 17

An attempt to change agent state to a new composite state which have no initial state defined.

Since

v.5.5.15

Definition at line 52 of file ret_code.hpp.

rc_no_preallocated_resources_for_agent

const int so_5::rc_no_preallocated_resources_for_agent = 193

There are no resources that must have been in place for an agent in advance.

Some dispatchers (like so_5::disp::nef_one_thread) preallocates resources necessary for normal agent work. If those resource are not found for an agent for some reason it's an error and exception with this error code is thrown.

Since

v.5.8.0

Definition at line 481 of file ret_code.hpp.

rc_not_implemented

const int so_5::rc_not_implemented = 502

Feature or method has no implementation yet.

Since

v.5.5.16

Definition at line 546 of file ret_code.hpp.

rc_null_message_data

const int so_5::rc_null_message_data = 82

Null message data.

An attempt to deliver message_t by nullptr pointer to it is an error. A signal should be used for this.

Since

v.5.2.0

Definition at line 144 of file ret_code.hpp.

rc_nullptr_as_delivery_filter_pointer

const int so_5::rc_nullptr_as_delivery_filter_pointer = 191

nullptr can't be passed as delivery_filter.

An attempt to pass nullptr pointer to a delivery_filter (or empty delivery_filter_unique_ptr_t) to a method/function that expects an actual instance of delivery_filter.

Since

v.5.8.0

Definition at line 454 of file ret_code.hpp.

rc_nullptr_as_result_of_user_mbox_factory

const int so_5::rc_nullptr_as_result_of_user_mbox_factory = 192

nullptr returned by user-provided mbox factory.

The so_5::environment_t::introduce_named_mbox() gets a user-provided mbox factory. This factory is called by SObjectizer Environment to create a new instance of the named mbox. This factory must return a valid so_5::mbox_t. If the returned so_5::mbox_t contains nullptr it's an error and this error code will be used in an exception thrown by so_5::environment_t::introduce_named_mbox().

Since

v.5.8.0

Definition at line 468 of file ret_code.hpp.

rc_operation_enabled_only_on_agent_working_thread

const int so_5::rc_operation_enabled_only_on_agent_working_thread = 16

An attempt to perform an operation which is enabled only on agent's working thread.

Since

v.5.4.0

Definition at line 44 of file ret_code.hpp.

rc_prepared_select_is_active_now

const int so_5::rc_prepared_select_is_active_now = 188

An attempt to activate prepared-select when an operation on that prepared-select object is already active.

Since

v.5.6.1

Definition at line 418 of file ret_code.hpp.

rc_priority_quote_illegal_value

const int so_5::rc_priority_quote_illegal_value = 120

Illegal value of quote for a priority.

Definition at line 174 of file ret_code.hpp.

rc_scenario_must_be_completed

const int so_5::rc_scenario_must_be_completed = 182

Testing scenario must be completed before an attempt to do the current operation.

Since

v.5.5.24

Definition at line 367 of file ret_code.hpp.

rc_several_handlers_for_one_message_type

const int so_5::rc_several_handlers_for_one_message_type = 165

Attempt to define several handlers for one msg_type.

Definition at line 206 of file ret_code.hpp.

rc_several_limits_for_one_message_type

const int so_5::rc_several_limits_for_one_message_type = 49

An attempt to define several limits for one message type.

Since

v.5.5.4

Definition at line 130 of file ret_code.hpp.

rc_state_nesting_is_too_deep

const int so_5::rc_state_nesting_is_too_deep = 18

Nesting of agent states is too deep.

Since

v.5.5.15

Definition at line 59 of file ret_code.hpp.

rc_stored_msg_inspection_result_not_found

const int so_5::rc_stored_msg_inspection_result_not_found = 198

There is no stored msg inspection result in the testing scenario.

Since

v.5.8.3

Definition at line 526 of file ret_code.hpp.

rc_stored_state_name_not_found

const int so_5::rc_stored_state_name_not_found = 183

There is no stored state name in the testing scenario.

Since

v.5.5.24

Definition at line 374 of file ret_code.hpp.

rc_subscription_to_mutable_msg_from_mpmc_mbox

const int so_5::rc_subscription_to_mutable_msg_from_mpmc_mbox = 174

An attempt to make subscription on mutable message from MPMC mbox.

Delivery of mutable messages via MPMC mboxes is prohibited.

Since

v.5.5.19

Definition at line 251 of file ret_code.hpp.

rc_transfer_to_state_loop

const int so_5::rc_transfer_to_state_loop = 178

A loop in transfer_to_state detected.

There could be a case when usage of transfer_to_state leads to a loop. For a very simple example:

class a_two_state_loop_t final : public so_5::agent_t
{
  state_t st_one{ this, "one" };
  state_t st_two{ this, "two" };
 
  struct message {};
 
public :
  a_two_state_loop_t(context_t ctx) : so_5::agent_t{ctx} {
    this >>= st_one;
 
    st_one.transfer_to_state<message>(st_two);
    st_two.transfer_to_state<message>(st_one);
  }
 
  virtual void so_evt_start() override {
    so_5::send<message>(*this);
  }
};

Since v.5.5.22.1 an attempt to handle message in the example above will lead to an exception with this error code.

Note that there could be more tricky examples when hierarchical states are used:

class a_hsm_case_t final : public so_5::agent_t
{
  state_t st_base{ this, "base" };
  state_t st_disconnected{ initial_substate_of{st_base}, "disconnected" };
  state_t st_connected{ substate_of{st_base}, "connected" };
 
  struct message {};
 
public :
  a_hsm_case_t(context_t ctx) : so_5::agent_t{ctx} {
    this >>= st_base;
 
    st_base.transfer_to_state<message>(st_disconnected);
  }
 
  virtual void so_evt_start() override {
    so_5::send<message>(*this);
  }
};

Since

v.5.5.22.1

Definition at line 337 of file ret_code.hpp.

rc_trying_to_add_extra_layer_that_already_exists_in_default_list

const int so_5::rc_trying_to_add_extra_layer_that_already_exists_in_default_list = 102

The layer is already bound to the SObjectizer Environment as a default layer.

Definition at line 158 of file ret_code.hpp.

rc_trying_to_add_extra_layer_that_already_exists_in_extra_list

const int so_5::rc_trying_to_add_extra_layer_that_already_exists_in_extra_list = 103

The layer is already bound to the SObjectizer Environment as an extra layer.

Definition at line 161 of file ret_code.hpp.

rc_trying_to_add_nullptr_extra_layer

const int so_5::rc_trying_to_add_nullptr_extra_layer = 101

Unable to bind a layer by the null pointer to it.

Definition at line 155 of file ret_code.hpp.

rc_unable_to_define_new_step

const int so_5::rc_unable_to_define_new_step = 181

New step can't be defined if testing scenario is already started or finished.

Since

v.5.5.24

Definition at line 359 of file ret_code.hpp.

rc_unable_to_join_thread_by_itself

const int so_5::rc_unable_to_join_thread_by_itself = 186

An attempt to call join() from the joinable thread itself.

Since

v.5.6.0

Definition at line 402 of file ret_code.hpp.

rc_unable_to_register_coop_during_shutdown

const int so_5::rc_unable_to_register_coop_during_shutdown = 28

It is impossible to register cooperation during SObjectizer Environment shutdown.

Since

v.5.4.0.1

Definition at line 89 of file ret_code.hpp.

rc_unable_to_start_extra_layer

const int so_5::rc_unable_to_start_extra_layer = 104

Layer initialization is failed.

Definition at line 164 of file ret_code.hpp.

rc_unexpected_error

const int so_5::rc_unexpected_error = 0xFFFFFF

Unclassified error.

Definition at line 559 of file ret_code.hpp.

rc_unknown_exception_type

const int so_5::rc_unknown_exception_type = 503

An exception of unknown type is caught.

SObjectizer expects that all exceptions are derived from std::exception class.

Since

v.5.5.24.3

Definition at line 556 of file ret_code.hpp.

skip_demands_on_dereg

demands_handling_on_dereg_t so_5::skip_demands_on_dereg

inlineconstexpr

Initial value:

=
    demands_handling_on_dereg_t::skip

Marker that tells that pending demands have to be skipped on deregistration.

Usage example:

class my_agent : public so_5::agent_t
{
public:
  my_agent(context_t ctx) : so_5::agent_t{ctx + so_5::skip_demands_on_dereg} {}
  ...
};

Since

v.5.8.5

Definition at line 213 of file agent_tuning_options.hpp.

terminate_if_throws

terminate_if_throws_t so_5::terminate_if_throws

inlineconstexpr

Value that indicates that an exception leads to the termination of the whole application.

Usage example:

class some_class {
  so_5::mchain_t ch_;
  ...
public:
  some_class(so_5::environment_t & env)
    : ch_{so_5::create_mchain(env)}
  {}
  ~some_class() noexcept
  {
    // There is no sense to allow exceptions during close operation.
    ch_->close(
        so_5::terminate_if_throws,
        so_5::mchain_props::close_mode_t::drop_content );
  }
  ...
};

Since

v.5.7.3

Definition at line 74 of file exception_control_flags.hpp.

thread_safe

const thread_safety_t so_5::thread_safe = thread_safety_t::safe

Shorthand for thread safety indicator.

Since

v.5.4.0

Examples

so_5/adv_thread_pool_fifo/main.cpp, and so_5/hardwork_imit/main.cpp.

Definition at line 69 of file types.hpp.