SObjectizer Environment. More...

#include <environment.hpp>

Inheritance diagram for so_5::environment_t:

Classes
struct	internals_t
	Internal details of SObjectizer Environment object. More...

Public Member Functions
	environment_t (environment_params_t &&so_environment_params)

virtual	~environment_t ()

	environment_t (const environment_t &)=delete

environment_t &	operator= (const environment_t &)=delete

void	call_exception_logger (const std::exception &event_exception, const coop_handle_t &coop) noexcept
	Call event exception logger for logging an exception. More...

exception_reaction_t	exception_reaction () const
	An exception reaction for the whole SO Environment. More...

error_logger_t &	error_logger () const
	Get the error_logger object. More...

template<class Agent , typename... Args>
std::unique_ptr< Agent >	make_agent (Args &&... args)
	Helper method for simplification of agents creation. More...

stats::controller_t &	stats_controller ()
	Access to controller of run-time monitoring. More...

stats::repository_t &	stats_repository ()
	Access to repository of data sources for run-time monitoring. More...

so_5::disp::abstract_work_thread_factory_shptr_t	work_thread_factory () const noexcept
	Access to the global work thread factory. More...

template<typename... Args>
decltype(auto)	introduce_coop (Args &&... args)
	Helper method for simplification of cooperation creation and registration. More...

work_thread_activity_tracking_t	work_thread_activity_tracking () const
	Get activity tracking flag for the whole SObjectizer Environment. More...

disp_binder_shptr_t	so_make_default_disp_binder ()
	Get binding to the default dispatcher. More...

bool	autoshutdown_disabled () const
	Get autoshutdown_disabled flag. More...

so_5::timer_id_t	so_schedule_timer (const low_level_api::schedule_timer_params_t params)
	Schedule timer event. More...

void	so_single_timer (const low_level_api::single_timer_params_t params)
	Schedule a single shot timer event. More...

template<typename Lambda >
mbox_t	make_custom_mbox (Lambda &&lambda)
	Create a custom mbox. More...

Methods for working with mboxes.
mbox_t	create_mbox ()
	Create an anonymous mbox with the default mutex. More...

mbox_t	create_mbox (nonempty_name_t mbox_name)
	Create named mbox. More...

Method for working with message chains.
mchain_t	create_mchain (const mchain_params_t &params)
	Create message chain. More...

Method for working with dispatchers.
void	install_exception_logger (event_exception_logger_unique_ptr_t logger)
	Set up an exception logger. More...

Methods for working with cooperations.
coop_unique_holder_t	make_coop ()
	Create a cooperation. More...

coop_unique_holder_t	make_coop (disp_binder_shptr_t disp_binder)
	Create a cooperation with specified dispatcher binder. More...

coop_unique_holder_t	make_coop (coop_handle_t parent)
	Create a new cooperation that will be a child for specified parent coop. More...

coop_unique_holder_t	make_coop (coop_handle_t parent, disp_binder_shptr_t disp_binder)
	Create a new cooperation that will be a child for specified parent coop. More...

coop_handle_t	register_coop (coop_unique_holder_t agent_coop)
	Register a cooperation. More...

template<class A >
coop_handle_t	register_agent_as_coop (std::unique_ptr< A > agent)
	Register single agent as a cooperation. More...

template<class A >
coop_handle_t	register_agent_as_coop (std::unique_ptr< A > agent, disp_binder_shptr_t disp_binder)
	Register single agent as a cooperation with specified dispatcher binder. More...

void	deregister_coop (coop_handle_t coop, int reason) noexcept
	Deregister the cooperation. More...

Methods for working with layers.
template<class SO_Layer >
SO_Layer *	query_layer_noexcept () const

template<class SO_Layer >
SO_Layer *	query_layer () const
	Get access to the layer with exception if layer is not found. More...

template<class SO_Layer >
void	add_extra_layer (std::unique_ptr< SO_Layer > layer_ptr)
	Add an additional layer. More...

Methods for starting, initializing and stopping of the Run-Time.
void	run ()
	Run the SObjectizer Run-Time. More...

virtual void	init ()=0
	Initialization hook. More...

void	stop ()
	Send a shutdown signal to the Run-Time. More...

Methods for working with stop_guards.
stop_guard_t::setup_result_t	setup_stop_guard (stop_guard_shptr_t guard, stop_guard_t::what_if_stop_in_progress_t reaction_on_stop_in_progress=stop_guard_t::what_if_stop_in_progress_t::throw_exception)
	Set up a new stop_guard. More...

