Agent cooperation. More...

#include <agent_coop.hpp>

Classes
struct	agent_with_disp_binder_t
	Information about agent and its dispatcher binding. More...

Public Member Functions
	coop_t (nonempty_name_t name, disp_binder_unique_ptr_t coop_disp_binder, environment_t &env)
	Constructor. More...

const std::string &	query_coop_name () const
	Get cooperation name. More...

template<class Agent >
Agent *	add_agent (std::unique_ptr< Agent > agent)
	Add agent to cooperation. More...

template<class Agent >
Agent *	add_agent (Agent *agent)
	Add agent to cooperation via raw pointer. More...

template<class Agent >
Agent *	add_agent (std::unique_ptr< Agent > agent, disp_binder_unique_ptr_t disp_binder)
	Add agent to the cooperation with the dispatcher binding. More...

template<class Agent >
Agent *	add_agent (Agent *agent, disp_binder_unique_ptr_t disp_binder)

agent_context_t	make_agent_context () const
	Creation of instance of agent_context for tuning agent options. More...

adhoc_agent_definition_proxy_t	define_agent ()
	Start definition of ad-hoc agent with default dispatcher binding. More...

adhoc_agent_definition_proxy_t	define_agent (agent_context_t ctx)
	Start definition of ad-hoc agent with default dispatcher binding and the custom agent tuning options. More...

adhoc_agent_definition_proxy_t	define_agent (disp_binder_unique_ptr_t binder)
	Start definition of ad-hoc agent with the specific dispatcher binder. More...

adhoc_agent_definition_proxy_t	define_agent (agent_context_t ctx, disp_binder_unique_ptr_t binder)
	Start definition of ad-hoc agent with the specific dispatcher binder and custom agent tuning options. More...

environment_t &	environment () const
	Access to SO Environment for which cooperation is bound. More...

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

template<class Agent , typename... Args>
Agent *	make_agent_with_binder (so_5::disp_binder_unique_ptr_t binder, Args &&... args)
	Helper method for simplification of agents creation and binding to the specified dispatcher. More...

std::size_t	query_agent_count () const
	Get agent count in the cooperation. More...

std::size_t	size () const
	Get agent count in the cooperation. More...

std::size_t	capacity () const
	Get the capacity of vector for holding agents list. More...

void	reserve (std::size_t v)
	Reserve a space for vector for holding agents list. More...

void	deregister (int reason)
	Deregister the cooperation with the specified reason. More...

void	deregister_normally ()
	Deregistr the cooperation normally. More...

Methods for working with name of parent cooperation.
bool	has_parent_coop () const
	Does cooperation have parent cooperation? More...

void	set_parent_coop_name (nonempty_name_t name)
	Set name of the parent cooperation. More...

const std::string &	parent_coop_name () const
	Get name of the parent cooperation. More...

Method for working with notificators.
void	add_reg_notificator (const coop_reg_notificator_t &notificator)
	Add notificator about cooperation registration event. More...

void	add_dereg_notificator (const coop_dereg_notificator_t &notificator)
	Add notificator about cooperation deregistration event. More...

Method for working with user resources.
template<class T >
T *	take_under_control (std::unique_ptr< T > resource)
	Take a user resouce under cooperation control. More...

template<class T >
T *	take_under_control (T *resource)
	Take a user resouce under cooperation control. More...

Exception reaction methods.
void	set_exception_reaction (exception_reaction_t value)
	Set exception reaction for that cooperation. More...

exception_reaction_t	exception_reaction () const
	Get the current exception rection flag for that cooperation. More...

Static Public Member Functions
static void	destroy (coop_t *coop)
	Deleter for agent_coop. More...

static void	increment_usage_count (coop_t &coop)
	Internal SObjectizer method. More...

static void	decrement_usage_count (coop_t &coop)
	Internal SObjectizer method. More...

static void	call_final_deregister_coop (coop_t *coop)
	Internal SObjectizer method. More...

Protected Member Functions
virtual	~coop_t ()

Private Types
enum	registration_status_t { registration_status_t::coop_not_registered, registration_status_t::coop_registered, registration_status_t::coop_deregistering }
	Registration status. More...

typedef std::vector< agent_with_disp_binder_t >	agent_array_t
	Typedef for the agent information container. More...

typedef std::function< void() >	resource_deleter_t
	Type of user resource deleter. More...

typedef std::vector< resource_deleter_t >	resource_deleter_vector_t
	Type of container for user resource deleters. More...

Private Member Functions
	coop_t (const coop_t &)=delete

coop_t &	operator= (const coop_t &)=delete

void	do_add_agent (const agent_ref_t &agent_ref)
	Add agent to cooperation. More...

