dev/so_5/coop.cpp

/*
	SObjectizer 5.
*/

#include <so_5/coop.hpp>

#include <so_5/impl/internal_env_iface.hpp>
#include <so_5/impl/internal_agent_iface.hpp>
#include <so_5/impl/agent_ptr_compare.hpp>

#include <so_5/details/abort_on_fatal_error.hpp>

#include <so_5/exception.hpp>
#include <so_5/environment.hpp>

#include <exception>
#include <algorithm>

namespace so_5
{

//
// coop_reg_notificators_container_t
//
void
coop_reg_notificators_container_t::call_all(
	environment_t & env,
	const coop_handle_t & coop ) const noexcept
	{
		for( auto & n : m_notificators )
			n( env, coop );
	}

//
// coop_dereg_notificators_container_t
//
void
coop_dereg_notificators_container_t::call_all(
	environment_t & env,
	const coop_handle_t & coop,
	const coop_dereg_reason_t & reason ) const noexcept
	{
		for( auto & n : m_notificators )
			n( env, coop, reason );
	}

namespace impl
{

//
// coop_impl_t
//
void
coop_impl_t::destroy_content(
	coop_t & coop ) noexcept
	{
		using std::swap;

		// Initiate deleting of agents by hand to guarantee that
		// agents will be destroyed before return from coop_t
		// destructor.
		//
		// NOTE: because agents are stored here by smart references
		// for some agents this operation will lead only to reference
		// counter descrement. Not to deletion of agent.
		decltype(coop.m_agent_array) agents;
		swap( coop.m_agent_array, agents );

		agents.clear();

		// Now all user resources should be destroyed.
		decltype(coop.m_resource_deleters) resources;
		swap( coop.m_resource_deleters, resources );

		for( auto & d : resources )
			d();
	}

void
coop_impl_t::do_add_agent(
	coop_t & coop,
	agent_ref_t agent_ref )
	{
		coop.m_agent_array.emplace_back(
				std::move(agent_ref), coop.m_coop_disp_binder );
	}

void
coop_impl_t::do_add_agent(
	coop_t & coop,
	agent_ref_t agent_ref,
	disp_binder_shptr_t disp_binder )
	{
		coop.m_agent_array.emplace_back(
				std::move(agent_ref), std::move(disp_binder) );
	}

namespace
{
	/*!
	 * \since
	 * v.5.2.3
	 *
	 * \brief Helper function for notificator addition.
	 */
	template< class C, class N >
	inline void
	do_add_notificator_to(
		intrusive_ptr_t< C > & to,
		N notificator )
	{
		if( !to )
		{
			to = intrusive_ptr_t< C >( new C() );
		}

		to->add( std::move(notificator) );
	}

} /* namespace anonymous */

void
coop_impl_t::add_reg_notificator(
	coop_t & coop,
	coop_reg_notificator_t notificator )
	{
		do_add_notificator_to(
				coop.m_reg_notificators,
				std::move(notificator) );
	}

void
coop_impl_t::add_dereg_notificator(
	coop_t & coop,
	coop_dereg_notificator_t notificator )
	{
		do_add_notificator_to(
				coop.m_dereg_notificators,
				std::move(notificator) );
	}

[[nodiscard]]
exception_reaction_t
coop_impl_t::exception_reaction(
	const coop_t & coop ) noexcept
	{
		if( inherit_exception_reaction == coop.m_exception_reaction )
			{
				const auto parent = so_5::low_level_api::to_shptr_noexcept(
						coop.m_parent );
				if( parent )
					return parent->exception_reaction();
				else
					return coop.environment().exception_reaction();
			}

		return coop.m_exception_reaction;
	}

void
coop_impl_t::do_decrement_reference_count(
	coop_t & coop ) noexcept
	{
		// If it is the last working agent then Environment should be
		// informed that the cooperation is ready to be deregistered.
		if( 0 == --coop.m_reference_count )
			{
				// NOTE: usage counter incremented and decremented during
				// registration process even if registration of cooperation failed.
				// So decrement_usage_count() could be called when cooperation
				// has coop_not_registered status.
				//
				// It is possible that reference counter become 0 several times.
				// For example when a child coop is being registered while
				// the parent coop is in deregistration process.
				// Because of that it is necessary to check the current status
				// of the coop.
				//
				// If the coop should be deregistered finally its status should
				// be changed to deregistration_in_final_stage.
				const auto should_finalize = [&] {
					std::lock_guard< std::mutex > lock{ coop.m_lock };

					using status_t = coop_t::registration_status_t;
					if( status_t::coop_registered == coop.m_registration_status ||
						status_t::coop_deregistering == coop.m_registration_status )
						{
							coop.m_registration_status =
									status_t::deregistration_in_final_stage;
							return true;
						}
					else
						return false;
				};

				if( should_finalize() )
					{
						impl::internal_env_iface_t{ coop.m_env.get() }
								.ready_to_deregister_notify( coop.shared_from_this() );
					}
			}
	}

class coop_impl_t::registration_performer_t
	{
		coop_t & m_coop;