void	remove_stop_guard (stop_guard_shptr_t guard)
	Remove stop_guard and complete the stop operation if necessary. More...

Methods for working with msg_tracing's filters.
void	change_message_delivery_tracer_filter (so_5::msg_tracing::filter_shptr_t filter)
	Change the current msg_tracing's filter to a new one. More...

Private Member Functions
environment_t &	self_ref ()
	Auxiliary methods for getting reference to itself. More...

layer_t *	query_layer (const std::type_index &type) const
	Access to an additional layer. More...

void	add_extra_layer (const std::type_index &type, const layer_ref_t &layer)
	Add an additional layer. More...

void	remove_extra_layer (const std::type_index &type)
	Remove an additional layer. More...

mbox_t	do_make_custom_mbox (custom_mbox_details::creator_iface_t &creator)
	Actual creation of a custom mbox. More...

Implementation details related to run/stop functionality.
void	imp_run_stats_controller_and_go_further ()
	Run controller for run-time monitoring and call next run stage. More...

void	imp_run_layers_and_go_further ()
	Run layers and call next run stage. More...

void	imp_run_infrastructure ()
	Launch environment infrastructure and wait for finish. More...

Private Attributes
std::unique_ptr< internals_t >	m_impl
	SObjectizer Environment internals. More...

Friends
class	so_5::impl::internal_env_iface_t

Detailed Description

SObjectizer Environment.

Basic information

The SObjectizer Environment provides a basic infrastructure for the SObjectizer Run-Time execution.

The main method of starting SObjectizer Environment creates a class derived from the environment_t and reimplementing the environment_t::init() method. This method should be used to define starting actions of application. For example first application cooperations can be registered here and starting messages can be sent to them.

The SObjectizer Environment calls the environment_t::init() when the SObjectizer Run-Time is successfully started. If something happened during the Run-Time startup then the method init() will not be called.

The SObjectizer Run-Time is started by the environment_t::run(). This method blocks the caller thread until SObjectizer completely finished its work.

The SObjectizer Run-Time is finished by the environment_t::stop(). This method doesn't block the caller thread. Instead it sends a special shutdown signal to the Run-Time. The SObjectizer Run-Time then informs agents about this and waits finish of agents work. The SObjectizer Run-Time finishes if all agents are stopped and all cooperations are deregistered.

Methods of the SObjectizer Environment can be splitted into the following groups:

working with mboxes;
working with dispatchers, exception loggers and handlers;
working with cooperations;
working with delayed and periodic messages;
working with additional layers;
initializing/running/stopping/waiting of the Run-Time.

Methods for working with mboxes.

SObjectizer Environment allows creation of named and anonymous mboxes. Syncronization objects for these mboxes can be obtained from common pools or assigned by a user during mbox creation.

Mboxes are created by environment_t::create_mbox() methods. All these methods return the mbox_t which is a smart reference to the mbox.

An anonymous mbox is automatically destroyed when the last reference to it is destroyed. So, to save the anonymous mbox, the mbox_ref from the create_mbox() should be stored somewhere.

Methods for working with cooperations.

Cooperations can be created by environment_t::make_coop() methods.

The method environment_t::register_coop() should be used for the cooperation registration.

Method environment_t::deregister_coop() should be used for the cooperation deregistration.

Examples:: so_5/adv_thread_pool_fifo/main.cpp, so_5/blinking_led/main.cpp, so_5/chameneos_prealloc_msgs/main.cpp, so_5/chameneos_simple/main.cpp, so_5/chstate/main.cpp, so_5/chstate_msg_tracing/main.cpp, so_5/coop_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_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/intercom_statechart/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/state_deep_history/main.cpp, so_5/stop_guard/main.cpp, so_5/subscriptions/main.cpp, and so_5/two_handlers/main.cpp.

Constructor & Destructor Documentation

◆ environment_t() [1/2]

so_5::environment_t::environment_t ( environment_params_t && so_environment_params )

explicit

Parameters

so_environment_params Initialization params.

◆ ~environment_t()

so_5::environment_t::~environment_t ( )

virtual

◆ environment_t() [2/2]

so_5::environment_t::environment_t ( const environment_t & )

delete

Member Function Documentation

◆ add_extra_layer() [1/2]

template<class SO_Layer >

