so_5::wrapped_env_t Class Reference

A wrapped environment. More...

#include <wrapped_env.hpp>

Classes
struct	details_t
	Implementation details for wrapped_env. More...

Public Types
enum class	wait_init_completion_t { sync }
	Helper type to be used as indicator of synchronous mode. More...

Public Member Functions
	wrapped_env_t (const wrapped_env_t &)=delete
	wrapped_env_t (wrapped_env_t &&)=delete
	wrapped_env_t ()
	Default constructor.
	wrapped_env_t (so_5::generic_simple_init_t init_func)
	A constructor which receives only initialization function.
	wrapped_env_t (so_5::generic_simple_init_t init_func, so_5::generic_simple_so_env_params_tuner_t params_tuner)
	A constructor which receives initialization function and a function for environment's params tuning.
	wrapped_env_t (so_5::generic_simple_init_t init_func, environment_params_t &&params)
	wrapped_env_t (wait_init_completion_t wait_init_completion_indicator, so_5::generic_simple_init_t init_func)
	A constructor for synchronous mode which receives only initialization function.
	wrapped_env_t (wait_init_completion_t wait_init_completion_indicator, so_5::generic_simple_init_t init_func, environment_params_t &&params)
	A constructor for synchronous mode which receives initialization function and already prepared environment's params.
	wrapped_env_t (wait_init_completion_t wait_init_completion_indicator, so_5::generic_simple_init_t init_func, so_5::generic_simple_so_env_params_tuner_t params_tuner)
	A constructor for synchronous mode which receives initialization function and a function for environment's params tuning.
	wrapped_env_t (environment_params_t &&params)
	A constructor which receives already prepared environment's params.
	~wrapped_env_t ()
	Destructor.
environment_t &	environment () const
	Access to wrapped environment.
void	stop ()
	Send stop signal to environment.
void	join ()
	Wait for complete finish of environment's work.
void	stop_then_join ()
	Send stop signal and wait for complete finish of environment's work.

Static Public Attributes
static constexpr wait_init_completion_t	wait_init_completion
	Special indicator that tells that synchronous mode has to be used for calling init-function.

Private Member Functions
	wrapped_env_t (so_5::generic_simple_init_t init_func, environment_params_t &&params, wrapped_env_details::init_style_t init_style)
	The main initializing constructor.

Private Attributes
std::unique_ptr< details_t >	m_impl
	Implementation details.

Detailed Description

A wrapped environment.

Note

Starts a SObjectizer Environment in the constructor. Automatically stops it in the destructor (via stop_then_join() call). An Environment will be started on the context of new thread. This thread is also created in the constructor of wrapped_env_t.

SObjectizer Environment is started with autoshutdown disabled. It means that the Environment won't be stopped when the last coop will be deregistered. Autoshutdown will be disabled even if a constructor with custom Environment's params will be used.

