so-5.2.3 Parent-child cooperation relationship

General idea

Parent-child cooperation relationship from SObjectizer-4 is implemented in version 5.2.3. It allows to specify the parent cooperation for a new cooperation before a new cooperation registration. In this way, if the parent cooperation deregistered all its children cooperations will be deregistered automatically. If some child cooperation has its own children cooperations they will be deregistered as well.

The parent-child relation serves for two main purposes:

1. Simplification for management of child agent which performs some part of parent cooperation tasks. For example parent cooperation could receipt user requests and create child cooperations for serving those requests. When parent cooperation is being deregistered all of its children cooperations should be deregistered too. And since v.5.2.3 it is done automatically.
2. Simplification for resource management. For example, an agent from parent cooperation could create some resource like DB connection object. And afterwards, it passes reference to that object to child cooperation agents. It is safe to use such reference because SObjectizer guarantees that children cooperations will be destroyed before its parent cooperation. So it is necessary to manage resource control only in the parent cooperation.

To specify parent cooperation new a method so_5::rt::agent_coop_t::set_parent_coop_name() was introduced. It must be applied with the name of already registered cooperation in order to set parent-child relationship. The usage of that method looks like:

so_5::rt::so_environment_t & env = ...;

auto coop = env.create_coop( "child_coop" );
coop->set_parent_coop_name( "parent_coop" );
... // Add agents to cooperation.
env.register_coop( std::move(coop) );

Some technical details

The parent cooperation name is checked inside the so_5::rt::so_environment_t::register_coop() method. The cooperation with specified name must be registered at that moment and must not be under some deregistration
process. If cooperation name is unknown or parent cooperation is being deregistered then an error is raised.

If a parent cooperation name is passed to so_5::rt::so_environment_t::deregister_coop() then SObjectizer makes a full list of all of children cooperations (e.g. direct children cooperations, children of children and so on). And then initiates deregistration for all of them at once. It means that all of cooperations will receive deregistration signal at the same time. But because cooperation deregistration could take some time some of cooperations can finish their deregistration process earlier and some later. Because of that agents of the parent cooperation could finish their work before agents from children cooperations.

Note, that the destruction of cooperation will be done in particular order. Cooperations without any children will be deregistered at first turn. Then the parents of already deregistered cooperations will be deregistered. Next, parents of those parents and so on. The root cooperation which name was specified in so_5::rt::so_environment_t::deregister_coop() will be destroyed the last.