void so_5::environment_t::add_extra_layer ( std::unique_ptr< SO_Layer > layer_ptr )

inline

Add an additional layer.

◆ add_extra_layer() [2/2]

void so_5::environment_t::add_extra_layer	(	const std::type_index &	type,
		const layer_ref_t &	layer
	)

private

Add an additional layer.

◆ autoshutdown_disabled()

bool so_5::environment_t::autoshutdown_disabled ( ) const

Get autoshutdown_disabled flag.

Autoshutdown feature is on by default. It can be turned off in environment_params_t. This methods returns true if autoshutdown is turned off.

Since: v.5.5.19

◆ call_exception_logger()

void so_5::environment_t::call_exception_logger	(	const std::exception &	event_exception,
		const coop_handle_t &	coop
	)

noexcept

Call event exception logger for logging an exception.

Note: Since v.5.6.0 this method is marked as noexcept.

Since: v.5.2.3.

Parameters

event_exception	Exception caught.
coop	A cooperation to which agent is belong.

◆ change_message_delivery_tracer_filter()

void so_5::environment_t::change_message_delivery_tracer_filter ( so_5::msg_tracing::filter_shptr_t filter )

Change the current msg_tracing's filter to a new one.

Usage example:

so_5::launch([](so_5::environment_t & env) {...},
  [](so_5::environment_params_t & params) {
    // Turn message delivery tracing on.
    params.message_delivery_tracer(
      so_5::msg_tracing::std_cout_tracer());
    // Disable all trace messages.
    // It is expected that trace filter will be changed in the future.
    params.message_delivery_tracer_filter(
      so_5::msg_tracing::make_disable_all_filter());
    ...
  } );
...
void some_agent_t::turn_msg_tracing_on() {
  // Remove trace filter. As result all trace messages will be printed.
  so_environment().change_message_delivery_tracer_filter(
    so_5::msg_tracing::no_filter());
  ...
}

Note: It is possible that there are active calls to so_5::msg_tracing::filter_t::filter() methods at the time of invocation of change_message_delivery_tracer_filter(). In this case all active calls will be completed with the previous filter. This could lead to mixture of messages in the trace: some of them will be enabled by old filter and some of them will be enabled by new filter. And it is possible that messages enabled by new filter will precede messages enabled by old filter.

Exceptions

exception_t if message delivery tracing is disabled.

Since: v.5.5.22

Parameters

filter A new filter to be used. It can be an empty pointer. In this case all trace messages will be passed to tracer object.

◆ create_mbox() [1/2]

mbox_t so_5::environment_t::create_mbox ( )

Create an anonymous mbox with the default mutex.

Note: always creates a new mbox.

Examples:: so_5/adv_thread_pool_fifo/main.cpp, so_5/custom_work_thread_factory/main.cpp, so_5/intercom_statechart/main.cpp, so_5/machine_control/main.cpp, so_5/news_board/main.cpp, so_5/ping_pong/main.cpp, so_5/ping_pong_minimal/main.cpp, so_5/prio_work_stealing/main.cpp, so_5/producer_consumer_mchain/main.cpp, and so_5/wrapped_env_demo_2/main.cpp.

◆ create_mbox() [2/2]

mbox_t so_5::environment_t::create_mbox ( nonempty_name_t mbox_name )

Create named mbox.

If mbox_name is unique then a new mbox will be created. If not the reference to existing mbox will be returned.

Parameters

mbox_name Mbox name.

◆ create_mchain()

mchain_t so_5::environment_t::create_mchain ( const mchain_params_t & params )

Create message chain.

Since: v.5.5.13

Usage examples:: so_5::environment_t & env = ...;
// Create mchain with size-unlimited queue.
auto ch1 = env.create_mchain(
so_5::make_unlimited_mchain_params() );
// Create mchain with size-limited queue without a timeout
// on attempt to push another message to full mchain...
auto ch2 = env.create_mchain(
so_5::make_limited_without_waiting_mchain_params(
// ...maximum size of the chain.
100,
// ...memory for chain will be allocated and deallocated dynamically...
so_5::mchain_props::memory_usage_t::dynamic,
// ...an exception will be thrown on overflow.
so_5::mchain_props::overflow_reaction_t::throw_exception ) );
// Create mchain with size-limited queue with a timeout for 200ms
// on attempt to push another message to full mchain...
auto ch3 = env.create_mchain(
so_5::make_limited_with_waiting_mchain_params(
// ...maximum size of the chain.
100,
// ...memory for chain will be preallocated...
so_5::mchain_props::memory_usage_t::preallocated,
// ...an oldest message from mchain will be removed on overflow...
so_5::mchain_props::overflow_reaction_t::remove_oldest,
// ...timeout for waiting on attempt to push a message into full mchain.
std::chrono::milliseconds(200) ) );
// Create size-unlimited mchain with custom notificator for
// 'not_empty' situations.
auto ch4 = env.create_mchain(
so_5::make_unlimited_mchain_params().not_empty_notificator(
[&] { some_widget.send_notify(); } ) );