void	do_add_agent (const agent_ref_t &agent_ref, disp_binder_unique_ptr_t disp_binder)
	Add agent to the cooperation with the dispatcher binding. More...

void	do_registration_specific_actions (coop_t *agent_coop)
	Perform all neccessary actions related to cooperation registration. More...

void	do_deregistration_specific_actions (coop_dereg_reason_t dereg_reason)
	Perform all necessary actions related to cooperation deregistration. More...

void	reorder_agents_with_respect_to_priorities ()
	Rearrangement of agents in agents storage with respect to its priorities. More...

void	bind_agents_to_coop ()
	Bind agents to the cooperation. More...

void	define_all_agents ()
	Calls define_agent method for all cooperation agents. More...

void	bind_agents_to_disp ()
	Bind agents to the dispatcher. More...

void	unbind_agents_from_disp (agent_array_t::iterator it)
	Unbind agent from the dispatcher. More...

void	shutdown_all_agents ()
	Shutdown all agents as a part of cooperation deregistration. More...

void	increment_usage_count ()
	Increment usage counter for this cooperation. More...

void	decrement_usage_count ()

void	final_deregister_coop ()
	Do the final deregistration stage. More...

coop_t *	parent_coop_ptr () const
	Get pointer to the parent cooperation. More...

coop_reg_notificators_container_ref_t	reg_notificators () const
	Get registration notificators. More...

coop_dereg_notificators_container_ref_t	dereg_notificators () const
	Get deregistration notificators. More...

void	delete_user_resources ()
	Delete all user resources. More...

const coop_dereg_reason_t &	dereg_reason () const
	Get deregistration reason. More...

Private Attributes
const std::string	m_coop_name
	Cooperation name. More...

disp_binder_ref_t	m_coop_disp_binder
	Default agent to the dispatcher binder. More...

agent_array_t	m_agent_array
	Cooperation agents. More...

environment_t &	m_env
	SObjectizer Environment for which cooperation is created. More...

atomic_counter_t	m_reference_count
	Count for entities. More...

std::string	m_parent_coop_name
	Name of the parent cooperation. More...

coop_t *	m_parent_coop_ptr
	Pointer to parent cooperation. More...

coop_reg_notificators_container_ref_t	m_reg_notificators
	Notificators for registration event. More...

coop_dereg_notificators_container_ref_t	m_dereg_notificators
	Notificators for deregistration event. More...

std::mutex	m_binding_lock
	A lock for synchonization of evt_start events. More...

registration_status_t	m_registration_status
	The registration status of cooperation. More...

resource_deleter_vector_t	m_resource_deleters
	Container of user resource deleters. More...

coop_dereg_reason_t	m_dereg_reason
	Deregistration reason. More...

exception_reaction_t	m_exception_reaction
	A reaction to non-handled exception. More...

Friends
class	agent_t

class	impl::agent_core_t

class	impl::coop_private_iface_t

Detailed Description

Agent cooperation.

The main purpose of the cooperation is the introducing of several agents into SObjectizer as a single unit. A cooperation should be registered.

For the cooperation to be successfuly registered all of its agents must successfuly pass registration steps (so-define, bind to the dispatcher). If at least one agent out of this cooperation fails to pass any of mentioned steps, the cooperation will not be registered and all of agents will run procedures opposite to registration steps (unbind from the dispatcher, so-undefine) which had been successfuly taken for the particulary agent in the reverse order.

Agents are added to the cooperation by the add_agent() method.

After addition to the cooperation the cooperation takes care about the agent lifetime.

Examples:: so_5/adv_thread_pool_fifo/main.cpp, so_5/blinking_led/main.cpp, so_5/chameneos_prealloc_msgs/main.cpp, so_5/chameneos_simple/main.cpp, so_5/chstate_msg_tracing/main.cpp, so_5/collector_many_performers/main.cpp, so_5/collector_performer_pair/main.cpp, so_5/convert_lib/main.cpp, so_5/coop_notification/main.cpp, so_5/coop_user_resources/main.cpp, so_5/custom_error_logger/main.cpp, so_5/dining_philosophers/main.cpp, so_5/dining_philosophers_2/main.cpp, so_5/disp/main.cpp, so_5/hello_all/main.cpp, so_5/hello_periodic/main.cpp, so_5/hello_world_adhoc/main.cpp, so_5/hello_world_simple_not_mtsafe/main.cpp, so_5/intercom_statechart/main.cpp, so_5/machine_control/main.cpp, so_5/make_pipeline/main.cpp, so_5/many_timers/main.cpp, so_5/mchain_svc_req/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/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/private_dispatcher_for_children/main.cpp, so_5/private_dispatcher_restarts/main.cpp, so_5/producer_consumer_mchain/main.cpp, so_5/queue_size_stats/main.cpp, so_5/redirect_and_transform/main.cpp, so_5/selective_msg_tracing/main.cpp, so_5/simple_message_deadline/main.cpp, so_5/state_deep_history/main.cpp, so_5/stop_guard/main.cpp, so_5/svc/exceptions/main.cpp, so_5/svc/hello/main.cpp, so_5/svc/parallel_sum/main.cpp, so_5/work_generation/main.cpp, so_5/wrapped_env_demo/main.cpp, and so_5/wrapped_env_demo_2/main.cpp.

