/*!

\page so_5__version so_5: Version History

\section so_5__5_8_3 5.8.3 "Volcan Tacora"

A fix for a case when message limits are specified for an agent and time_limit
is used for the agent's state(s). See the <a href="https://github.com/Stiffstream/sobjectizer/issues/75">issue 75</a>
for more details.

The lock_shared/unlock_shared methods have been added to so_5::null_mutext_t class.
Now the so_5::null_mutex_t class can be used with std::shared_lock.

New facilities for testing of agents: so_5::experimental::testing::inspect_msg(),
so_5::experimental::testing::receives(), and
so_5::experimental::testing::wait_event_handler_completion().

New facilities for message delivery tracing: so_5::msg_tracing::individual_trace()
and so_5::msg_tracing::make_individual_trace_filter().

\section so_5__5_8_2 5.8.2 "Sabancaya"

New synchronous mode for execution of init-function in the
constructor of so_5::wrapped_env_t.

A new type of subscription storage: flat-set based storage.
It can be specified by using a new so_5::flat_set_based_subscription_storage_factory()
function.

A new method so_5::environment_params_t::default_subscription_storage_factory().

New methods so_5::stats::prefix_t::as_string_view() and
so_5::stats::suffix_t::as_string_view(). Several methods of
so_5::stats::prefix_t and so_5::stats::suffix_t are now constexpr.

A possibility to set an optional name for agent. New types so_5::name_for_agent_t,
so_5::agent_identity_t. New methods so_5::agent_t::name_for_agent(), so_5::agent_t::so_agent_name().

\section so_5__5_8_1 5.8.1 "Alpamayo"

New functions so_5::msinks::transform_then_redirect() and new
helpers so_5::bind_transformer().

New methods so_5::agent_t::so_this_agent_disp_binder() and
so_5::agent_t::so_this_coop_disp_binder().

BugFix: the so_5::agent_t::limit_then_transform() now can be used with
mutable messages.

\section so_5__5_8_0 5.8.0 "Nevado de Chani"

\attention
This version breaks compatibility with SObjectizer-5.7 in several
places.

An introduction of so_5::abstract_message_sink_t interface.

Format of so_5::abstract_message_box_t::subscribe_event_handler() changed.

Method so_5::abstract_message_box_t::unsubscribe_event_handler() instead
of unsubscribe_event_handlers in previous versions.

Several method of so_5::abstract_message_box_t (like
unsubscribe_event_handler() and drop_delivery_filter()) are now noexcept.

New helpers so_5::single_sink_binding_t, so_5::multi_sink_binding_t and
so_5::wrap_to_msink().

New method so_5::environment_t::introduce_named_mbox().

Unique-subcribers mbox is now a part of SObjectizer core (it's borrowed from
companion so5extra project). See so_5::make_unique_subscribers_mbox() helper
function for more details.

There were several member functions `swap` in different classes. Since v.5.8
they have been transformed into more standard-like friend freestanding `swap`
functions (receive two references as parameters and are noexcept).

New method so_5::agent_t::so_low_level_exec_as_event_handler().

The standard implementations of environment infrastructures are no longer use
dynamic memory allocation to handle the final deregistration of coops. An
intrusive list of coop_t objects is now used to hold a list of coops ready to
be removed.

Changed the interface so_5::event_queue_t: new methods
so_5::event_queue_t::push_evt_start() and
so_5::event_queue_t::push_evt_finish() are introduced.

Two new dispatchers added: so_5::disp::nef_one_thread and
so_5::disp::nef_thread_pool. The so_5::disp::nef_one_thread dispatcher
can be used as the default dispatcher if the standard multi-theaded
environment-infrastructure is used.

The so_5::environment_params_t::default_disp_params(void) getter now returns
a sum type (parameters for so_5::disp::one_thread or so_5::disp::nef_one_thread
dispatchers).

\section so_5__5_7_5 5.7.5 "Licancabur"

The so_5::abstract_message_box_t::environment() method for MPSC mboxes now
returns a valid reference to the environment even if the owner of the MPSC mbox
has already deregistered (note that mbox can't be used if the environment is
stopped).

Changed the order in which of agents and disp_binders are destroyed: now
disp_binders are destroyed after the destruction of agents. This was achieved
by moving the ownership of the disp_binder to an agent.

\section so_5__5_7_4 5.7.4 "Cerro Miniques"

The standard MPSC mboxes now support delivery filters.
Delivery filters for mutable messages should be set via a new method
so_5::agent_t::so_set_delivery_filter_for_mutable_msg().

A posibility to set a custom mbox as the direct mbox for an agent added.
See so_5::agent_t::custom_direct_mbox_factory().

\section so_5__5_7_3 5.7.3 "Cotopaxi"

Old forms of so_5::abstract_message_chain_t::close(),
so_5::close_drop_content() and so_5::close_retain_content() are deprecated. New
forms that accept so_5::exceptions_enabled/so_5::terminate_if_throws have to be
used now.

A user can now introduce own worker threads to SObjectizer dispatchers via
implementing new interfaces so_5::disp::abstract_work_thread_t and
so_5::disp::abstract_work_thread_factory_t.

New method so_5::agent_t::so_deactivate_agent deactivates the agent:

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

Being in a deactivated state an agent can't make new subscriptions and change
its state.

Since v.5.7.3 actions performed in a thread-safe event-handler are checked
regardless of the dispatcher type. It means that the state of an agent can't be
changed in thread-safe handler even if the agent is bound to one_thread
dispatcher. Changes to agent's subscriptions can't be made in a thread-safe
event-handler too.


\section so_5__5_7_2 5.7.2 "Putana"

	`operator==` and `operator!=` added to so_5::coop_handle_t.

	Fixes for several issues reported by users.

\section so_5__5_7_1 5.7.1 "Nevados Jotabeche"

	New function template so_5::make_agent_ref().

	A possibility to define default (generic) message limits. For example:
\code
class demo final : public so_5::agent_t
{
public:
   demo(context_t ctx)
      : so_5::agent_t{ctx
         + limit_then_drop<msg_A>(100u)
         + limit_then_abort<msg_B>(10u)
         // That limit will be used for all other messages.
         + limit_then_drop<any_unspecified_message>(50u)
         }
   {}
\endcode

	Fix for supported formats of on_enter/on_exit handlers for
	agent states. Now `noexcept` methods/lambdas can be used as
	those handlers.

	Changes in the procedure of message delivery to MPSC mboxes.
	Now the presence of a subscription to the message type is performed
	during `send` operation. If there is no such subscriptions the
	message isn't stored into the receiver's queue.

	New examples: default_message_limits, make_agent_ref,
	named_dispatchers_layer.

\section so_5__5_7_0 5.7.0 "Volcan Ollague"

	Support of so_5::send_case() in so_5::select().

	There is no more so_5::case_() function, so_5::receive_case() should be
	used instead.

	so_5::select() returns so_5::mchain_select_result_t instead of
	so_5::mchain_receive_result_t.

	The behavior of enveloped messages with `transfer_to_state()` and
	`suppress()` helpers. Since v.5.7.0 an envelope doesn't receive a
	notification if the payload is ignoread as the result of
	`transfer_to_state()`/`suppress()` actions.

	New enum so_5::event_handler_kind_t is introduced and the format
	of so_5::agent_t::so_create_event_subscription() changed.

\section so_5__5_6_1 5.6.1 "Cerro Mururata"

	Extensible-select added. See functions so_5::make_extensible_select()
	and so_5::add_select_cases() for more details.

	Implementation of prepared-select changed. The parallel/nested calls
	to select() with prepared-select are now checked and an exception is
	thrown if such call is detected.

\section so_5__5_6_0 5.6.0 "Volcan San Jose"

	A list of changes in v.5.6.0 can be found <a href="https://github.com/Stiffstream/sobjectizer/wiki/v.5.6.0">here</a>.

	\attention This version is not compatible with SObjectizer-5.5.

	\note Since v.5.6.0 some descriptions made for previous versions of
	SObjectizer can contain obsolete information.

\section so_5__5_24_1 5.5.24.1 "El Misti"

	Flags -fvisibitity=hidden and -fvisibility-inlines-hidden are now
	used for Unix builds (Linux, FreeBSD, MacOS). This reduces count of
	public symbols in SObjectizer's .so library.

\section so_5__5_24 5.5.24 "El Misti"

	Mechanism of so_5::event_queue_hook_t added.
	See \ref so_5_5_24__event_queue_hook for more details.

	The first version of experimental support for unit-testing of agents added.

\section so_5__5_23 5.5.23 "Volcan Cayambe"

	Some internal refactoring and optimizations.

	so_5::message_kind_t, so_5::message_t::kind_t,
	so_5::message_t::so5_message_kind() and related stuff are introduced.

	A new namespace so_5::enveloped_msg is introduced. See \ref so_5_5_23__enveloped_msg
	for more details.

	so_5::abstract_message_box_t::do_deliver_enveloped_msg() introduced.

	so_5::abstract_message_box_t::delegate_deliver_message_from_timer()
	introduced.

\section so_5__5_22_1 5.5.22.1 "Pico Cristobal Colon"

	An error code so_5::rc_transfer_to_state_loop added and run-time
	detection of transfer_to_state loops is implemented.

\section so_5__5_22 5.5.22 "Pico Cristobal Colon"

	A new experimental mechanism for filtering msg_tracing messages
	is introduced. It includes new types
	so_5::msg_tracing::trace_data_t, so_5::msg_tracing::filter_t (and some
	more related types in so_5::msg_tracing namespace),
	new methods so_5::environment_t::change_message_delivery_tracer_filter()
	and so_5::environment_params_t::message_delivery_tracer_filter(),
	and new free functions like so_5::msg_tracing::make_filter(),
	so_5::msg_tracing::make_disable_all_filter(),
	so_5::msg_tracing::make_enable_all_filter().

	Free functions can be used as handlers for so_5::receive()
	and so_5::select() functions.
	For example it is possible to write something like:
	\code
	void first_handler(const some_msg & msg) {...}
	void second_handler(another_msg msg) {...}
	void third_handler(so_5::mhood_t<third_msg> cmd) {...}
	void forth_handler(so_5::mutable_mhood_t<third_msg> cmd) {...}
	...
	auto ch = so_5::create_mchain(env);
	so_5::receive(ch, so_5::infinite_wait,
		 first_handler,
		 second_handler,
		 third_handler,
		 forth_handler);
	\endcode

	Method so_5::agent_t::so_current_state() now returns expected value
	in on_enter/on_exit state's handlers. For example, the following
	asserts will work correctly since v.5.5.22:
	\code
	class demo final : public so_5::agent_t {
		state_t st_1{ this };
		state_t st_1_1{ initial_substate_of{st_1} };
		state_t st_1_2{ substate_of{st_1}};
		...
		virtual void so_define_agent() override {
			st_1.on_enter([this]{
				assert(st_1 == so_current_state());
				...
			});
			st_1_1.on_enter([this]{
				assert(st_1_1 == so_current_state());
				...
			});
			...
		}
	};
	\endcode

	New examples selective_msg_tracing and nohandler_msg_tracing added.

\section so_5__5_21 5.5.21 "Cerro de La Isla"

	Deadletter handlers are introduced.
	See \ref so_5_5_21__deadletter_handlers for more details.

	Negative values of `pause` and `period` for so_5::send_delayed(),
	so_5::send_periodic(), so_5::environment_t::schedule_timer() and
	so_5::environment_t::single_timer() are now explicitely disabled.
	Values of `pause` and `period` are checked at run-time and
	an exception is thrown if a value is negative.
	There are new error codes so_5::rc_negative_value_for_pause and
	so_5::rc_negative_value_for_period for such cases.

\section so_5__5_20_1 5.5.20.1 "Nevado Aguas Blancas"

	Operator so_5::state_t::operator!=() added.

	`noexcept` marks are set for so_5::intrusive_ptr_t and
	so_5::timer_id_t classes.

\section so_5__5_20 5.5.20 "Nevado Aguas Blancas"

	Const methods of agents can now be used as event handlers.

	Const methods of agents can now be used as on_enter/on_exit handlers
	for agent's states.

	Support for CMake has been enhanced.

	New overloads for so_5::send_delayed(target, pause, mhood)
	and so_5::send_periodic(target, pause, period, mhood) have been added.

	Timers' implementation has been switched to timertt-1.2.2.

	If a compiler supports `[[nodiscard]]` attribute then this attribute
	will be used for `so_5::send_periodic` functions.

\section so_5__5_19_5 5.5.19.5 "Nevado de Poquis"

	Now it is possible to check presense of a subscription to a message.
	See \ref so_5_5_19__has_subscription for more details.

	New methods are introduced: so_5::agent_t::so_has_subscription(),
	so_5::state_t::has_subscription(), so_5::state_t::drop_subscription().

	Fix implementation of so_5::agent_t::so_drop_subscription() and
	so_5::agent_t::so_drop_subscription_for_all_states() for cases when
	an event-handler returns non-void.

\section so_5__5_19_4 5.5.19.4 "Nevado de Poquis"

	Fixes for warnings detected by clang-5.0.0 on high warning levels.

\section so_5__5_19_3 5.5.19.3 "Nevado de Poquis"

	Some version-specific macros are introduced: SO_5_VERSION_MAJOR,
	SO_5_VERSION_MINOR, SO_5_VERSION_PATCH, SO_5_VERSION, SO_5_VERSION_MAKE.

	Method make_trace in msg_tracing-implementation tracers is now public. It
	simplifies implementation of custom mboxes.

\section so_5__5_19_2 5.5.19.2 "Nevado de Poquis"

	A new entity so_5::stop_guard_t is added. See \ref so_5_5_19__stop_guards
	for more details.

	New methods: so_5::environment_t::setup_stop_guard() and
	so_5::environment_t::remove_stop_guard().

	New example stop_guard is added.

	Method so_5::environment_t::make_custom_mbox() and new type
	so_5::mbox_creation_data_t. See \ref so_5_5_19__custom_mbox for more
	details.

	Class so_5::null_mutex_t added.

	Helper template so_5::details::lock_holder_detector added to simplify
	development of SObjectizer's extensions and additional libraries.

\section so_5__5_19 5.5.19 "Nevado de Poquis"

	New format of send-functions, see \ref
	so_5_5_19__new_format_of_send_functions for more details.

	Mutable messages are supported now. See \ref so_5_5_19__mutable_messages for
	more details.

	An ability to run SObjectizer Environment in a single threaded mode
	is implemented. See \ref so_5_5_19__environment_infrastructures for
	more details.

	Function so_5::create_default_disp_binder() is deprecated.
	New function so_5::make_default_disp_binder() must be used instead.

	New examples: hello_world_simple_not_mtsafe, modify_resend_as_immutable,
	mutable_msg_agents, wrapped_env_demo_3, two_handlers.

\section so_5__5_18 5.5.18 "Nevado Pisco"

	New behavior for delivery of delayed and periodic messages to overloaded
	message chains. See \ref so_5_5_18__overloaded_mchains_and_timers for
	details.

	New messages so_5::stats::messages::distribution_started and
	so_5::stats::messages::distribution_finished.
	See also \ref so_5_5_18__new_msg_distrib_started_finished
	for more details.

	Support for global lock_factories.
	Class so_5::queue_locks_defaults_manager_t and method
	so_5::environment_params_t::queue_locks_defaults_manager().
	See also \ref so_5_5_18__global_lock_factories for more details.

	Nested state switch is explicitely disabled.
	See \ref so_5_5_18__nested_state_switch for more details.

	Work thread activity tracking.
	See \ref so_5_5_18__work_thread_activity_tracking for more details.

\section so_5__5_17 5.5.17 "Nevado del Huila"

	SObjectizer can be built as shared or static library.
	See \ref so_5_5_17__so_as_static_lib for more details.

	New functions so_5::prepare_receive(),
	so_5::receive(const prepared_receive_t< HANDLERS_COUNT > &),
	so_5::prepare_select(),
	so_5::select(const prepared_select_t< CASES_COUNT > &).
	See \ref so_5_5_17__prepare_receive for more details.

	New method so_5::mchain_bulk_processing_params_t::on_close()
	to specify a handler for chain close event.
	See \ref so_5_5_17__on_close_handlers_for_adv_receive for more details.

	Helper class so_5::mchain_master_handle_t added.
	See \ref so_5_5_17__mchain_master_handle for more details.

\section so_5__5_16_1 5.5.16.1

	Support for GCC v.4.8.2.

\section so_5__5_16 5.5.16 "Cerro Barroso"

	New method
	so_5::disp::mpmc_queue_traits::queue_params_t::next_thread_wakeup_threshold()
	for tuning the behaviour of thread_pool and adv_thread_pool dispatchers.

	Helper functions so_5::create_mchain() added. They simplify creation
	of size-limited and size-unlimited mchains.

	Helper function so_5::auto_join() added. It helps to work with
	raw std::thread.

	Helper function so_5::auto_close_mchains() added.
	There are also helper functions so_5::auto_close_retain_content()
	and so_5::auto_close_drop_content().

	New functions so_5::select() for handling messages from several
	mchains added.

	New example *mchain_select* added.

	mchain can now be used as MPMC chains. It means that several consumer
	threads can call so_5::receive() on the same mchain.

	New example *mchain_multi_consumers* added.

	New methods so_5::coop_t::size(), so_5::coop_t::capacity() and
	so_5::coop_t::reserve().

\section so_5__5_15 5.5.15 "Cerro Paroma"

	A possibility to implement agent as a hierachical state machine added.
	See \ref so_5_5__in_depth__agent_states for more details.

	New examples added: *blinking_led*, *intercom_statechart* and *state_deep_history*.
	

\section so_5__5_14 5.5.14 "Nevado de Antisana"

	Unification of event handler formats for method-style and lambda-style
	handlers. See \ref so_5_5_14__mhood for more details.

	New method so_5::mchain_receive_params_t::no_wait_on_empty().

	New example producer_consumer_mchain added.

\section so_5__5_13 5.5.13 "Cerro Dona Ana"

	<b>Breaking change: namespace so_5::rt is deprecated!</b>
	See \ref so_5_5_13__so_rt_ns_deprecated for more details.

	Functions send_delayed_to_agent and send_periodic_to_agent are
	deprecated. See \ref so_5_5_13__timed_send_deprecated for more
	details.

	Another constructor implemented for class so_5::wrapped_env_t. It
	receives just one argument: an instance of so_5::environment_params_t.

	Type name so_5::agent_t::state_t is added. It just an alias for
	so_5::state_t.

	Methods so_5::environment_t::create_local_mbox() are deprecated.
	Methods so_5::environment_t::create_mbox() must be used instead.

	A new mechanism named <i>message chain</i> added.
	See \ref so_5_5__in_depth__mchains for more details.

\section so_5__5_12 5.5.12 "Cerro Araral"

	A performance degradation for local mboxes with large amount of
	subscribers for one message type is fixed (that degradation was accidentally
	introduced some versions ago).

	New data source for showing quantity of coops waiting for final
	deregistration added to run-time statistics.

	Small modification to output format of msg_tracing messages
	(format of pointers doesn't depends of compiler now).

\section so_5__5_11 5.5.11 "Cerro Nelly"

	A possibility to tune some options for event queue added for dispatchers
	so_5::disp::thread_pool and so_5::disp::adv_thread_pool.
	See \ref so_5_5_12__event_queue_lock_factories for more details.

	Types for parameters for dispatchers now have name disp_params_t
	(for example so_5::disp::one_thread::disp_params_t or
	so_5::disp::adv_thread_pool::disp_params_t).

	Type for event queues' parameters now have name queue_params_t
	(for example so_5::disp::one_thread::queue_traits::queue_params_t
	or so_5::disp::adv_thread_pool::queue_traits::queue_params_t).

\section so_5__5_10 5.5.10 "Pichu Pichu"

	A possibility to tune some options for event queue added for dispatchers
	so_5::disp::one_thread, so_5::disp::active_obj, so_5::disp::active_group,
	so_5::disp::prio_one_thread::strictly_ordered,
	so_5::disp::prio_one_thread::quoted_round_robin,
	so_5::disp::prio_dedicated_threads::one_per_prio.
	A type of event queue lock can be specified by providing appropriate
	lock factory (such as so_5::disp::mpsc_queue_traits::combined_lock_factory()
	and so_5::disp::mpsc_queue_traits::simple_lock_factory());
	
	A possibility to tune options for event queue of the default dispatcher
	is implemented via so_5::rt::environment_params_t::default_disp_params()
	method.

\section so_5__5_9 5.5.9 "Cerro Zapaleri"

	A possibility to trace details of message delivery process is added.
	See \ref so_5_5__in_depth_msg_tracing for more details.

	A possibility to send messages of arbitrary types is added. See \ref so_5_5__in_depth__arbitrary_msg_type for more details.

	New format of event handlers is supported now. It is `R event_handler(T)`
	for methods of agents or `R(T)` for lambda-functions. Event handlers of such
	format are very useful with messages of arbitrary types.

	New helper functions for synchronous agents interaction:
	so_5::request_future() and so_5::request_value().
	See \ref so_5_5_9__request_future for more details.

	New format of so_5::send(). Now so_5::send() can accept const reference to
	so_5::rt::mbox_t, so_5::rt::agent_t and
	so_5::rt::adhoc_agent_definition_proxy_t.
	See \ref so_5_5_9__new_send_format for more details.

	New class so_5::wrapped_env_t added. See \ref so_5_5_9__wrapped_env
	for more details.

	A fix for serious bug: usage of MPSC mbox after the deregistration of
	the mbox's owner will lead to use of dangling pointer (with unpredicted
	consequences like application crash).

\section so_5__5_8 5.5.8 "Elbrus"

	Pririties for agents and several new dispatchers with priorities support
	have been added. See \ref so_5_5__in_depth_priority_of_agents for details.

	Another variant of introduce_child_coop and create_child_coop for
	simplification of child coop creation: \ref so_5_5_8__new_form_introduce_child_coop.

	New methods of so_5::rt::agent_coop_t for simplification of coop
   deregistration: \ref so_5_5_8__new_method_agent_coop_deregister.

	<i>An ability to define context object for ad-hoc agents added.</i> <b><i>NOTE. This feature was removed in SObjectizer-5.6.0</i></b>.

	<i>New version of send-family functions.</i> <b><i>NOTE. This feature was removed in SObjectizer-5.6.0</i></b>.

	<i>More short way for subscribing ad-hoc agents.</i> <b><i>NOTE. This feature was removed in SObjectizer-5.6.0</i></b>.

	A new variant of so_5::rt::agent_t::limit_then_abort() with pre-abort action: \ref so_5_5_8__new_limit_then_abort.

\section so_5__5_7 5.5.7

	Support for Visual C++ 14.0 (Visual Studio 2015) added.

	A small fix for collecting runtime monitoring info in so_5::disp::reuse::work_thread.

\section so_5__5_6 5.5.6

	A small refactoring of SObjectizer-5 to guarantee that `std::abort` will be
	called when appropriate event in presence of exceptions during error
	logging.

	A new description is added to Doxygen-generated documentation: \ref so_5_5__in_depth_exceptions.

	A new example make_pipeline is added.

\section so_5__5_5 5.5.5

	A mechanism of message delivery filters is introduced.
	See \ref so_5_5__in_depth_message_delivery_filters for more details.

	New templates so_5::rt::tuple_as_message_t, so_5::rt::mtag and
	so_5::rt::typed_mtag added. <b><i>NOTE. These features were
	removed in SObjectizer-5.6.0.</i></b>

	New helpers so_5::rt::environment_t::introduce_coop() and
	so_5::rt::introduce_child_coop(). See \ref so_5_5_5__introduce_coop
	for more details.

\section so_5__5_4 5.5.4 "Koshtan-Tau"

	A possibility to receive run-time statistics from SObjectizer's internals
	are introduced. See \ref so_5_5__in_depth_runtime_monitoring for more
	details.

	Message limits are supported now. See \ref so_5_5_4__message_limits for more
	details.

	Another constructor has been added to so_5::rt::agent_t. This constructor
	receives argument of type so_5::rt::agent_t::context_t.
	See \ref so_5_5_4__agent_context for more details.

	A new conception of *private dispatchers* has been introduced.
	See \ref so_5_5_4__private_dispatchers for more details.

	Methods so_5::rt::environment_t::make_agent(),
	so_5::rt::agent_coop_t::make_agent() and
	so_5::rt::agent_coop_t::make_agent_with_binder() have been
	introduced. See \ref so_5_5_4__make_agent_methods for more details.

	Switching to timertt-1.1.1.

	Switching to utest_helpers-1.0.2.

\section so_5__5_3 5.5.3 "Pik Pushkin"

	Support for CMake expanded also to the SObjectizer's tests.

	Switching to timertt-1.1.0.

	<i>A possibility to get ad-hoc agent's direct mbox added via
	so_5::rt::adhoc_agent_definition_proxy_t::direct_mbox() method.</i>
	<b><i>NOTE. This feature was removed in SObjectizer-5.6.0</i></b>.

	A free function so_5::rt::create_child_coop() has been added for
	simplification of creation of child cooperations.

	A method for tuning subscription handling mechanism has been
	added (via so_5::rt::agent_t::tuning_options() and
	so_5::rt::agent_tuning_options_t data structure).
	See \ref so_5_5_3__subscr_storage_selection for more details.

	Several new samples have been added
	(collector_performer_pair, collector_many_performers,
	simple_message_deadline, ping_pong_with_owner).

\section so_5__5_2 5.5.2 "Jangi-Tau"

	Initial support for CMake added.

	Some warnings which are detected at high warning level fixed.

\section so_5__5_1 5.5.1 "Shkhara"

	The old name so_5::rt::mbox_ref_t is marked as deprecated. Name mbox_t must
	be used instead. The old name will remain valid for several future versions
	of SObjectizer. But it is strongly recommended to use so_5::rt::mbox_t in
	the new code.

	The old name so_5::rt::smart_atomic_reference_t is marked as deprecated.
	Name so_5::intrusive_ptr_t must be used instead. The old name will remain
	valid for several future versions of SObjectizer. But it is strongly
	recommended to use so_5::intrusive_ptr_t in the new code.
	Also the so_5::atomic_refcounted_t is now moved from namespace so_5::rt
	to so_5.

	A method so_5::rt::agent_t::so_subscribe_self() has been introduced. It is
	just a shorthand for <tt>so_subscrive(so_direct_mbox())</tt>.

	A state of an agent can now be changed by several methods.
	See \ref so_5_5_1__change_agent_state.

	A new approach for subscribing an agent's event via
	so_5::rt::state_t::event() method chain. See \ref
	so_5_5_1__subscribe_event_via_state.

	New overload to simplify subscription for signals. See \ref
	so_5_5_1__new_event_method_overloads.

	New family of free functions introduced to simplify messages and signal
	sending. See \ref so_5_5_1__new_send_function_family.

	Names for new cooperations may be generated automatically. See \ref
	so_5_5_1__autoname_for_cooperations.

\section so_5__5_0 5.5.0 "Kazbek"

	Timer-handling methods so_5::rt::environment_t::schedule_timer()
	and so_5::rt::environment_t::single_timer() now accept
	std::chrono::duration as arguments.
	See \ref so_5_5_0__native_stdchrono_support.

	Two new functions so_5::launch() are implemeted to be used instead
	of bunch of so_5::api::run_so_environment() functions.

	SObjectizer Environment class renamed to so_5::rt::environment_t.
	Class with parameters for SObjectizer Environment renamed to
	so_5::rt::environment_params_t.
	Old names (so_5::rt::so_environment_t, so_5::rt::so_environment_params_t)
	kept for backward compatibility.

	timertt library is used for timers support. Because of that user has
	a possibility to select the most appropriate timer mechanism for
	its application. See \ref so_5_5_0__timer_thread_factories for more
	details.

	Because ACE_Logging is no more used new interface, so_5::error_logger_t is
	introduced. See \ref so_5_5_0__error_logger for more details.

	ACE Framework is no more used in SObjectizer core.

\section so_5__4_0 5.4.0 "Katyn-Tau"

	New helper header file so_5/api.hpp added.
	See \ref so_5_4_0__new_header_all_hpp.

	New method so_5::rt::so_environment_t::add_dispatcher_if_not_exists()
	is implemeted. It allows to add new dispatcher on running
	SO Environment. Added dispatcher cannot be removed.
	See \ref so_5_4_0__add_dispatcher_if_not_exists.

	New helper methods so_5::rt::agent_t::so_deregister_agent_coop() and
	so_5::rt::agent_t::so_deregister_agent_coop_normally().
	See \ref so_5_4_0__coop_dereg_helper_methods.

	A new feature for SObjectizer Environment: SO Environment is shutting
	down automatically if there is no more live cooperations.
	This feature is on by default. To disable it new method
	so_5::rt::so_environment_params_t::disable_autoshutdown() must be used.
	See \ref so_5_4_0__autoshutdown_mode.

	New methods so_5::rt::agent_t::so_make_state() introduced to
	simplify initialization of so_5::rt::state_t objects.
	See \ref so_5_4_0__method_so_make_state.

	Two new dispatchers: so_5::disp::thread_pool and so_5::disp::adv_thread_pool.
	The dispatcher adv_thread_pool can use event handler thread safety
	information for launching several thread-safe event handlers of one
	agent on different threads at the same time.
	See \ref so_5_4_0__thread_pool_dispatcher and
	\ref so_5_4_0__adv_thread_pool_dispatcher.

	A possibility to specify thread safety for event handler. By default
	all event handlers are not thread safe and SObjectizer is guarantees
	that those handler will not be called from different threads at the
	same time. But if event is declared as thread safe then dispatcher
	is free to launch several thread-safe event handlers at different
	threads at the same time.
	See \ref so_5_4_0__thread_safety_for_events.

	New sequence of agent to dispatcher binding. Now it is two stage
	procedure which guaratees that no so_evt_start() is called until
	all cooperation's agents are bound to dispatchers.

	New format of so_5::rt::agent_coop_t::add_agent(). Those methods now
	return a pointer to agent which has been added to cooperation.
	See \ref so_5_4_0__new_format_of_add_agent.

	There is no more anonymous agent states. If user doesn't specify name
	for the state it will be generated automatically.
	See \ref so_5_4_0__no_anonymous_states.

	A new type of mbox is introduced: this is multi-producer/single-consumer
	mbox. That mbox is belonging to the agent. A reference to that
	mbox can be obtained only by agent_t::so_direct_mbox() method.
	Anyone can send messages/signals to such mbox, but only the owner
	can be subscribed to messages from such mbox.
	See \ref so_5_4_0__new_mpsc_mbox.

	Format of so_5::rt::mbox_t::query_name() is changed. Now the std::string
	object is returned, not the const reference as in previous versions.

	A working thread identifier is now stored for every agent and controlled by
	some operations (like changing agent's state and managing agent's
	subscriptions).

	A new mechanism for event queues are implemented.

	Prototypes of methods of so_5::rt::disp_binder_t are changed:
	now they are received reference to so_5::rt::so_environment_t.

	There is no more local event queue for agents.
	Method so_5::rt::so_environment_params_t::agent_event_queue_mutex_pool_size()
	is obsolete and marked as deprecated.

\section so_5__3_0 5.3.0 "Shota Rustaveli Peak"

	New formats and forms of event- and signal-handlers are supported.
	See \ref so_5_3_0__new_event_handlers_formats for details.

	A form of synchronous interaction with agents is introduced.
	See \ref so_5_3_0__synchronous_interaction for details.

	<i>Ad-hoc agents implemented</i>. <b><i>NOTE. This feature was removed in SObjectizer-5.6.0</i></b>.

	Exception reaction for agents and agent cooperation could be
	inhreited now. See \ref so_5_3_0__exception_reaction for details.

	Several new forms of so_5::api::run_so_environment() added.
	See \ref so_5_3_0__new_run_so_environment for details.

	Namespace so_5::chrono_helpers and the function so_5::chrono_helpers::to_ms()
	added to simplify usage of C++11 std::chrono::duration values.

\section so_5__2_3 5.2.3 "Mijirgi"

	Methods so_5::rt::agent_t::so_subscribe(),
	so_5::rt::agent_t::so_drop_subscription() and
	so_5::rt::agent_t::so_drop_subscription_for_all_states() are made public
	since v.5.2.3.2.

	Class so_5::rt::so_environment_params_t is now moveable (but not
	copyable).

	New exception handling mechanism implemented.
	An enumeration so_5::rt::exception_reaction_t and method
	so_5::rt::agent_t::so_exception_reaction() added.
	Old event_exception_handler_t and related stuff removed.
	For more details see \ref so_5_2_3__exception_reaction.

	A class so_5::rt::coop_dereg_reason_t added. New namespace with
	cooperation deregistration reasons enumeration added:
	so_5::rt::dereg_reason.

	Format of so_5::rt::so_environment_t::deregisted_coop() changed. It is
	necessary to specify reason of cooperation deregistration.

	New sample 'coop_user_resources' added.

	An ability to store some dynamically allocated user resource inside
	cooperation is added via so_5::rt::agent_coop_t::take_under_control()
	method.
	For more details see \ref so_5_2_3__cooperation_controlled_resources.

	The so_5::rt::agent_coop_t contructor is now declared as public. It means
	that it is possible to create classess which are derived from agent_coop_t.
	The agent_coop_t destructor is protected now. So the only way to work
	with agent cooperations is create them as dynamically allocated objects
	and pass pointers to them to so_5::rt::agent_coop_unique_ptr_t wrappers.

	New sample 'coop_notification' added.

	Demands queues now store agent pointers, not smart references as in
	previous versions.

	so_5::rt::msg_coop_registered and so_5::rt::msg_coop_deregistered added.
	so_5::rt::make_coop_reg_notificator() and
	so_5::rt::make_coop_dereg_notificator() added.

	so_5::rt::coop_reg_notificator_t and so_5::rt::coop_dereg_notificator_t
	so_5::rt::agent_coop_t::add_reg_notificator() and
	so_5::rt::agent_coop_t::add_dereg_notificator() are introduced.
	See \ref so_5_2_3__cooperation_notificators for more details.

	Parent-child relationship added for cooperations.
	For the details see \ref so_5_2_3__parent_child_coops.

	Cooperation mutex pool no more used and removed from SObjectizer code.
	Some related method marked as deprecated and will be removed in
	future releases.

\section so_5__2_2 5.2.2 "Tetnuld"

	Method so_5::rt::event_data_t::make_reference added. It returns
	an instance of so_5::rt::smart_atomic_reference_t<MSG> where MSG is the
	same type as in event_data_t.

	Another overloaded method deliver_message() added to so_5::rt::mbox_t.
	It accepts so_5::rt::smart_atomic_reference_t<MSG>.

	Those changes make possible to resending or storing the same message
	without copying a message.

	Method so_5::rt::smart_atomic_reference_t::reset() added.

\section so_5__2_1 5.2.1 "Tetnuld"

	Methods so_5::rt::so_environment_t::register_agent_as_coop() added.

\section so_5__2_0 5.2.0 "Tetnuld"

	Return codes no more used for error reporting in public methods of
	SObjectizer classes. In case of error an exception is thrown.
	All stuff related to return codes (e.g. throwing_strategy_t and so on)
	have been removed. Only exceptions are used now.

	Format of so_5::rt::agent_coop_t::add_agent() methods has been changed.
	Now add_agent() accepts std::unique_ptr and raw so_5::rt::agent_t
	pointers, not agent_ref_t as in previous versions.

	An instance of so_5::rt::so_environment_params_t now is passed to
	so_5::rt::so_environment_t constructor by rvalue reference, not by
	const reference as in previous versions. 

	A template not_null_event_data_t and all related stuff have been removed.

	A new base class for all signals (e.g. messages without any data)
	introduced. Since then all signals classes should be derived from
	so_5::rt::signal_t.

	Special checks for inheritance from so_5::rt::message_t and
	so_5::rt::signal_t inserted into deliver_message/deliver_signal and
	schedule_timer methods. Those checks work in compile-time.

	Special checks for not-null message pointers inserted into deliver_message
	and schedult_timer methods. So it is impossible to use those methods to send
	null messages. Signals should be used for this purpose.

	A version of deliver_message for raw message pointer is added (since
	v.5.2.0.2).

	Some changes to message dispatching scheme.

	Some refactoring of code inside SObjectizer internals.

\section so_5__1_2 5.1.2

	All comments in code have been translated to English.

	Some small code improvements and refactoring.

\section so_5__1_0 5.1.0 "Jimara"

	Transport layer has been rewritten.

	An exception handler/logger facility has been added.

	A cooperation listener has been added.

\section so_5__0_0 5.0.0 "Ushba"

	A first version of new generation of SObjectizer.
*/
// vim:ft=cpp.doxygen