Parameters

params Parameters for a new bag.

Examples:: so_5/producer_consumer_mchain/main.cpp.

◆ deregister_coop()

void so_5::environment_t::deregister_coop	(	coop_handle_t	coop,
		int	reason
	)

inlinenoexcept

Deregister the cooperation.

Method searches the cooperation within registered cooperations and if it is found deregisters it.

Deregistration can take some time.

At first a special signal is sent to cooperation agents. By receiving these signal agents stop receiving new messages. When the local event queue for an agent becomes empty the agent informs the cooperation about this. When the cooperation receives all these signals from agents it informs the SObjectizer Run-Time.

Only after this the cooperation is deregistered on the special context.

After the cooperation deregistration agents are unbound from dispatchers.

Note: This method is marked as noexcept because there is no way to recover if any exception is raised here.

Parameters

coop	The coop to be deregistered.
reason	Deregistration reason.

Examples:: so_5/ping_pong_with_owner/main.cpp.

◆ do_make_custom_mbox()

mbox_t so_5::environment_t::do_make_custom_mbox ( custom_mbox_details::creator_iface_t & creator )

private

Actual creation of a custom mbox.

Since: v.5.5.19.2

◆ error_logger()

error_logger_t & so_5::environment_t::error_logger ( ) const

Get the error_logger object.

Since: v.5.5.0

◆ exception_reaction()

exception_reaction_t so_5::environment_t::exception_reaction ( ) const

An exception reaction for the whole SO Environment.

Since: v.5.3.0

◆ imp_run_infrastructure()

void so_5::environment_t::imp_run_infrastructure ( )

private

Launch environment infrastructure and wait for finish.

Since: v.5.5.19

◆ imp_run_layers_and_go_further()

void so_5::environment_t::imp_run_layers_and_go_further ( )

private

Run layers and call next run stage.

◆ imp_run_stats_controller_and_go_further()

void so_5::environment_t::imp_run_stats_controller_and_go_further ( )

private

Run controller for run-time monitoring and call next run stage.

Since: v.5.5.4

◆ init()

virtual void so_5::environment_t::init ( )

pure virtual

Initialization hook.

Attention: A hang inside of this method will prevent the Run-Time from stopping. For example if a dialog with an application user is performed inside init() then SObjectizer cannot finish its work until this dialog is finished.

Implemented in so_5::impl::so_quick_environment_t< Init >, and so_5::anonymous_namespace{wrapped_env.cpp}::actual_environment_t.

◆ install_exception_logger()

void so_5::environment_t::install_exception_logger ( event_exception_logger_unique_ptr_t logger )

Set up an exception logger.

Examples:: so_5/exception_logger/main.cpp.

◆ introduce_coop()

template<typename... Args>

decltype(auto) so_5::environment_t::introduce_coop ( Args &&... args )

Helper method for simplification of cooperation creation and registration.

Returns: The value returned from lambda-function. Or void if the lambda-function returns void.

Since: v.5.5.5

Usage samples:: // The default dispatcher will be used for binding.
env.introduce_coop( []( so_5::coop_t & coop ) {
coop.make_agent< first_agent >(...);
coop.make_agent< second_agent >(...);
});
// For the case when dispatcher binder is specified.
env.introduce_coop(
so_5::disp::active_obj::make_dispatcher( env ).binder(),
[]( so_5::coop_t & coop ) {
coop.make_agent< first_agent >(...);
coop.make_agent< second_agent >(...);
} );
// Usage of return value from the lambda function.
so_5::mbox_t mbox = env.introduce_coop( [](so_5::coop_t & coop) {
auto * a = coop.make_agent< first_agent >(...);
coop.make_agent< second_agent >(...);
return a->so_direct_mbox();
});

