so_5::environment_t Class Reference

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.
exception_reaction_t	exception_reaction () const noexcept
	An exception reaction for the whole SO Environment.
error_logger_t &	error_logger () const
	Get the error_logger object.
template<class Agent , typename... Args>
std::unique_ptr< Agent >	make_agent (Args &&... args)
	Helper method for simplification of agents creation.
stats::controller_t &	stats_controller ()
	Access to controller of run-time monitoring.
stats::repository_t &	stats_repository ()
	Access to repository of data sources for run-time monitoring.
so_5::disp::abstract_work_thread_factory_shptr_t	work_thread_factory () const noexcept
	Access to the global work thread factory.
template<typename... Args>
decltype(auto)	introduce_coop (Args &&... args)
	Helper method for simplification of cooperation creation and registration.
work_thread_activity_tracking_t	work_thread_activity_tracking () const
	Get activity tracking flag for the whole SObjectizer Environment.
disp_binder_shptr_t	so_make_default_disp_binder ()
	Get binding to the default dispatcher.
bool	autoshutdown_disabled () const
	Get autoshutdown_disabled flag.
so_5::timer_id_t	so_schedule_timer (const low_level_api::schedule_timer_params_t params)
	Schedule timer event.
void	so_single_timer (const low_level_api::single_timer_params_t params)
	Schedule a single shot timer event.
template<typename Lambda >
mbox_t	make_custom_mbox (Lambda &&lambda)
	Create a custom mbox.
Methods for working with mboxes.
mbox_t	create_mbox ()
	Create an anonymous MPMC mbox.
mbox_t	create_mbox (nonempty_name_t mbox_name)
	Create named MPMC mbox.
mbox_t	introduce_named_mbox (mbox_namespace_name_t mbox_namespace, nonempty_name_t mbox_name, const std::function< mbox_t() > &mbox_factory)
	Introduce named mbox with user-provided factory.
Method for working with message chains.
mchain_t	create_mchain (const mchain_params_t &params)
	Create message chain.
Method for working with dispatchers.
void	install_exception_logger (event_exception_logger_unique_ptr_t logger)
	Set up an exception logger.
Methods for working with cooperations.
coop_unique_holder_t	make_coop ()
	Create a cooperation.
coop_unique_holder_t	make_coop (disp_binder_shptr_t disp_binder)
	Create a cooperation with specified dispatcher binder.
coop_unique_holder_t	make_coop (coop_handle_t parent)
	Create a new cooperation that will be a child for specified parent coop.
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.
coop_handle_t	register_coop (coop_unique_holder_t agent_coop)
	Register a cooperation.
template<class A >
coop_handle_t	register_agent_as_coop (std::unique_ptr< A > agent)
	Register single agent as a cooperation.
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.
void	deregister_coop (coop_handle_t coop, int reason) noexcept
	Deregister the cooperation.
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.
template<class SO_Layer >
void	add_extra_layer (std::unique_ptr< SO_Layer > layer_ptr)
	Add an additional layer.
Methods for starting, initializing and stopping of the Run-Time.
void	run ()
	Run the SObjectizer Run-Time.
virtual void	init ()=0
	Initialization hook.
void	stop () noexcept
	Send a shutdown signal to the Run-Time.
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.
void	remove_stop_guard (stop_guard_shptr_t guard)
	Remove stop_guard and complete the stop operation if necessary.
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.

Private Member Functions
environment_t &	self_ref ()
	Auxiliary methods for getting reference to itself.
layer_t *	query_layer (const std::type_index &type) const
	Access to an additional layer.
void	add_extra_layer (const std::type_index &type, const layer_ref_t &layer)
	Add an additional layer.
void	remove_extra_layer (const std::type_index &type)
	Remove an additional layer.
mbox_t	do_make_custom_mbox (custom_mbox_details::creator_iface_t &creator)
	Actual creation of a custom mbox.
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.
void	imp_run_layers_and_go_further ()
	Run layers and call next run stage.