Member Typedef Documentation

◆ agent_array_t

typedef std::vector< agent_with_disp_binder_t > so_5::coop_t::agent_array_t

private

Typedef for the agent information container.

◆ resource_deleter_t

typedef std::function< void() > so_5::coop_t::resource_deleter_t

private

Type of user resource deleter.

Since: v.5.2.3

◆ resource_deleter_vector_t

typedef std::vector< resource_deleter_t > so_5::coop_t::resource_deleter_vector_t

private

Type of container for user resource deleters.

Since: v.5.2.3

Member Enumeration Documentation

◆ registration_status_t

enum so_5::coop_t::registration_status_t

strongprivate

Registration status.

Since: v.5.2.3

Enumerator

coop_not_registered

Cooperation is not registered yet.

coop_registered

Cooperation is registered.

Reference count for cooperation in that state should be greater than zero.

coop_deregistering

Cooperation is in deregistration process.

Reference count for cooperation in that state should be zero.

Constructor & Destructor Documentation

◆ coop_t() [1/2]

so_5::coop_t::coop_t ( const coop_t & )

privatedelete

◆ ~coop_t()

so_5::coop_t::~coop_t ( )

protectedvirtual

◆ coop_t() [2/2]

so_5::coop_t::coop_t	(	nonempty_name_t	name,
		disp_binder_unique_ptr_t	coop_disp_binder,
		environment_t &	env
	)

Constructor.

Parameters

name	Cooperation name.
coop_disp_binder	Default dispatcher binding.
env	SObjectizer Environment.

Member Function Documentation

◆ add_agent() [1/4]

template<class Agent >

Agent* so_5::coop_t::add_agent ( std::unique_ptr< Agent > agent )

inline

Add agent to cooperation.

Cooperation takes care about agent lifetime.

Default dispatcher binding is used for the agent.

Parameters

agent Agent.

◆ add_agent() [2/4]

template<class Agent >

Agent* so_5::coop_t::add_agent ( Agent * agent )

inline

Add agent to cooperation via raw pointer.

Cooperation takes care about agent lifetime.

Default dispatcher binding is used for the agent.

Parameters

agent Agent.

◆ add_agent() [3/4]

template<class Agent >

Agent* so_5::coop_t::add_agent	(	std::unique_ptr< Agent >	agent,
		disp_binder_unique_ptr_t	disp_binder
	)

inline

Add agent to the cooperation with the dispatcher binding.

Instead of the default dispatcher binding the disp_binder is used for this agent during the cooperation registration.

Parameters

agent	Agent.
disp_binder	Agent to dispatcher binder.

◆ add_agent() [4/4]

template<class Agent >

Agent* so_5::coop_t::add_agent	(	Agent *	agent,
		disp_binder_unique_ptr_t	disp_binder
	)

inline

Add agent to the cooperation via raw pointer and with the dispatcher binding.

Instead of the default dispatcher binding the disp_binder is used for this agent during the cooperation registration.

Parameters

agent	Agent.
disp_binder	Agent to dispatcher binder.

◆ add_dereg_notificator()

void so_5::coop_t::add_dereg_notificator ( const coop_dereg_notificator_t & notificator )

Add notificator about cooperation deregistration event.

Since: v.5.2.3

Examples:: so_5/coop_notification/main.cpp.

◆ add_reg_notificator()

void so_5::coop_t::add_reg_notificator ( const coop_reg_notificator_t & notificator )

Add notificator about cooperation registration event.

Since: v.5.2.3

Examples:: so_5/coop_notification/main.cpp, and so_5/custom_error_logger/main.cpp.

◆ bind_agents_to_coop()

void so_5::coop_t::bind_agents_to_coop ( )

private

Bind agents to the cooperation.

◆ bind_agents_to_disp()

void so_5::coop_t::bind_agents_to_disp ( )

private

Bind agents to the dispatcher.

◆ call_final_deregister_coop()