Examples:: so_5/adv_thread_pool_fifo/main.cpp, so_5/blinking_led/main.cpp, so_5/chameneos_prealloc_msgs/main.cpp, so_5/chameneos_simple/main.cpp, so_5/chstate_msg_tracing/main.cpp, so_5/coop_user_resources/main.cpp, so_5/custom_direct_mbox/main.cpp, so_5/custom_work_thread_factory/main.cpp, so_5/default_message_limits/main.cpp, so_5/disp/main.cpp, so_5/hello_all/main.cpp, so_5/hello_world_simple_not_mtsafe/main.cpp, so_5/intercom_statechart/main.cpp, so_5/machine_control/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/news_board/main.cpp, so_5/nohandler_msg_tracing/main.cpp, so_5/ping_pong/main.cpp, so_5/ping_pong_minimal/main.cpp, so_5/prio_work_stealing/main.cpp, so_5/producer_consumer_mchain/main.cpp, so_5/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/state_deep_history/main.cpp, so_5/stop_guard/main.cpp, and so_5/wrapped_env_demo_2/main.cpp.

◆ make_agent()

template<class Agent , typename... Args>

std::unique_ptr< Agent > so_5::environment_t::make_agent ( Args &&... args )

inline

Helper method for simplification of agents creation.

Since: v.5.5.4

Note: Creates an instance of agent of type Agent by using environment_t::make_agent() template function and adds it to the cooperation. Uses the fact that most agent types use reference to the environment object as the first argument.

Returns: unique pointer to the new agent.

Template Parameters

Agent	type of agent to be created.
Args	type of parameters list for agent constructor.

Usage sample:: so_5::environment_t & env = ...;
// For the case of constructor like my_agent(environmen_t&).
auto a1 = env.make_agent< my_agent >();
// For the case of constructor like your_agent(environment_t&, std::string).
auto a2 = env.make_agent< your_agent >( "hello" );
// For the case of constructor like their_agent(environment_t&, std::string, mbox_t).
auto a3 = env.make_agent< their_agent >( "bye", a2->so_direct_mbox() );

Examples:: so_5/chstate/main.cpp, so_5/coop_listener/main.cpp, so_5/coop_notification/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/delivery_filters/main.cpp, so_5/dispatcher_for_children/main.cpp, so_5/dispatcher_hello/main.cpp, so_5/dispatcher_restarts/main.cpp, so_5/exception_logger/main.cpp, so_5/exception_reaction/main.cpp, so_5/hello_delay/main.cpp, so_5/hello_evt_handler/main.cpp, so_5/hello_evt_lambda/main.cpp, so_5/hello_periodic/main.cpp, so_5/hello_world/main.cpp, so_5/make_agent_ref/main.cpp, so_5/make_new_direct_mbox/main.cpp, so_5/make_pipeline/main.cpp, so_5/named_dispatchers_layer/main.cpp, so_5/parent_coop/main.cpp, so_5/ping_pong_with_owner/main.cpp, so_5/subscriptions/main.cpp, and so_5/two_handlers/main.cpp.

◆ make_coop() [1/4]

coop_unique_holder_t so_5::environment_t::make_coop ( )

Create a cooperation.

Returns: A new cooperation. This cooperation will use default dispatcher binders.

Since: v.5.6.0

Examples:: so_5/hardwork_imit/main.cpp.

◆ make_coop() [2/4]

coop_unique_holder_t so_5::environment_t::make_coop ( disp_binder_shptr_t disp_binder )

Create a cooperation with specified dispatcher binder.

A binder disp_binder will be used for binding cooperation agents to the dispatcher. This binder will be default binder for this cooperation.

so_5::environment_t & so_env = ...;
so_5::coop_unique_holder_t coop = so_env.make_coop(
  so_5::disp::active_group::make_dispatcher( so_env ).binder(
    "some_active_group" ) );
// That agent will be bound to the dispatcher "active_group"
// and will be member of an active group with name
// "some_active_group".
coop->make_agent< a_some_agent_t >();

Since: v.5.6.0

Parameters

disp_binder A default binder for this cooperation.

◆ make_coop() [3/4]

coop_unique_holder_t so_5::environment_t::make_coop ( coop_handle_t parent )

Create a new cooperation that will be a child for specified parent coop.

The new cooperation will use the default dispatcher binder.

Usage example:

class parent_t final : public so_5::agent_t {
  void on_some_event(mhood_t<some_message>) {
    // We need to create a child coop.
    auto coop = so_environment().make_coop(
        // We as a parent.
        so_coop());
    ...
  }
};

Since: v.5.6.0

Parameters

parent Parent coop.

◆ make_coop() [4/4]

coop_unique_holder_t so_5::environment_t::make_coop	(	coop_handle_t	parent,
		disp_binder_shptr_t	disp_binder
	)

Create a new cooperation that will be a child for specified parent coop.

The new cooperation will use the specified dispatcher binder.

Usage example:

class parent_t final : public so_5::agent_t {
  void on_some_event(mhood_t<some_message>) {
    // We need to create a child coop.
    auto coop = so_environment().make_coop(
        // We as a parent.
        so_coop(),
        // The default dispatcher for the new coop.
        so_5::disp::active_obj::make_dispatcher(
            so_environment() ).binder() );
    ...
  }
};

Since: v.5.6.0

Parameters

parent	Parent coop.
disp_binder	A default binder for this cooperation.

◆ make_custom_mbox()

template<typename Lambda >

mbox_t so_5::environment_t::make_custom_mbox ( Lambda && lambda )

inline

Create a custom mbox.

Template Parameters

Lambda

type of actual lambda with all creation actions. The Lambda must be lambda-function or functional objects with the following format:

so_5::mbox_t lambda(const so_5::mbox_creation_data_t &);

Since: v.5.5.19.2

◆ operator=()

environment_t& so_5::environment_t::operator= ( const environment_t & )

delete

◆ query_layer() [1/2]

template<class SO_Layer >

SO_Layer* so_5::environment_t::query_layer ( ) const

inline

Get access to the layer with exception if layer is not found.

Examples:: so_5/named_dispatchers_layer/main.cpp.

◆ query_layer() [2/2]

layer_t * so_5::environment_t::query_layer ( const std::type_index & type ) const

private

Access to an additional layer.

◆ query_layer_noexcept()

template<class SO_Layer >

SO_Layer* so_5::environment_t::query_layer_noexcept ( ) const

inline

Get access to the layer without raising exception if layer is not found.

◆ register_agent_as_coop() [1/2]

template<class A >

coop_handle_t so_5::environment_t::register_agent_as_coop ( std::unique_ptr< A > agent )

inline

Register single agent as a cooperation.

It is just a helper methods for convience.

Usage sample:

std::unique_ptr< my_agent > a( new my_agent(...) );

so_env.register_agent_as_coop( std::move(a) );

Examples:: so_5/chstate/main.cpp, so_5/coop_listener/main.cpp, so_5/coop_notification/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/delivery_filters/main.cpp, so_5/dispatcher_for_children/main.cpp, so_5/dispatcher_hello/main.cpp, so_5/dispatcher_restarts/main.cpp, so_5/exception_logger/main.cpp, so_5/exception_reaction/main.cpp, so_5/hello_delay/main.cpp, so_5/hello_evt_handler/main.cpp, so_5/hello_evt_lambda/main.cpp, so_5/hello_periodic/main.cpp, so_5/hello_world/main.cpp, so_5/make_agent_ref/main.cpp, so_5/make_new_direct_mbox/main.cpp, so_5/make_pipeline/main.cpp, so_5/named_dispatchers_layer/main.cpp, so_5/parent_coop/main.cpp, so_5/ping_pong_with_owner/main.cpp, so_5/subscriptions/main.cpp, and so_5/two_handlers/main.cpp.

◆ register_agent_as_coop() [2/2]

template<class A >

coop_handle_t so_5::environment_t::register_agent_as_coop	(	std::unique_ptr< A >	agent,
		disp_binder_shptr_t	disp_binder
	)

inline

Register single agent as a cooperation with specified dispatcher binder.

Since: v.5.2.1

It is just a helper methods for convience.

Usage sample:

so_env.register_agent_as_coop(
  std::make_unique<my_agent>(...),
    so_5::disp::active_group::create_disp_binder(
        "active_group",
        "some_active_group" ) );

◆ register_coop()

coop_handle_t so_5::environment_t::register_coop ( coop_unique_holder_t agent_coop )

Register a cooperation.

The cooperation registration includes following steps:

binding agents to the cooperation object;
checking uniques of the cooperation name. The cooperation will not be registered if its name isn't unique;
agent_t::so_define_agent() will be called for each agent in the cooperation;
binding of each agent to the dispatcher.