void	imp_run_infrastructure ()
	Launch environment infrastructure and wait for finish.

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

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

Definition at line 955 of file environment.hpp.

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.

Definition at line 513 of file environment.cpp.

~environment_t()

so_5::environment_t::~environment_t ( )

virtual

Definition at line 519 of file environment.cpp.

environment_t() [2/2]

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

delete

Member Function Documentation

add_extra_layer() [1/2]

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

private

Add an additional layer.

Definition at line 693 of file environment.cpp.

add_extra_layer() [2/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.

Definition at line 1606 of file environment.hpp.

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

Definition at line 783 of file environment.cpp.

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.

Definition at line 731 of file environment.cpp.

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.

Examples

so_5/selective_msg_tracing/main.cpp.

Definition at line 824 of file environment.cpp.

create_mbox() [1/2]

mbox_t so_5::environment_t::create_mbox ( )

nodiscard

Create an anonymous MPMC mbox.

Usage example:

class my_agent final : public so_5::agent_t {
  const so_5::mbox_t broadcast_mbox_;
  ...
public:
  my_agent(context_t ctx)
    : so_5::agent_t{std::move(ctx)}
    , broadcast_mbox_{so_environment().create_mbox()}
  {}
  ...
};

Note

always creates a new mbox.

Examples

so_5/adv_thread_pool_fifo/main.cpp, so_5/bind_transformer/main.cpp, so_5/custom_work_thread_factory/main.cpp, so_5/individual_msg_tracing/main.cpp, so_5/intercom_statechart/main.cpp, so_5/machine_control/main.cpp, so_5/news_board/main.cpp, so_5/ping_pong_minimal/main.cpp, so_5/prio_work_stealing/main.cpp, so_5/producer_consumer_mchain/main.cpp, so_5/selective_msg_tracing/main.cpp, and so_5/wrapped_env_demo_2/main.cpp.

Definition at line 524 of file environment.cpp.

create_mbox() [2/2]

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

nodiscard

Create named MPMC mbox.

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

Usage example:

class first_participant final : public so_5::agent_t {
  const so_5::mbox_t broadcast_mbox_;
  ...
public:
  first_participant(context_t ctx)
    : so_5::agent_t{std::move(ctx)}
    , broadcast_mbox_{so_environment().create_mbox("message-board")}
  {}
  ...
};
 
class second_participant final : public so_5::agent_t {
  const so_5::mbox_t broadcast_mbox_;
  ...
public:
  second_participant(context_t ctx)
    : so_5::agent_t{std::move(ctx)}
    , broadcast_mbox_{so_environment().create_mbox("message-board")}
  {}
  ...
};

In this example both agents will use the same mbox instance.

Attention

Mboxes created by this method live in a separate namespace, they are not mixed with named mboxes introduced via introduce_named_mbox() method.

Parameters

mbox_name

Mbox name.

Definition at line 530 of file environment.cpp.

create_mchain()

mchain_t so_5::environment_t::create_mchain

(

const mchain_params_t &

params

)

Create message chain.

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(); } ) );

Since

v.5.5.13

Parameters

params

Parameters for a new bag.

Examples

so_5/producer_consumer_mchain/main.cpp.

Definition at line 549 of file environment.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.

Usage example:

so_5::environment_t & env = ...;
so_5::coop_handle_t coop_handle;
 
auto simple_coop = env.make_coop();
simple_coop->make_agent<some_agent_type>(...);
coop_handle = env.register_coop(std::move(simple_coop));
...
// Some time later.
env.deregister_coop(coop_handle, so_5::dereg_reason::normal);

Note

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

Attention

It's safe to pass an empty coop_handle_t to deregister_coop(). It's also safe to pass a coop_handle of a coop that is already deregistered. For example, this is not an error:

class demo {
  so_5::environment_t & m_env;
  so_5::coop_handle_t m_child_coop;
  ...
public:
  demo(
    so_5::environment_t & env,
    so_5::coop_handle_t child_coop)
    : m_env{env}
    , m_child_coop{std::move(child_coop)}
  {}
 