static void so_5::coop_t::call_final_deregister_coop ( coop_t * coop )

inlinestatic

Internal SObjectizer method.

Initiate a final deregistration stage.

◆ capacity()

std::size_t so_5::coop_t::capacity ( ) const

inline

Get the capacity of vector for holding agents list.

Since: v.5.5.16

◆ decrement_usage_count() [1/2]

static void so_5::coop_t::decrement_usage_count ( coop_t & coop )

inlinestatic

Internal SObjectizer method.

Informs cooperation about full finishing of agent's or child cooperation work.

◆ decrement_usage_count() [2/2]

void so_5::coop_t::decrement_usage_count ( )

private

Process signal about finished work of an agent or child cooperation.

Cooperation deregistration is a long process. All agents process events out of their queues. When an agent detects that no more events in its queue it informs the cooperation about this.

When cooperation detects that all agents have finished their work it initiates the agent's destruction.

Since v.5.2.3 this method used not only for agents of cooperation but and for children cooperations. Because final step of cooperation deregistration could be initiated only when all children cooperations are deregistered and destroyed.

◆ define_agent() [1/4]

adhoc_agent_definition_proxy_t so_5::coop_t::define_agent ( )

inline

Start definition of ad-hoc agent with default dispatcher binding.

Since: v.5.3.0

Usage sample:

coop->define_agent()
    // Set initial agent action.
  .on_start( []() { std::cout << "Hello!" << std::endl; }
  // Set last agent action.
  .on_finish( []() { std::cout << "Bye!" << std::endl; }
  // Subscribe to message from a mbox.
  .event( mbox, []() { ... } );
  // Subscribe to signal from a mbox.
  .event( mbox, so_5::signal< Sig >, []() { ... } );

Examples:: so_5/adv_thread_pool_fifo/main.cpp, so_5/convert_lib/main.cpp, so_5/custom_error_logger/main.cpp, so_5/hello_periodic/main.cpp, so_5/hello_world_adhoc/main.cpp, so_5/hello_world_simple_not_mtsafe/main.cpp, so_5/machine_control/main.cpp, so_5/mchain_svc_req/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, so_5/svc/exceptions/main.cpp, so_5/svc/hello/main.cpp, so_5/svc/parallel_sum/main.cpp, and so_5/wrapped_env_demo_2/main.cpp.

◆ define_agent() [2/4]

adhoc_agent_definition_proxy_t so_5::coop_t::define_agent ( agent_context_t ctx )

inline

Start definition of ad-hoc agent with default dispatcher binding and the custom agent tuning options.

Since: v.5.5.8

Usage sample:

coop->define_agent( coop->make_agent_context() + so_5::prio::p7 )
    // Set initial agent action.
  .on_start( []() { std::cout << "Hello!" << std::endl; }
  // Set last agent action.
  .on_finish( []() { std::cout << "Bye!" << std::endl; }
  // Subscribe to message from a mbox.
  .event( mbox, []() { ... } );
  // Subscribe to signal from a mbox.
  .event( mbox, so_5::signal< Sig >, []() { ... } );

Parameters

ctx	Agent tuning options.

◆ define_agent() [3/4]

adhoc_agent_definition_proxy_t so_5::coop_t::define_agent ( disp_binder_unique_ptr_t binder )

inline

Start definition of ad-hoc agent with the specific dispatcher binder.

Since: v.5.3.0

Usage sample:

coop->define_agent(
    so_5::disp::active_obj::create_disp_binder( "active_obj" ) )
    // Set initial agent action.
  .on_start( []() { std::cout << "Hello!" << std::endl; }
  // Set last agent action.
  .on_finish( []() { std::cout << "Bye!" << std::endl; }
  // Subscribe to message from a mbox.
  .event( mbox, []() { ... } );
  // Subscribe to signal from a mbox.
  .event( mbox, so_5::signal< Sig >, []() { ... } );

Parameters

binder A binder to the dispatcher.

◆ define_agent() [4/4]

adhoc_agent_definition_proxy_t so_5::coop_t::define_agent	(	agent_context_t	ctx,
		disp_binder_unique_ptr_t	binder
	)

inline

Start definition of ad-hoc agent with the specific dispatcher binder and custom agent tuning options.

Since: v.5.5.8

Usage sample:

coop->define_agent(
    coop->make_agent_context() + so_5::prio::p7,
    so_5::disp::active_obj::create_disp_binder( "active_obj" ) )
    // Set initial agent action.
  .on_start( []() { std::cout << "Hello!" << std::endl; }
  // Set last agent action.
  .on_finish( []() { std::cout << "Bye!" << std::endl; }
  // Subscribe to message from a mbox.
  .event( mbox, []() { ... } );
  // Subscribe to signal from a mbox.
  .event( mbox, so_5::signal< Sig >, []() { ... } );

Parameters

ctx	Agent tuning options.
binder	A binder to the dispatcher.

◆ define_all_agents()

void so_5::coop_t::define_all_agents ( )

private

Calls define_agent method for all cooperation agents.

◆ delete_user_resources()

void so_5::coop_t::delete_user_resources ( )

private

Delete all user resources.

Since: v.5.2.3

◆ dereg_notificators()

coop_dereg_notificators_container_ref_t so_5::coop_t::dereg_notificators ( ) const

private

Get deregistration notificators.

Since: v.5.2.3

◆ dereg_reason()

const coop_dereg_reason_t & so_5::coop_t::dereg_reason ( ) const

private

Get deregistration reason.

Since: v.5.2.3

◆ deregister()

void so_5::coop_t::deregister ( int reason )

Deregister the cooperation with the specified reason.

Since: v.5.5.8

Usage example:: so_5::environment_t & env = ...;
env.introduce_coop( []( so_5::coop_t & coop ) {
coop.define_agent()
.event< some_signal >( some_mbox, [&coop] {
...
coop.deregister( so_4::dereg_reason::user_defined_reason + 100 );
} );
} );

Note: This method is just a shorthand for:
so_5::coop_t & coop = ...;
coop.environment().deregister_coop( coop.query_coop_name(), reason );

Parameters

reason Reason of cooperation deregistration.

◆ deregister_normally()

void so_5::coop_t::deregister_normally ( )

inline

Deregistr the cooperation normally.

Since: v.5.5.8

Note: This method is just a shorthand for:
so_5::coop_t & coop = ...;
coop.deregister( so_5::dereg_reason::normal );

Examples:: so_5/wrapped_env_demo_2/main.cpp.

◆ destroy()

void so_5::coop_t::destroy ( coop_t * coop )

static

Deleter for agent_coop.

Since: v.5.2.3

◆ do_add_agent() [1/2]

void so_5::coop_t::do_add_agent ( const agent_ref_t & agent_ref )

private

Add agent to cooperation.

Cooperation takes care about agent lifetime.

Default dispatcher binding is used for the agent.

◆ do_add_agent() [2/2]

void so_5::coop_t::do_add_agent	(	const agent_ref_t &	agent_ref,
		disp_binder_unique_ptr_t	disp_binder
	)

private

Add agent to the cooperation with the dispatcher binding.

Instead of the default dispatcher binding the disp_binder is used for this agent during the cooperation registration.

Parameters

agent_ref	Agent.
disp_binder	Agent to dispatcher binder.

◆ do_deregistration_specific_actions()

void so_5::coop_t::do_deregistration_specific_actions ( coop_dereg_reason_t dereg_reason )

private

Perform all necessary actions related to cooperation deregistration.

Since: v.5.2.3

Parameters

dereg_reason Deregistration reason.

◆ do_registration_specific_actions()

void so_5::coop_t::do_registration_specific_actions ( coop_t * agent_coop )

private

Perform all neccessary actions related to cooperation registration.

Since: v.5.2.3

Parameters

agent_coop Pointer to the parent cooperation. Contains nullptr if there is no parent cooperation.

◆ environment()

environment_t& so_5::coop_t::environment ( ) const

inline

Access to SO Environment for which cooperation is bound.

Since: v.5.3.0

Examples:: so_5/convert_lib/main.cpp, so_5/machine_control/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/svc/hello/main.cpp.

◆ exception_reaction()

exception_reaction_t so_5::coop_t::exception_reaction ( ) const

Get the current exception rection flag for that cooperation.

Since: v.5.3.0

It uses the following logic:

if own's exception_reaction flag value differs from inherit_exception_reaction value than own's exception_reaction flag value returned;
otherwise if there is a parent cooperation than parent coop's exception_reaction value returned;
otherwise SO Environment's exception_reaction is returned.

◆ final_deregister_coop()

void so_5::coop_t::final_deregister_coop ( )

private

Do the final deregistration stage.

◆ has_parent_coop()

bool so_5::coop_t::has_parent_coop ( ) const

Does cooperation have parent cooperation?

Since: v.5.2.3

◆ increment_usage_count() [1/2]

static void so_5::coop_t::increment_usage_count ( coop_t & coop )

inlinestatic

Internal SObjectizer method.

Since: v.5.2.3

Informs cooperation that it is used by yet another entity.

◆ increment_usage_count() [2/2]

void so_5::coop_t::increment_usage_count ( )

private

Increment usage counter for this cooperation.

Since: v.5.2.3

In v.5.2.3 the counter m_reference_count is used to reflect count of references to the cooperation. There are the following entities who can refer to cooperation:

agents from that cooperation. When cooperation is successfully registered the counter is incremented by count of agents. During cooperation deregistration agents finish their work and each agent decrement cooperation usage counter;
children cooperations. Each child cooperation increments reference counter on its registration and decrements counter on its deregistration;
cooperation registration routine. It increment reference counter to prevent cooperation deregistration before the end of registration process. It is possible if cooperation do its work very quickly and initiates deregistration. When cooperation has coop_notificators its registration process may be longer then cooperation working time. And cooperation could be deregistered and even destroyed before return from registration routine. To prevent this cooperation registration routine increments cooperation usage counter and the begin of process and decrement it when registration process finished.

◆ make_agent()

template<class Agent , typename... Args>

Agent* so_5::coop_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 and adds it to the cooperation.

Returns: 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::coop_unique_ptr_t coop = env.create_coop( so_5::autoname );
// For the case of constructor like my_agent(environmen_t&).
coop->make_agent< my_agent >();
// For the case of constructor like your_agent(environment_t&, std::string).
auto ya = coop->make_agent< your_agent >( "hello" );
// For the case of constructor like thier_agent(environment_t&, std::string, mbox_t).
coop->make_agent< their_agent >( "bye", ya->so_direct_mbox() );

Examples:: so_5/adv_thread_pool_fifo/main.cpp, so_5/blinking_led/main.cpp, so_5/chameneos_prealloc_msgs/main.cpp, so_5/chameneos_simple/main.cpp, so_5/chstate_msg_tracing/main.cpp, so_5/collector_many_performers/main.cpp, so_5/collector_performer_pair/main.cpp, so_5/coop_notification/main.cpp, so_5/coop_user_resources/main.cpp, so_5/dining_philosophers/main.cpp, so_5/dining_philosophers_2/main.cpp, so_5/disp/main.cpp, so_5/hello_all/main.cpp, so_5/intercom_statechart/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/news_board/main.cpp, so_5/nohandler_msg_tracing/main.cpp, so_5/parent_coop/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/private_dispatcher_restarts/main.cpp, so_5/queue_size_stats/main.cpp, so_5/redirect_and_transform/main.cpp, so_5/selective_msg_tracing/main.cpp, so_5/simple_message_deadline/main.cpp, so_5/state_deep_history/main.cpp, so_5/stop_guard/main.cpp, so_5/svc/exceptions/main.cpp, so_5/svc/hello/main.cpp, so_5/svc/parallel_sum/main.cpp, so_5/work_generation/main.cpp, so_5/wrapped_env_demo/main.cpp, and so_5/wrapped_env_demo_2/main.cpp.

◆ make_agent_context()

agent_context_t so_5::coop_t::make_agent_context ( ) const

inline

Creation of instance of agent_context for tuning agent options.

Since: v.5.5.8

Examples:: so_5/news_board/main.cpp, and so_5/prio_work_stealing/main.cpp.

◆ make_agent_with_binder()

template<class Agent , typename... Args>

Agent* so_5::coop_t::make_agent_with_binder	(	so_5::disp_binder_unique_ptr_t	binder,
		Args &&...	args
	)

inline

Helper method for simplification of agents creation and binding to the specified dispatcher.

Since: v.5.5.4

Note: Creates an instance of agent of type Agent and adds it to the cooperation with the specified binder.

Returns: 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::disp::one_thread::private_dispatcher_handler_t disp =
so_5::disp::one_thread::create_private_disp();
so_5::coop_unique_ptr_t coop = env.create_coop( so_5::autoname );
// For the case of constructor like my_agent(environmen_t&).
coop->make_agent_with_binder< my_agent >( disp->binder() );
// For the case of constructor like your_agent(environment_t&, std::string).
auto ya = coop->make_agent_with_binder< your_agent >( disp->binder(), "hello" );
// For the case of constructor like thier_agent(environment_t&, std::string, mbox_t).
coop->make_agent_with_binder< their_agent >( disp->binder(), "bye", ya->so_direct_mbox() );

Parameters

binder	A dispatcher binder for the new agent.
args	Arguments to be passed to the agent's constructor.

Examples:: so_5/collector_many_performers/main.cpp, so_5/collector_performer_pair/main.cpp, so_5/disp/main.cpp, so_5/machine_control/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, and so_5/work_generation/main.cpp.

◆ operator=()

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

privatedelete

◆ parent_coop_name()

const std::string & so_5::coop_t::parent_coop_name ( ) const

Get name of the parent cooperation.

Since: v.5.2.3

Exceptions

exception_t if the parent cooperation name is not set.

◆ parent_coop_ptr()

coop_t * so_5::coop_t::parent_coop_ptr ( ) const

private

Get pointer to the parent cooperation.

Since: v.5.2.3

Return values

nullptr if there is no parent cooperation.

◆ query_agent_count()

std::size_t so_5::coop_t::query_agent_count ( ) const

inline

Get agent count in the cooperation.

Since: v.5.5.4

◆ query_coop_name()

const std::string & so_5::coop_t::query_coop_name ( ) const

Get cooperation name.

Examples:: so_5/coop_notification/main.cpp, and so_5/custom_error_logger/main.cpp.

◆ reg_notificators()

coop_reg_notificators_container_ref_t so_5::coop_t::reg_notificators ( ) const

private

Get registration notificators.

Since: v.5.2.3

◆ reorder_agents_with_respect_to_priorities()

void so_5::coop_t::reorder_agents_with_respect_to_priorities ( )

private

Rearrangement of agents in agents storage with respect to its priorities.

Since: v.5.5.8

This step is necessary to handle agents with high priorities before agents with low priorities.

◆ reserve()

void so_5::coop_t::reserve ( std::size_t v )

inline

Reserve a space for vector for holding agents list.

Since: v.5.5.16

This method can help avoid reallocations of agents list during filling the coop:

env.introduce_coop( []( so_5::coop_t & coop ) {
  coop.reserve( agents_count );
  for( size_t i = 0; i != agents_count; ++i )
    coop.make_agent< some_type >( some_args );
} );

◆ set_exception_reaction()

void so_5::coop_t::set_exception_reaction ( exception_reaction_t value )

Set exception reaction for that cooperation.

Since: v.5.3.0

This value will be used by agents and children cooperation if they use inherit_exception_reaction value.

Examples:: so_5/coop_notification/main.cpp.

◆ set_parent_coop_name()

void so_5::coop_t::set_parent_coop_name ( nonempty_name_t name )

Set name of the parent cooperation.

Since: v.5.2.3

◆ shutdown_all_agents()

void so_5::coop_t::shutdown_all_agents ( )

private

Shutdown all agents as a part of cooperation deregistration.

Since: v.5.2.3

An exception from agent_t::shutdown_agent() leads to call to abort().

◆ size()

std::size_t so_5::coop_t::size ( ) const

inline

Get agent count in the cooperation.

Since: v.5.5.16

Note: Just an alias for query_agent_count().

◆ take_under_control() [1/2]

template<class T >

T* so_5::coop_t::take_under_control ( std::unique_ptr< T > resource )

inline

Take a user resouce under cooperation control.

Since: v.5.2.3

Examples:: so_5/coop_user_resources/main.cpp, so_5/machine_control/main.cpp, so_5/news_board/main.cpp, and so_5/prio_work_stealing/main.cpp.

◆ take_under_control() [2/2]

template<class T >

T* so_5::coop_t::take_under_control ( T * resource )

inline

Take a user resouce under cooperation control.

Since: v.5.2.3

◆ unbind_agents_from_disp()

void so_5::coop_t::unbind_agents_from_disp ( agent_array_t::iterator it )

inlineprivate

Unbind agent from the dispatcher.

Unbinds all agents in range [m_agent_array.begin(), it).

Parameters

it	Right border of the processing range.

Friends And Related Function Documentation

◆ agent_t

friend class agent_t

friend

Deprecated:: Will be removed in v.5.6.0. Use so_5::agent_t instead.

◆ impl::agent_core_t

friend class impl::agent_core_t

friend

◆ impl::coop_private_iface_t

friend class impl::coop_private_iface_t

friend

Member Data Documentation

◆ m_agent_array

agent_array_t so_5::coop_t::m_agent_array

private

Cooperation agents.

◆ m_binding_lock

std::mutex so_5::coop_t::m_binding_lock

private

A lock for synchonization of evt_start events.

Since: v.5.5.8

A new way of handling coop registration was introduced in v.5.5.8. Agents from the coop cannot start its work before finish of main coop registration actions (expecialy before end of such important step as binding agents to dispatchers). But some agents could receive evt_start event before end of agents binding step. Those agents will be stopped on this lock.

Coop acquires this lock before agents binding step and releases just after that. Every agent tries to acquire it during handling of evt_start. If lock is belong to coop then an agent will be stopped until the lock will be released.

◆ m_coop_disp_binder

disp_binder_ref_t so_5::coop_t::m_coop_disp_binder

private

Default agent to the dispatcher binder.

◆ m_coop_name

const std::string so_5::coop_t::m_coop_name

private

Cooperation name.

◆ m_dereg_notificators

coop_dereg_notificators_container_ref_t so_5::coop_t::m_dereg_notificators

private

Notificators for deregistration event.

Since: v.5.2.3

◆ m_dereg_reason

coop_dereg_reason_t so_5::coop_t::m_dereg_reason

private

Deregistration reason.

Since: v.5.2.3

Receives actual value only in do_deregistration_specific_actions().

◆ m_env

environment_t& so_5::coop_t::m_env

private

SObjectizer Environment for which cooperation is created.

◆ m_exception_reaction

exception_reaction_t so_5::coop_t::m_exception_reaction

private

A reaction to non-handled exception.

Since: v.5.3.0

By default inherit_exception_reaction is used. It means that actual exception reaction should be provided by parent coop or by SO Environment.

◆ m_parent_coop_name

std::string so_5::coop_t::m_parent_coop_name

private

Name of the parent cooperation.

Since: v.5.2.3.

Empty value means than there is no parent cooperation.

◆ m_parent_coop_ptr

coop_t* so_5::coop_t::m_parent_coop_ptr

private

Pointer to parent cooperation.

Since: v.5.2.3.

Gets the value only if there is the parent cooperation and cooperation itself is registered successfully.

◆ m_reference_count

atomic_counter_t so_5::coop_t::m_reference_count

private

Count for entities.

Since v.5.2.3 this counter includes:

count of agents from cooperation;
count of direct child cooperations;
usage of cooperation pointer in cooperation registration routine.

See also: coop_t::increment_usage_count()

◆ m_reg_notificators

coop_reg_notificators_container_ref_t so_5::coop_t::m_reg_notificators

private

Notificators for registration event.

Since: v.5.2.3

◆ m_registration_status

registration_status_t so_5::coop_t::m_registration_status

private

The registration status of cooperation.

Since: v.5.2.3

By default cooperation has NOT_REGISTERED status. It is changed to REGISTERED after successfull completion of all registration-specific actions.

And then changed to DEREGISTERING when m_reference_count becames zero and final deregistration demand would be put to deregistration thread.

◆ m_resource_deleters

resource_deleter_vector_t so_5::coop_t::m_resource_deleters

private

Container of user resource deleters.

Since: v.5.2.3

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

Classes

Public Member Functions

Static Public Member Functions

Protected Member Functions

Private Types

Private Member Functions

Private Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ agent_array_t

◆ resource_deleter_t

◆ resource_deleter_vector_t

Member Enumeration Documentation

◆ registration_status_t

Constructor & Destructor Documentation

◆ coop_t() [1/2]

◆ ~coop_t()

◆ coop_t() [2/2]

Member Function Documentation

◆ add_agent() [1/4]

◆ add_agent() [2/4]

◆ add_agent() [3/4]

◆ add_agent() [4/4]

◆ add_dereg_notificator()

◆ add_reg_notificator()

◆ bind_agents_to_coop()

◆ bind_agents_to_disp()

◆ call_final_deregister_coop()

◆ capacity()

◆ decrement_usage_count() [1/2]

◆ decrement_usage_count() [2/2]

◆ define_agent() [1/4]

◆ define_agent() [2/4]

◆ define_agent() [3/4]

◆ define_agent() [4/4]

◆ define_all_agents()

◆ delete_user_resources()

◆ dereg_notificators()

◆ dereg_reason()

◆ deregister()

◆ deregister_normally()

◆ destroy()

◆ do_add_agent() [1/2]

◆ do_add_agent() [2/2]

◆ do_deregistration_specific_actions()

◆ do_registration_specific_actions()

◆ environment()

◆ exception_reaction()

◆ final_deregister_coop()

◆ has_parent_coop()

◆ increment_usage_count() [1/2]

◆ increment_usage_count() [2/2]

◆ make_agent()

◆ make_agent_context()

◆ make_agent_with_binder()

◆ operator=()

◆ parent_coop_name()

◆ parent_coop_ptr()

◆ query_agent_count()

◆ query_coop_name()

◆ reg_notificators()

◆ reorder_agents_with_respect_to_priorities()

◆ reserve()

◆ set_exception_reaction()

◆ set_parent_coop_name()

◆ shutdown_all_agents()

◆ size()

◆ take_under_control() [1/2]

◆ take_under_control() [2/2]

◆ unbind_agents_from_disp()

Friends And Related Function Documentation

◆ agent_t

◆ impl::agent_core_t

◆ impl::coop_private_iface_t

Member Data Documentation

◆ m_agent_array

◆ m_binding_lock

◆ m_coop_disp_binder

◆ m_coop_name