If all these actions are successful then the cooperation is marked as registered.

Parameters

agent_coop Cooperation to be registered.

Examples:: so_5/dispatcher_hello/main.cpp, so_5/dispatcher_restarts/main.cpp, so_5/hardwork_imit/main.cpp, so_5/make_pipeline/main.cpp, and so_5/ping_pong_with_owner/main.cpp.

◆ remove_extra_layer()

void so_5::environment_t::remove_extra_layer ( const std::type_index & type )

private

Remove an additional layer.

◆ remove_stop_guard()

void so_5::environment_t::remove_stop_guard ( stop_guard_shptr_t guard )

Remove stop_guard and complete the stop operation if necessary.

Every stop_guard which was added to the environment must be explicitely removed from the environment. It is done by this method. If there is no more stop_guard and the stop operation is in progress then the environment will complete the stop operation.

Usage examples:

// Note: an exception can be thrown if stop is in progress
class my_stop_guard
  : public so_5::stop_guard_t
  , public std::enable_shared_from_this< my_stop_guard >
{...};
class my_agent : public so_5::agent_t
{
  ...
  void on_some_event()
  {
    // We need a stop_guard here.
    m_my_guard = std::make_shared< my_stop_guard >(...);
    so_environment().setup_stop_guard( m_my_guard );
  }
  void on_work_finished_signal()
  {
    // Stop_guard must be removed now.
    so_environment().remove_stop_guard( m_my_guard );
  }
private :
  so_5::stop_guard_shptr_t m_my_guard;
};

Since: v.5.5.19.2

Parameters

guard Stop guard to be removed.

Examples:: so_5/stop_guard/main.cpp.

◆ run()

void so_5::environment_t::run ( )

Run the SObjectizer Run-Time.

◆ self_ref()

environment_t & so_5::environment_t::self_ref ( )

private

Auxiliary methods for getting reference to itself.

Could be used in constructors without compiler warnings.

◆ setup_stop_guard()

stop_guard_t::setup_result_t so_5::environment_t::setup_stop_guard	(	stop_guard_shptr_t	guard,
		stop_guard_t::what_if_stop_in_progress_t	reaction_on_stop_in_progress = `stop_guard_t::what_if_stop_in_progress_t::throw_exception`
	)

Set up a new stop_guard.

Usage examples:

// Add a stop_guard.
// Note: an exception can be thrown if stop is in progress
class my_stop_guard
  : public so_5::stop_guard_t
  , public std::enable_shared_from_this< my_stop_guard >
{...};
class my_agent : public so_5::agent_t
{
  ...
  void on_some_event()
  {
    // We need a stop_guard here.
    m_my_guard = std::make_shared< my_stop_guard >(...);
    so_environment().setup_stop_guard( m_my_guard );
  }
private :
  so_5::stop_guard_shptr_t m_my_guard;
};
//
// Add a stop_guard without throwing an exception if stop is in progress
//
class my_stop_guard
  : public so_5::stop_guard_t
  , public std::enable_shared_from_this< my_stop_guard >
{...};
class my_agent : public so_5::agent_t
{
  ...
  void on_some_event()
  {
    // We need a stop_guard here.
    m_my_guard = std::make_shared< my_stop_guard >(...);
    const auto r = so_environment().setup_stop_guard(
        m_my_guard,
        so_5::stop_guard_t::what_if_stop_in_progress_t::return_negative_result );
    if( so_5::stop_guard_t::setup_result_t::stop_already_in_progress  == r )
      ... // handle error here.
  }
private :
  so_5::stop_guard_shptr_t m_my_guard;
};

Note: Uniqueness of stop_guard is not checked. It means that it is possible to add the same stop_guard several times. But it seems to be useless.

Since: v.5.5.19.2

Parameters

guard	Stop guard to be set. Should not be nullptr.
reaction_on_stop_in_progress	What to do is the stop operation is already in progress?

Examples:: so_5/stop_guard/main.cpp.

◆ so_make_default_disp_binder()

disp_binder_shptr_t so_5::environment_t::so_make_default_disp_binder ( )

Get binding to the default dispatcher.

Note: This method is part of environment_t for possibility to write custom implementations of environment_infrastructure_t. Because of that this method can be changed or removed in future versions of SObjectizer.

Since: v.5.5.19

◆ so_schedule_timer()

so_5::timer_id_t so_5::environment_t::so_schedule_timer ( const low_level_api::schedule_timer_params_t params )