  ~demo() {
    // Force the deregistration of the child coop.
    // Don't care if drop_child() has already been called.
    m_env.deregister_coop(m_child_coop, so_5::dereg_reason::normal);
  }
  ...
  void drop_child() {
    m_env.deregister_coop(m_child_coop, so_5::dereg_reason::normal);
  }
};
...
void some_action(so_5::environment_t & env) {
  ...
  coop_handle = env.register_coop(...);
  demo holder{env, coop_handle};
  ...
  holder.drop_child(); // The first call to deregister_coop.
  ...
} // Another call to deregister_coop in the destructor of demo object.

Parameters

coop	The coop to be deregistered.
reason	Deregistration reason.

Examples

so_5/custom_work_thread_factory/main.cpp, and so_5/ping_pong_with_owner/main.cpp.

Definition at line 1556 of file environment.hpp.

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

Definition at line 789 of file environment.cpp.

error_logger()

error_logger_t & so_5::environment_t::error_logger

(

)

const

Get the error_logger object.

Since

v.5.5.0

Definition at line 747 of file environment.cpp.

exception_reaction()

exception_reaction_t so_5::environment_t::exception_reaction ( ) const

noexcept

An exception reaction for the whole SO Environment.

Note

This method is noexcept since v.5.8.0.

Since

v.5.3.0

Definition at line 741 of file environment.cpp.

imp_run_infrastructure()

void so_5::environment_t::imp_run_infrastructure ( )

private

Launch environment infrastructure and wait for finish.

Since

v.5.5.19

Definition at line 889 of file environment.cpp.

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.

Definition at line 849 of file environment.cpp.

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

Definition at line 837 of file environment.cpp.

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::anonymous_namespace{wrapped_env.cpp}::actual_environment_t, and so_5::impl::so_quick_environment_t< Init >.

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.

Definition at line 556 of file environment.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/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/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/dispatcher_for_children_2/main.cpp, so_5/hello_all/main.cpp, so_5/hello_world_simple_not_mtsafe/main.cpp, so_5/individual_msg_tracing/main.cpp, so_5/intercom_statechart/main.cpp, so_5/introduce_named_mbox/main.cpp, so_5/machine_control/main.cpp, so_5/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/single_sink_binding/main.cpp, so_5/state_deep_history/main.cpp, so_5/stop_guard/main.cpp, so_5/unique_subscribers_mbox/main.cpp, and so_5/wrapped_env_demo_2/main.cpp.

Definition at line 2191 of file environment.hpp.

introduce_named_mbox()

mbox_t so_5::environment_t::introduce_named_mbox ( mbox_namespace_name_t mbox_namespace, nonempty_name_t mbox_name, const std::function< mbox_t() > & mbox_factory )

nodiscard

Introduce named mbox with user-provided factory.

This method allows a user to create own named mbox.

The create_mbox(nonempty_name_t) method always creates a standard MPMC mbox. This isn't always desirable. For example, a user may want to have a named unique_subscribers mbox. The introduce_named_mbox() allows to achieve this:

class first_participant final : public so_5::agent_t {
  const so_5::mbox_t broadcast_mbox_;
  ...
public:
  first_participant(context_t ctx)
    : so_5::agent_t{std::move(ctx)}
    , broadcast_mbox_{so_environment().introduce_named_mbox(
        so_5::mbox_namespace_name_t{"demo"},
        "message-board",
        [this]() { return so_5::make_unique_subscribers_mbox(so_environment()); } )
      }
  {}
  ...
};
 
class second_participant final : public so_5::agent_t {
  const so_5::mbox_t broadcast_mbox_;
  ...
public:
  second_participant(context_t ctx)
    : so_5::agent_t{std::move(ctx)}
    , broadcast_mbox_{so_environment().introduce_named_mbox(
        so_5::mbox_namespace_name_t{"demo"},
        "message-board",
        [this]() { return so_5::make_unique_subscribers_mbox(so_environment()); } )
      }
  {}
  ...
};