		void
		perform_actions_without_rollback_on_exception()
			{
				reorder_agents_with_respect_to_priorities();
				bind_agents_to_coop();
				preallocate_disp_resources();
			}

		void
		perform_actions_with_rollback_on_exception()
			{
				so_5::details::do_with_rollback_on_exception( [this] {
						define_all_agents();

						// Coop's lock should be acquired before notification
						// of the parent coop.
						std::lock_guard< std::mutex > lock{ m_coop.m_lock };
						make_relation_with_parent_coop();

						// These actions shouldn't throw.
						details::invoke_noexcept_code( [&] {
							// This operation shouldn't throw because dispatchers
							// allocated resources for agents.
							//
							// But it is possible that an exception will be throw
							// during an attempt to send evt_start message to agents.
							// In that case it is simpler to call std::terminate().
							bind_agents_to_disp();

							// Cooperation should assume that it is registered now.
							m_coop.m_registration_status =
									coop_t::registration_status_t::coop_registered;

							// Increment reference count to reflect that cooperation
							// is registered. This is necessary in v.5.5.12 to prevent
							// automatic deregistration of the cooperation right after
							// finish of registration process for empty cooperation.
							m_coop.increment_usage_count();
						} );
					},
					[this] {
						// NOTE: we use the fact that actual binding of agents to
						// dispatchers can't throw. It means that exception was thrown
						// at earlier stages (in define_all_agents() or
						// make_relation_with_parent_coop()).
						deallocate_disp_resources();
					} );
			}

		void
		reorder_agents_with_respect_to_priorities() noexcept
			{
				std::sort(
						std::begin(m_coop.m_agent_array),
						std::end(m_coop.m_agent_array),
						[]( const auto & a, const auto & b ) noexcept {
							return special_agent_ptr_compare(
									*a.m_agent_ref, *b.m_agent_ref );
						} );
			}

		void
		bind_agents_to_coop()
			{
				for( auto & i : m_coop.m_agent_array )
					internal_agent_iface_t{ *i.m_agent_ref }.bind_to_coop( m_coop );
			}

		void
		preallocate_disp_resources()
			{
				// In case of an exception we should undo preallocation only for
				// those agents for which preallocation was successful.
				coop_t::agent_array_t::iterator it;
				try
					{
						for( it = m_coop.m_agent_array.begin();
								it != m_coop.m_agent_array.end();
								++it )
							{
								it->m_binder->preallocate_resources(
										*(it->m_agent_ref) );
							}
					}
				catch( const std::exception & x )
					{
						// All preallocated resources should be returned back.
						for( auto it2 = m_coop.m_agent_array.begin();
								it2 != it;
								++it2 )
							{
								it2->m_binder->undo_preallocation(
										*(it2->m_agent_ref) );
							}

						SO_5_THROW_EXCEPTION(
								rc_agent_to_disp_binding_failed,
								std::string{
										"an exception during the first stage of "
										"binding agent to the dispatcher, exception: " }
								+ x.what() );
					}
			}

		void
		define_all_agents()
			{
				try
					{
						for( auto & info : m_coop.m_agent_array )
							internal_agent_iface_t{ *info.m_agent_ref }
									.initiate_agent_definition();
					}
				catch( const exception_t & )
					{
						throw;
					}
				catch( const std::exception & ex )
					{
						SO_5_THROW_EXCEPTION(
							rc_coop_define_agent_failed,
							ex.what() );
					}
				catch( ... )
					{
						SO_5_THROW_EXCEPTION(
							rc_coop_define_agent_failed,
							"exception of unknown type has been thrown in "
							"so_define_agent()" );
					}
			}

		void
		make_relation_with_parent_coop()
			{
				so_5::low_level_api::to_shptr(m_coop.m_parent)->add_child(
						m_coop.shared_from_this() );
			}

		void
		bind_agents_to_disp() noexcept
			{
				for( auto & info : m_coop.m_agent_array )
					info.m_binder->bind( *info.m_agent_ref );
			}

		void
		deallocate_disp_resources() noexcept
			{
				for( auto & info : m_coop.m_agent_array )
					info.m_binder->undo_preallocation( *(info.m_agent_ref) );
			}

	public :
		explicit registration_performer_t( coop_t & coop ) noexcept
			:	m_coop{ coop }
			{}

		void
		perform()
			{
				// On first phase we perform actions that don't require
				// any rollback on exception.
				perform_actions_without_rollback_on_exception();

				// Then we should perform some actions that require some
				// rollback in the case of an exception.
				perform_actions_with_rollback_on_exception();
			}
	};

void
coop_impl_t::do_registration_specific_actions( coop_t & coop )
	{
		registration_performer_t{ coop }.perform();
	}

//
// deregistration_performer_t
//
//! A helper for coop's deregistration procedure.
class coop_impl_t::deregistration_performer_t
	{
		coop_t & m_coop;
		const coop_dereg_reason_t m_reason;