Schedule timer event.

Attention: Values of pause and period should be non-negative.

Note: This method is a part of low-level SObjectizer's API. Because of that it can be changed or removed in some future version of SObjectizer without prior notice.

Parameters

params Parameters for new timer.

◆ so_single_timer()

void so_5::environment_t::so_single_timer ( const low_level_api::single_timer_params_t params )

Schedule a single shot timer event.

Attention: Value of pause should be non-negative.

Note: This method is a part of low-level SObjectizer's API. Because of that it can be changed or removed in some future version of SObjectizer without prior notice.

Parameters

params Parameters for new timer.

◆ stats_controller()

stats::controller_t & so_5::environment_t::stats_controller ( )

Access to controller of run-time monitoring.

Since: v.5.5.4

Examples:: so_5/queue_size_stats/main.cpp.

◆ stats_repository()

stats::repository_t & so_5::environment_t::stats_repository ( )

Access to repository of data sources for run-time monitoring.

Since: v.5.5.4

◆ stop()

void so_5::environment_t::stop ( )

Send a shutdown signal to the Run-Time.

Examples:: so_5/adv_thread_pool_fifo/main.cpp, so_5/blinking_led/main.cpp, so_5/chameneos_prealloc_msgs/main.cpp, so_5/chameneos_simple/main.cpp, so_5/coop_listener/main.cpp, so_5/disp/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/hello_periodic/main.cpp, so_5/hello_world/main.cpp, so_5/parent_coop/main.cpp, so_5/ping_pong/main.cpp, so_5/ping_pong_minimal/main.cpp, so_5/queue_size_stats/main.cpp, so_5/redirect_and_transform/main.cpp, and so_5/stop_guard/main.cpp.

◆ work_thread_activity_tracking()

work_thread_activity_tracking_t so_5::environment_t::work_thread_activity_tracking ( ) const

Get activity tracking flag for the whole SObjectizer Environment.

Since: v.5.5.18

◆ work_thread_factory()

so_5::disp::abstract_work_thread_factory_shptr_t so_5::environment_t::work_thread_factory ( ) const

noexcept

Access to the global work thread factory.

Since: v.5.7.3

Friends And Related Function Documentation

◆ so_5::impl::internal_env_iface_t

friend class so_5::impl::internal_env_iface_t

friend

Member Data Documentation

◆ m_impl

std::unique_ptr< internals_t > so_5::environment_t::m_impl

private

SObjectizer Environment internals.

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

Classes

Public Member Functions

Private Member Functions

Private Attributes

Friends

Detailed Description

Basic information

Methods for working with mboxes.

Methods for working with cooperations.

Constructor & Destructor Documentation

◆ environment_t() [1/2]

◆ ~environment_t()

◆ environment_t() [2/2]

Member Function Documentation

◆ add_extra_layer() [1/2]

◆ add_extra_layer() [2/2]

◆ autoshutdown_disabled()

◆ call_exception_logger()

◆ change_message_delivery_tracer_filter()

◆ create_mbox() [1/2]

◆ create_mbox() [2/2]

◆ create_mchain()

◆ deregister_coop()

◆ do_make_custom_mbox()

◆ error_logger()

◆ exception_reaction()

◆ imp_run_infrastructure()

◆ imp_run_layers_and_go_further()

◆ imp_run_stats_controller_and_go_further()

◆ init()

◆ install_exception_logger()

◆ introduce_coop()

◆ make_agent()

◆ make_coop() [1/4]

◆ make_coop() [2/4]

◆ make_coop() [3/4]

◆ make_coop() [4/4]

◆ make_custom_mbox()

◆ operator=()

◆ query_layer() [1/2]

◆ query_layer() [2/2]

◆ query_layer_noexcept()

◆ register_agent_as_coop() [1/2]

◆ register_agent_as_coop() [2/2]

◆ register_coop()

◆ remove_extra_layer()

◆ remove_stop_guard()

◆ run()

◆ self_ref()

◆ setup_stop_guard()

◆ so_make_default_disp_binder()

◆ so_schedule_timer()

◆ so_single_timer()

◆ stats_controller()

◆ stats_repository()

◆ stop()

◆ work_thread_activity_tracking()

◆ work_thread_factory()

Friends And Related Function Documentation

◆ so_5::impl::internal_env_iface_t

Member Data Documentation

◆ m_impl