The introduce_named_mbox work the following way:

• it checks for the existence of a mbox with the given name in the specified namespace. If such a mbox is found it will be returned and mbox_factory is not called;
• otherwise, the mbox_factory is called;
• after the completion of mbox_factory the existence of a mbox with the given name is checked again;
• if there is still no such a mbox, then the mbox obtained from mbox_factory is stored inside the SOEnv and returned as the result of the introduce_named_mbox method;
• but if a mbox is found (it may have been created a little earlier by a parallel call to the introduce_named_mbox), then the the value returned by mbox_factory is discarded and the existing named mbox is returned.

It means then the mbox_factory is used if there is no a mbox with the name specified yet. If such a mbox is already exists then the already created mbox will be returned without calling mbox_factory.

Note that named mboxes created by this method live in separate namespaces and those namespaces aren't intersect with "the default" namespace used by the create_mbox(nonempty_name_t) method. It means that a user can create named mboxes with the same name in different namespaces and they will be different mboxes:

so_5::environment_t & env = ...;
auto std_mbox = env.create_mbox("alice");
auto my_mbox1 = env.introduce_named_mbox(
  so_5::mbox_namespace_name_t{"a"},
  "alice",
  [&env]() { return env.create_mbox(); });
auto my_mbox2 = env.introduce_named_mbox(
  so_5::mbox_namespace_name_t{"b"},
  "alice",
  [&env]() { return env.create_mbox(); });
// NOTE: it's just a reference to my_mbox2.
auto my_duplicate = env.introduce_named_mbox(
  so_5::mbox_namespace_name_t{"b"},
  "alice",
  [&env]() { return env.create_mbox(); });
 
assert(std_mbox->id() != my_mbox1->id());
assert(std_mbox->id() != my_mbox2->id());
assert(my_mbox1->id() != my_mbox2->id());
assert(my_mbox2->id() == my_duplicate->id());

Attention

The mbox_factory should return a valid so_5::mbox_t. If mbox_factory returns empty so_5::mbox_t (nullptr), then introduce_named_mbox() will throw an exception with so_5::rc_nullptr_as_result_of_user_mbox_factory error code. If mbox_factory can't create a valid so_5::mbox_t it has to thrown a user-defined exception. This exception will be let out from introduce_named_mbox(). For example:

so_5::environment_t & env = ...;
try
{
  auto mbox = env.introduce_named_mbox(
      so_5::mbox_namespace_name_t{"b"},
      "alice",
      [&]() {
        auto mbox = try_to_get_new_mbox();
        if(!mbox)
          throw my_exception{...};
        return mbox;
      });
}
catch( const my_exception & x ) { ... }

Note

If several parallel calls to introduce_named_mbox() with the same parameters are made at the same time then mbox_factory can be called several times (at most once for every introduce_named_mbox() invocation). But only one result of those calls will be used, all other returned values will be discarded.

Attention

The mbox_factory can be called in parallel (so mbox_factory should support this behavior). The mbox_factory can safely call environment_t's methods like create_mbox() and so on.

Since

v.5.8.0

Parameters

mbox_namespace	Name of mbox_namespace for a new mbox.
mbox_name	Name for a new mbox.
mbox_factory	Factory for new mbox.

Examples

so_5/introduce_named_mbox/main.cpp.

Definition at line 537 of file environment.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/agent_name/main.cpp, so_5/child_soenv/main.cpp, 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.

Definition at line 1709 of file environment.hpp.

make_coop() [1/4]

coop_unique_holder_t so_5::environment_t::make_coop ( )

nodiscard

Create a cooperation.

Usage example:

so_5::environmet_t & env = ...;
// A binder for the default dispatcher will be used.
auto coop = env.make_coop();
coop.make_agent<first_agent>(...);
coop.make_agent<second_agent>(...);
// Registration of the coop.
env.register_coop(std::move(coop));