The wrapped_env_t may handle init-function (if it's passed to the constructor) in two modes:

• asynchronous (the default). In that case the wrapped_env_t constructor may complete its work even before the start of init-function;
• synchronous. In that case the wrapped_env_t constructor will block the caller thread until the init-function completes.

Usage examples for the default asynchronous mode

// Start Environment without initialization function.
int main()
{
  so_5::wrapped_env_t env;
  ... // Some user code.
  // Add a cooperation to environment.
  env.environment().introduce_coop( []( so_5::coop_t & coop ) {
    coop.make_agent< some_agent >(...);
    ...
  } );
  ... // Some user code.
 
  return 0; // env.stop_then_join() will be called in env destructor.
}
 
// Start Environment with initialization function but with
// default parameters.
int main()
{
  so_5::wrapped_env_t env{
    []( so_5::environment_t & env ) {
      ... // Some initialization stuff.
    }
  };
  ... // Some user code.
 
  return 0; // env.stop_then_join() will be called in env destructor.
}
 
// Start Environment with initialization function and custom
// parameters.
so_5::environment_params_t make_params()
{
  so_5::environment_params_t params;
  params.exception_reaction( so_5::shutdown_sobjectizer_on_exception );
  ...
  return params;
}
 
int main()
{
  so_5::wrapped_env_t env{
    []( so_5::environment_t & env ) {
      ... // Some initialization stuff.
    },
    make_params()
  };
  ... // Some user code.
 
  return 0; // env.stop_then_join() will be called in env destructor.
}
 
// Start Environment with initialization function and custom
// parameters tuner function.
int main()
{
  so_5::wrapped_env_t env{
    []( so_5::environment_t & env ) {
      ... // Some initialization stuff.
    },
    []( so_5::environment_params_t & params ) {
      params.exception_reaction( so_5::shutdown_sobjectizer_on_exception );
      ...
    }
  };
  ... // Some user code.
 
  return 0; // env.stop_then_join() will be called in env destructor.
}
 
// Explicit stop and join.
int main()
{
  so_5::wrapped_env_t env{ ... };
  ... // Some user code.
  // Stopping environment.
  env.stop();
  ... // Some user code.
  // Waiting for finish of environment's work.
  env.join();
  ... // Some user code.
}

Attention

Please note that if an init function is passed to the constructor of wrapped_env_t objects then it is possible that this init function will work longer than lifetime of wrapped_env_t object. For example:

int some_func() {
 so_5::wrapped_env_t env{
   [](so_5::environment_t & env) { ... } // Some long-running code inside.
 };
 ... // Some very fast actions.
 return 42; // It is possible that init-function is not finished yet.
}

This can lead to some nasty surprises. For example:

so_5::wrapped_env_t env{
 [](so_5::environment & env) {
   env.introduce_coop(...); // Creation of one coop.
   env.introduce_coop(...); // Creation of another coop.
   ...
   env.introduce_coop(...); // Creation of yet another coop.
 }
};
... // Some very fact actions.
env.stop(); // Several coops could not be registered yet.

Another example that may lead to null-pointer dereference:

so_5::mbox_t target; // null by default.
so_5::wrapped_env_t env{
 [&](so_5::environment_t & env) {
 env.introduce_coop([&](so_5::coop_t & coop) {
     target = coop.make_agent<some_agent>(...)->so_direct_mbox();
   });
 }
};
so_5::send<msg_start_doing_work>(target); // target may still be null!

If init-function throws an exception in synchronous mode then the whole application will be terminated because this exception won't be handled.

Usage examples for the default synchronous mode

Please note that there is no overloads of the wrapped_env_t contructor without the init-function parameter.

// Start Environment with initialization function but with
// default parameters.
int main()
{
 so_5::wrapped_env_t env{
   so_5::wrapped_env_t::wait_init_completion,
   []( so_5::environment_t & env ) {
     ... // Some initialization stuff.
   }
 };
 ... // Some user code.
 
 return 0; // env.stop_then_join() will be called in env destructor.
}
 
// Start Environment with initialization function and custom
// parameters.
so_5::environment_params_t make_params()
{
 so_5::environment_params_t params;
 params.exception_reaction( so_5::shutdown_sobjectizer_on_exception );
 ...
 return params;
}
 
int main()
{
 so_5::wrapped_env_t env{
   so_5::wrapped_env_t::wait_init_completion,
   []( so_5::environment_t & env ) {
     ... // Some initialization stuff.
   },
   make_params()
 };
 ... // Some user code.
 
 return 0; // env.stop_then_join() will be called in env destructor.
}
 
// Start Environment with initialization function and custom
// parameters tuner function.
int main()
{
 so_5::wrapped_env_t env{
   so_5::wrapped_env_t::wait_init_completion,
   []( so_5::environment_t & env ) {
     ... // Some initialization stuff.
   },
   []( so_5::environment_params_t & params ) {
     params.exception_reaction( so_5::shutdown_sobjectizer_on_exception );
     ...
   }
 };
 ... // Some user code.
 
 return 0; // env.stop_then_join() will be called in env destructor.
}

Attention

If the init-function throws in synchronous mode then the exception will be rethrown from the constructor of the wrapped_env_t:

struct my_exception final : public std::exception {...};
...
try {
 so_5::wrapped_env_t sobjectizer{
   so_5::wrapped_env_t::wait_init_completion,
   [](so_5::environment_t & env) {
     ...
     if(some_condition)
       // In the synchronous mode we can throw from init-function.
       throw my_exception{...};
   }
 }
 ...
}
catch( const my_exception & x ) {
 ... // exception handling.
}

Since

v.5.5.9

Examples

so_5/intercom_statechart/main.cpp, so_5/mchain_empty_notificator/main.cpp, so_5/mchain_empty_notificator_2/main.cpp, so_5/mchain_fibonacci/main.cpp, so_5/mchain_handler_formats/main.cpp, so_5/mchain_multi_consumers/main.cpp, so_5/mchain_select/main.cpp, so_5/state_deep_history/main.cpp, so_5/wrapped_env_demo_2/main.cpp, and so_5/wrapped_env_demo_3/main.cpp.

Definition at line 288 of file wrapped_env.hpp.

Member Enumeration Documentation

wait_init_completion_t

enum class so_5::wrapped_env_t::wait_init_completion_t

strong

Helper type to be used as indicator of synchronous mode.

Since

v.5.8.2.

Enumerator
sync

Definition at line 311 of file wrapped_env.hpp.

Constructor & Destructor Documentation

wrapped_env_t() [1/11]

so_5::wrapped_env_t::wrapped_env_t ( so_5::generic_simple_init_t init_func, environment_params_t && params, wrapped_env_details::init_style_t init_style )

private

The main initializing constructor.

All other constructors just delegate work to this constructor.

Since

v.5.8.2

Parameters

init_func	Init-function to be called.
params	Parameters for SOEnv to be used.
init_style	Asynchronous or synchronous mode.

Definition at line 320 of file wrapped_env.cpp.

wrapped_env_t() [2/11]

so_5::wrapped_env_t::wrapped_env_t ( const wrapped_env_t & )

delete

wrapped_env_t() [3/11]

so_5::wrapped_env_t::wrapped_env_t ( wrapped_env_t && )

delete

wrapped_env_t() [4/11]

so_5::wrapped_env_t::wrapped_env_t

(

)

Default constructor.

Starts environment without any initialization actions.

Definition at line 334 of file wrapped_env.cpp.

wrapped_env_t() [5/11]

so_5::wrapped_env_t::wrapped_env_t

(

so_5::generic_simple_init_t

init_func

)

A constructor which receives only initialization function.

Default environment parameters will be used.

Attention

This constructor runs init_func in asynchronous mode.

Parameters

init_func

Initialization function.

Definition at line 338 of file wrapped_env.cpp.

wrapped_env_t() [6/11]

so_5::wrapped_env_t::wrapped_env_t	(	so_5::generic_simple_init_t	init_func,
		so_5::generic_simple_so_env_params_tuner_t	params_tuner )

A constructor which receives initialization function and a function for environment's params tuning.

Attention

This constructor runs init_func in asynchronous mode.

Parameters

init_func	Initialization function.
params_tuner	Function for environment's params tuning.

Definition at line 345 of file wrapped_env.cpp.

wrapped_env_t() [7/11]

so_5::wrapped_env_t::wrapped_env_t	(	so_5::generic_simple_init_t	init_func,
		environment_params_t &&	params )

A constructor which receives initialization function and already prepared environment's params.

Attention

This constructor runs init_func in asynchronous mode.

Parameters

init_func	Initialization function.
params	Environment's params.

Definition at line 353 of file wrapped_env.cpp.

wrapped_env_t() [8/11]

so_5::wrapped_env_t::wrapped_env_t	(	wait_init_completion_t	wait_init_completion_indicator,
		so_5::generic_simple_init_t	init_func )

A constructor for synchronous mode which receives only initialization function.

Default environment parameters will be used.

Attention

This constructor runs init_func in synchronous mode.

Note

This construtor rethrows an exception thrown in init_func.

Since

v.5.8.2

Parameters

wait_init_completion_indicator	Indicator of the synchronous mode.
init_func	Initialization function.

Definition at line 362 of file wrapped_env.cpp.

wrapped_env_t() [9/11]

so_5::wrapped_env_t::wrapped_env_t	(	wait_init_completion_t	wait_init_completion_indicator,
		so_5::generic_simple_init_t	init_func,
		environment_params_t &&	params )

A constructor for synchronous mode which receives initialization function and already prepared environment's params.

Attention

This constructor runs init_func in synchronous mode.

Note

This construtor rethrows an exception thrown in init_func.

Since

v.5.8.2

Parameters

wait_init_completion_indicator	Indicator of the synchronous mode.
init_func	Initialization function.
params	Environment's params.

Definition at line 371 of file wrapped_env.cpp.

wrapped_env_t() [10/11]

so_5::wrapped_env_t::wrapped_env_t	(	wait_init_completion_t	wait_init_completion_indicator,
		so_5::generic_simple_init_t	init_func,
		so_5::generic_simple_so_env_params_tuner_t	params_tuner )

A constructor for synchronous mode which receives initialization function and a function for environment's params tuning.

Attention

This constructor runs init_func in synchronous mode.

Note

This construtor rethrows an exception thrown in init_func.

Since

v.5.8.2

Parameters

init_func	Initialization function.
params_tuner	Function for environment's params tuning.

Definition at line 381 of file wrapped_env.cpp.

wrapped_env_t() [11/11]

so_5::wrapped_env_t::wrapped_env_t

(

environment_params_t &&

params

)

A constructor which receives already prepared environment's params.

Usage example:

#include <so_5/all.hpp>
 
so_5::environment_params_t make_params() {
    so_5::environment_params_t result;
    ... // Parameters' tuning.
    return result;
}
 
int main() {
    so_5::wrapped_env_t sobj{ make_params() }; // SObjectizer is started on separate thread here.
    ... // Some actions.
    return 0; // SObjectizer will be stopped automatically here.
}

Since

v.5.5.13

Parameters

params

Environment's params.

Definition at line 391 of file wrapped_env.cpp.

~wrapped_env_t()

so_5::wrapped_env_t::~wrapped_env_t

(

)

Destructor.

Stops the environment and waits it.

Definition at line 398 of file wrapped_env.cpp.

Member Function Documentation

environment()

environment_t & so_5::wrapped_env_t::environment

(

)

const

Access to wrapped environment.

Examples

so_5/intercom_statechart/main.cpp, so_5/state_deep_history/main.cpp, and so_5/wrapped_env_demo_2/main.cpp.

Definition at line 404 of file wrapped_env.cpp.

join()

void so_5::wrapped_env_t::join

(

)

Wait for complete finish of environment's work.

Definition at line 416 of file wrapped_env.cpp.

stop()

void so_5::wrapped_env_t::stop

(

)

Send stop signal to environment.

Definition at line 410 of file wrapped_env.cpp.

stop_then_join()

void so_5::wrapped_env_t::stop_then_join

(

)

Send stop signal and wait for complete finish of environment's work.

Definition at line 422 of file wrapped_env.cpp.

Member Data Documentation

m_impl

std::unique_ptr< details_t > so_5::wrapped_env_t::m_impl

private

Implementation details.

Definition at line 492 of file wrapped_env.hpp.

wait_init_completion

wait_init_completion_t so_5::wrapped_env_t::wait_init_completion

staticconstexpr

Initial value:

{
        wait_init_completion_t::sync
      }

Special indicator that tells that synchronous mode has to be used for calling init-function.

Usage example:

so_5::wrapped_env_t sobjectizer{
    so_5::wrapped_env_t::wait_init_completion,
    ...
  };
...

Since

v.5.8.2

Examples

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

Definition at line 328 of file wrapped_env.hpp.

---

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

• wrapped_env.hpp
• wrapped_env.cpp