		enum class phase1_result_t
			{
				dereg_initiated,
				dereg_already_in_progress
			};

		phase1_result_t
		perform_phase1() noexcept
			{
				// The first phase should be performed on locked object.
				std::lock_guard< std::mutex > lock{ m_coop.m_lock };

				if( coop_t::registration_status_t::coop_registered !=
						m_coop.m_registration_status )
					// Deregistration is already in progress.
					// Nothing to do.
					return phase1_result_t::dereg_already_in_progress;

				// Deregistration process should be started.
				m_coop.m_registration_status =
						coop_t::registration_status_t::coop_deregistering;
				m_coop.m_dereg_reason = m_reason;

				initiate_deregistration_for_children();

				return phase1_result_t::dereg_initiated;
			}

		void
		shutdown_all_agents() noexcept
			{
				for( auto & info : m_coop.m_agent_array )
					internal_agent_iface_t{ *info.m_agent_ref }.shutdown_agent();
			}

		void
		initiate_deregistration_for_children() noexcept
			{
				m_coop.for_each_child( []( coop_t & coop ) {
						coop.deregister( dereg_reason::parent_deregistration );
					} );
			}

	public :
		deregistration_performer_t(
			coop_t & coop,
			coop_dereg_reason_t reason ) noexcept
			:	m_coop{ coop }
			,	m_reason{ reason }
			{}

		void
		perform() noexcept
			{
				auto result = perform_phase1();

				if( phase1_result_t::dereg_initiated == result )
					{
						// Deregistration is initiated the first time.

						// All agents should be shut down.
						shutdown_all_agents();

						// Reference count to this coop can be decremented.
						// If there is no more uses of that coop then the coop
						// will be deregistered completely.
						m_coop.decrement_usage_count();
					}
			}
	};

void
coop_impl_t::do_deregistration_specific_actions(
	coop_t & coop,
	coop_dereg_reason_t reason ) noexcept
	{
		deregistration_performer_t{ coop, reason }.perform();
	}

void
coop_impl_t::do_final_deregistration_actions(
	coop_t & coop )
	{
		// Agents should be unbound from their dispatchers.
		for( auto & info : coop.m_agent_array )
			info.m_binder->unbind( *info.m_agent_ref );

		// Now the coop can be removed from it's parent.
		// We don't except an exception here because m_parent should
		// contain an actual value.
		// But if not then we have a serious problem and it is better
		// to terminate the application.
		so_5::low_level_api::to_shptr(coop.m_parent)->remove_child( coop );
	}

void
coop_impl_t::do_add_child(
	coop_t & parent,
	coop_shptr_t child )
	{
		// Count of users on this coop is incremented.
		parent.increment_usage_count();

		// If an exception is throw below then usage count for the parent
		// coop should be decremented.
		so_5::details::do_with_rollback_on_exception( [&] {
				// Modification of parent-child relationship must be performed
				// on locked object.
				std::lock_guard< std::mutex > lock{ parent.m_lock };

				// A new coop can't be added as a child if coop is being
				// deregistered.
				if( coop_t::registration_status_t::coop_registered !=
						parent.m_registration_status )
					SO_5_THROW_EXCEPTION(
							rc_coop_is_not_in_registered_state,
							"add_child() can be processed only when coop "
							"is registered" );

				// New child will be inserted to the head of children list.
				if( parent.m_first_child )
					parent.m_first_child->m_prev_sibling = child;

				child->m_next_sibling = std::move(parent.m_first_child);

				parent.m_first_child = std::move(child);
			},
			[&parent] {
				// Something went wrong. Count of references should be
				// returned back.
				parent.decrement_usage_count();
			} );
	}

void
coop_impl_t::do_remove_child(
	coop_t & parent,
	coop_t & child )
	{
		{
			// Modification of parent-child relationship must be performed
			// on locked object.
			std::lock_guard< std::mutex > lock{ parent.m_lock };

			if( parent.m_first_child.get() == &child )
			{
				// Child was a head of children chain. There is no prev-sibling
				// for the child to be removed.
				parent.m_first_child = child.m_next_sibling;
				if( parent.m_first_child )
					parent.m_first_child->m_prev_sibling.reset();
			}
			else
			{
				child.m_prev_sibling->m_next_sibling = child.m_next_sibling;
				if( child.m_next_sibling )
					child.m_next_sibling->m_prev_sibling = child.m_prev_sibling;
			}
		}

		// Count of references to the parent coop can be decremented now.
		parent.decrement_usage_count();
	}

} /* namespace impl */

} /* namespace so_5 */