Returns

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

Since

v.5.6.0

Examples

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

Definition at line 573 of file environment.cpp.

make_coop() [2/4]

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

nodiscard

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.

Definition at line 592 of file environment.cpp.

make_coop() [3/4]

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

nodiscard

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.

Definition at line 602 of file environment.cpp.

make_coop() [4/4]

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

nodiscard

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.

Definition at line 582 of file environment.cpp.

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

Definition at line 1855 of file environment.hpp.

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.

Definition at line 1591 of file environment.hpp.

query_layer() [2/2]

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

private

Access to an additional layer.

Definition at line 686 of file environment.cpp.

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.

Definition at line 1579 of file environment.hpp.

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/agent_name/main.cpp, so_5/child_soenv/main.cpp, 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.

Definition at line 1444 of file environment.hpp.

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.

It is just a helper methods for convience.

Usage sample:

so_5::environment_t & env = ...;
env.register_agent_as_coop(
    std::make_unique<my_agent>(...),
    so_5::disp::active_group::make_dispatcher(env)
        .binder("some_active_group") );

Since

v.5.2.1

Definition at line 1471 of file environment.hpp.

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.

Usage examples

Very simple case.

so_5::environment_t & env = ...;
 
auto simple_coop = env.make_coop();
simple_coop->make_agent<some_agent_type>(...);
env.register_coop(std::move(simple_coop));

More complex case with storing coop_handle and using it for coop deregistration:

so_5::environment_t & env = ...;
so_5::coop_handle_t coop_handle;
 
auto simple_coop = env.make_coop();
simple_coop->make_agent<some_agent_type>(...);
coop_handle = env.register_coop(std::move(simple_coop));
...
// Some time later.
env.deregister_coop(coop_handle, so_5::dereg_reason::normal);

A typical scenario for register_coop() when an instance of coop is created by a separate function:

[[nodiscard]] so_5::coop_unique_holder_t create_coop(
    so_5::environment_t & env)
{
  auto coop = env.make_coop();
  coop->make_agent<some_agent_type>(...);
  ... // Some other actions like creation of additional agents.
 
  // Now the coop can be returned back.
  return coop;
}
 
so_5::environment_t & env = ...;
...
env.register_coop(create_coop(env));

Parameters

agent_coop

Cooperation to be registered.

Examples

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

Definition at line 612 of file environment.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.

Definition at line 815 of file environment.cpp.

run()

void so_5::environment_t::run

(

)

Run the SObjectizer Run-Time.

Definition at line 701 of file environment.cpp.

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.

Definition at line 507 of file environment.cpp.

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.

Definition at line 796 of file environment.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

Definition at line 777 of file environment.cpp.

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.

Definition at line 619 of file environment.cpp.

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.

Definition at line 660 of file environment.cpp.

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.

Definition at line 753 of file environment.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

Definition at line 759 of file environment.cpp.

stop()

void so_5::environment_t::stop ( )

noexcept

Send a shutdown signal to the Run-Time.

Note

This method is noexcept since v.5.8.0.

Examples

so_5/adv_thread_pool_fifo/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/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/producer_consumer_mchain/main.cpp, so_5/queue_size_stats/main.cpp, so_5/redirect_and_transform/main.cpp, and so_5/stop_guard/main.cpp.

Definition at line 722 of file environment.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

Definition at line 771 of file environment.cpp.

work_thread_factory()

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

nodiscardnoexcept

Access to the global work thread factory.

Since

v.5.7.3

Definition at line 765 of file environment.cpp.

Friends And Related Symbol Documentation

so_5::impl::internal_env_iface_t

friend class so_5::impl::internal_env_iface_t

friend

Definition at line 957 of file environment.hpp.

Member Data Documentation

m_impl

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

private

SObjectizer Environment internals.

Definition at line 2060 of file environment.hpp.

---

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

• environment.hpp
• environment.cpp