all.cpp

Go to the documentation of this file.

/*
 * SObjectizer-5
 */
 
/*!
 * \file
 * \brief Testing related stuff.
 *
 * \since v.5.5.24
 */
 
#include <so_5/experimental/testing/v1/all.hpp>
 
#include <so_5/details/safe_cv_wait_for.hpp>
 
#include <so_5/impl/enveloped_msg_details.hpp>
 
namespace so_5 {
 
namespace experimental {
 
namespace testing {
 
inline namespace v1 {
 
namespace details {
 
trigger_t::trigger_t(
  incident_status_t incident_status,
  const agent_t & target,
  std::type_index msg_type,
  mbox_id_t src_mbox_id )
  : m_incident_status( incident_status )
  , m_target_agent( target )
  , m_target_id( target.so_direct_mbox()->id() )
  , m_msg_type( std::move(msg_type) )
  , m_src_mbox_id( src_mbox_id )
  {}
 
trigger_t::~trigger_t()
  {}
 
[[nodiscard]]
const agent_t &
trigger_t::target_agent() const noexcept
  {
    return m_target_agent;
  }
 
void
trigger_t::set_completion( completion_function_t fn )
  {
    if( !m_completion )
      // Simple store the new function.
      m_completion = std::move(fn);
    else
      {
        // We have to join the old and the new ones.
        completion_function_t joined_version =
          [old_fn = m_completion, new_fn = std::move(fn)]
          ( const trigger_completion_context_t & ctx ) {
            // NOTE: don't care about exception because completion
            // functions have to be noexcept.
            old_fn( ctx );
            new_fn( ctx );
          };
 
        m_completion = std::move(joined_version);
      }
  }
 
void
trigger_t::set_activation( activation_function_t fn )
  {
    if( !m_activation )
      // Simple store the new function.
      m_activation = std::move(fn);
    else
      {
        // We have to join the old and the new ones.
        activation_function_t joined_version =
          [old_fn = m_activation, new_fn = std::move(fn)]
          ( const trigger_activation_context_t & ctx ) {
            // NOTE: don't care about exception because completion
            // functions have to be noexcept.
            old_fn( ctx );
            new_fn( ctx );
          };
 
        m_activation = std::move(joined_version);
      }
  }
 
[[nodiscard]]
bool
trigger_t::check(
  const incident_status_t incident_status,
  const incident_info_t & info ) const noexcept
  {
    return incident_status == m_incident_status
        && info.m_agent->so_direct_mbox()->id() == m_target_id
        && info.m_msg_type == m_msg_type
        && info.m_src_mbox_id == m_src_mbox_id;
  }
 
[[nodiscard]]
bool
trigger_t::requires_completion() const noexcept
  {
    return static_cast<bool>(m_completion);
  }
 
void
trigger_t::activate(
  const trigger_activation_context_t & context ) noexcept
  {
    if( m_activation )
      m_activation( context );
  }
 
void
trigger_t::complete(
  const trigger_completion_context_t & context ) noexcept
  {
    m_completion( context );
  }
 
/*!
 * \brief An actual implementation of step of testing scenario.
 *
 * \since v.5.5.24
 */
class real_scenario_step_t final : public abstract_scenario_step_t
  {
    //! Type of container for preactivation actions.
    using preactivate_actions_container_t =
        std::vector< preactivate_action_t >;
 
    //! Name of a step.
    const std::string m_name;
 
    //! All preactivation actions.
    preactivate_actions_container_t m_preactivate_actions;
 
    //! All constraints.
    constraint_container_t m_constraints;
 
    //! All triggers.
    /*!
     * This containers holds all triggers as for when_all, as
     * for when_any case.
     *
     * There is an important trick: activated triggers moved to
     * the end of that container. It means that first N triggers
     * in that containers wait for activation. The value of N
     * is defined by m_last_non_activated_trigger attribute.
     */
    trigger_container_t m_triggers;
    //! Index of last trigger in the first part of trigger's container.
    /*!
     * Receives actual value in setup_triggers() method.
     * At the begining, if m_triggers.size() is not 0, it holds
     * (m_triggers.size()-1). Then it is decremented after activation
     * of yet another trigger.
     */
    std::size_t m_last_non_activated_trigger = 0u;
 
    //! Count of triggers those should be activated for activation
    //! of the step.
    /*!
     * Receives actual value in setup_triggers() method.
     */
    std::size_t m_triggers_to_activate;
    //! Count of triggers those are activated.
    std::size_t m_triggers_activated = 0u;
 
    //! Count of activated triggers those are not completed yet.
    /*!
     * Condition for completion of the step looks like:
     * \code
     * (m_triggers_to_activate == m_triggers_activated) && (0u == m_triggers_to_completion)
     * \endcode
     */
    std::size_t m_triggers_to_completion = 0u;
 
    //! The current state of the step.
    status_t m_status = status_t::passive;
 
  public :
    real_scenario_step_t(
      std::string name )
      : m_name( std::move(name) )
      {}
 
    [[nodiscard]]
    const std::string &
    name() const noexcept override
      {
        return m_name;
      }
 
    void
    preactivate() noexcept override
      {
        change_status( status_t::preactivated );
      }
 
    [[nodiscard]]
    token_t
    pre_handler_hook(
      const scenario_in_progress_accessor_t & scenario_accessor,
      const incident_info_t & info,
      const message_ref_t & incoming_msg ) noexcept override
      {
        token_t result;
 
        if( status_t::preactivated == m_status )
          result = try_activate(
              trigger_activation_context_t{
                  scenario_accessor,
                  *this,
                  incoming_msg
              },
              incident_status_t::handled, info );
 
        return result;
      }
 
    void
    post_handler_hook(
      const scenario_in_progress_accessor_t & scenario_accessor,
      token_t token ) noexcept override
      {
        if( token.valid() )
          {
            token.trigger().complete(
                trigger_completion_context_t{
                    scenario_accessor,
                    *this
                } );
 
            --m_triggers_to_completion;
 
            // If step activated and there is no triggers to
            // be completed then the step can be completed.
            // But there can be cases when m_triggers_to_completion
            // is zero, but the step is not activated yet
            // (for example when `when_all` is used).
            if( !m_triggers_to_completion &&
                status_t::active == m_status )
              change_status( status_t::completed );
          }
      }
 
    void
    no_handler_hook(
      const scenario_in_progress_accessor_t & scenario_accessor,
      const incident_info_t & info,
      const message_ref_t & incoming_msg ) noexcept override
      {
        if( status_t::preactivated == m_status )
          (void)try_activate(
              trigger_activation_context_t{
                  scenario_accessor,
                  *this,
                  incoming_msg,
              },
              incident_status_t::ignored, info );
      }
 
    [[nodiscard]]
    status_t
    status() const noexcept override
      {
        return m_status;
      }
 
    void
    add_preactivate_action(
      preactivate_action_t action ) override
      {
        m_preactivate_actions.emplace_back( std::move(action) );
      }
 
    void
    setup_triggers(
      trigger_container_t triggers,
      std::size_t triggers_to_activate ) noexcept override
      {
        using std::swap;
 
        swap( m_triggers, triggers );
        m_triggers_to_activate = triggers_to_activate;
 
        m_last_non_activated_trigger = m_triggers.size();
        if( m_last_non_activated_trigger )
          --m_last_non_activated_trigger;
      }
 
    void
    setup_constraints(
      constraint_container_t constraints ) noexcept override
      {
        using std::swap;
 
        swap( m_constraints, constraints );
      }
 
  private :
    //! Change the state of the step and perform all necessary
    //! transitional actions.
    /*!
     * If a new state is status_t::preactivated then preactivation
     * actions will be called and constraint_t::start() will be called
     * for all constraints.
     *
     * If a new state is status_t::completed then constraint_t::finish()
     * will be called for all constraints.
     */
    void
    change_status( status_t status ) noexcept
      {
        m_status = status;
        switch( status )
          {
          case status_t::preactivated:
            {
              for( auto & act : m_preactivate_actions )
                act();
 
              for( auto & c : m_constraints )
                c->start();
            }
          break;
          case status_t::completed:
            {
              for( auto & c : m_constraints )
                c->finish();
            }
          break;
 
          case status_t::passive: break;
          case status_t::active: break;
          }
      }
 
    //! An attempt to check constraints for a new incident.
    /*!
     * \retval true if all constraints fullfilled.
     */
    [[nodiscard]]
    bool
    try_pass_constraints(
      const incident_status_t incident_status,
      const incident_info_t & info ) const noexcept
      {
        for( auto & c : m_constraints )
          if( !c->check( incident_status, info ) )
            return false;
 
        return true;
      }
 
    //! An attempt to activate the step when a new incident arrives.
    [[nodiscard]]
    token_t
    try_activate(
      const trigger_activation_context_t & context,
      const incident_status_t incident_status,
      const incident_info_t & info ) noexcept
      {
        token_t result;
 
        // All constraints must be fullfilled.
        if( !try_pass_constraints( incident_status, info ) )
          return result;
 
        // Check triggers those are not activated yet.
        // Those triggers are in the first part of m_triggers.
        // It is safe to add 1 to m_last_non_activated_trigger, because
        // this method is called only if there is at least one
        // non-activated trigger in the triggers container.
        auto end = std::begin(m_triggers) +
            static_cast<trigger_container_t::iterator::difference_type>(
                m_last_non_activated_trigger + 1u);
 
        auto it = std::find_if(
            std::begin(m_triggers), end,
            [incident_status, &info]
            ( trigger_unique_ptr_t & trigger ) {
              return trigger->check( incident_status, info );
            } );
 
        if( it == end )
          return result;
 
        trigger_t * active_trigger = it->get();
        // Trigger has to be activated.
        active_trigger->activate( context );
 
        // Actual trigger should be stored separatelly.
        if( m_last_non_activated_trigger )
          {
            // Actual trigger should be moved to the end of triggers list.
            std::swap( *it, m_triggers[ m_last_non_activated_trigger ] );
            --m_last_non_activated_trigger;
          }
 
        ++m_triggers_activated;
        if( active_trigger->requires_completion() )
          {
            ++m_triggers_to_completion;
            // Actual trigger should be returned in result token.
            result = token_t{ active_trigger };
          }
 
        // Now the new state of the step can be calculated.
        if( m_triggers_activated == m_triggers_to_activate )
          {
            // All expected triggers are activated.
            // New state should be `active` or `completed`.
            change_status( (0u != m_triggers_to_completion) ?
                status_t::active : status_t::completed );
          }
 
        return result;
      }
  };
 
/*!
 * \brief An interface for object that will unfreeze all registered
 * agents when testing scenario starts.
 *
 * It is necessary for testing scenarios to keep all registered agents in
 * frozen state. Those agents should be present in the Environment but should
 * not receive nor handle messages. It is done by a special implementation of
 * event queues and event_queue_hook.
 *
 * But at some moment all frozen agents should become unfrozen. This moment is
 * known only for testing scenario. It means that testing scenario should
 * issue a command to unfreeze all frozen agents.
 *
 * This interface allows testing scenario to unfreeze agents but hides the
 * details of this procedure.
 *
 * \since v.5.5.24
 */
class agent_unfreezer_t
  {
    agent_unfreezer_t( const agent_unfreezer_t & ) = delete;
    agent_unfreezer_t & operator=( const agent_unfreezer_t & ) = delete;
 
    agent_unfreezer_t( agent_unfreezer_t && ) = delete;
    agent_unfreezer_t & operator=( agent_unfreezer_t && ) = delete;
 
  public :
    agent_unfreezer_t() = default;
    virtual ~agent_unfreezer_t() = default;
 
    //! Issue a command to unfreeze all frozen agents.
    virtual void
    unfreeze() noexcept = 0;
  };
 
/*!
 * \brief The actual implementation of testing scenario.
 *
 * \since v.5.5.24
 */
class real_scenario_t final : public abstract_scenario_t
  {
  private :
    //! Object lock.
    /*!
     * \note
     * It is mutable because it has to be used in a const method.
     */
    mutable std::mutex m_lock;
    //! Condition variable for waiting completion of the scenario.
    std::condition_variable m_completion_cv;
 
    //! The current state of the scenario.
    scenario_status_t m_status = scenario_status_t::not_started;
 
    //! Scenario's steps.
    /*!
     * Can be empty.
     */
    std::vector< step_unique_ptr_t > m_steps;
    //! Set of active step those are not completed yet.
    /*!
     * If a step switches from preactivated state to the completed
     * without staying in active state then this step won't go
     * to this set.
     */
    std::set< abstract_scenario_step_t * > m_active_steps;
 
    //! Index of the current preactivated step.
    std::size_t m_waiting_step_index = 0u;
 
    //! Type of container for holding stored state names.
    /*!
     * The key consists of step_name and tag_name.
     */
    using state_name_map_t = std::map<
        std::pair< std::string, std::string >,
        std::string >;
 
    //! Type of container for holding stored inspection results for messages.
    /*!
     * The key consists of step_name and tag_name.
     */
    using inspection_result_map_t = std::map<
        std::pair< std::string, std::string >,
        std::string >;
 
    //! Container for holding stored state names.
    state_name_map_t m_stored_states;
 
    //! Container for holding stored inspection results for messages.
    /*!
     * \since v.5.8.3
     */
    inspection_result_map_t m_stored_inspection_results;
 
    //! Unfreezer for registered agents.
    /*!
     * \note Will receive an actual value later.
     */
    agent_unfreezer_t * m_unfreezer{};
 
  public :
    real_scenario_t() = default;
 
    //! Set the unfreezer for registered agents.
    /*!
     * \attention
     * This method must be called before start of the scenario.
     */
    void
    setup_unfreezer( agent_unfreezer_t & unfreezer ) noexcept
      {
        m_unfreezer = &unfreezer;
      }
 
    [[nodiscard]]
    step_definition_proxy_t
    define_step( nonempty_name_t step_name ) override
      {
        std::lock_guard< std::mutex > lock{ m_lock };
        if( scenario_status_t::not_started != m_status )
          SO_5_THROW_EXCEPTION(
              rc_unable_to_define_new_step,
              "new testing scenario step can be defined only when "
              "scenario is not started yet" );
 
        m_steps.emplace_back(
            std::make_unique< real_scenario_step_t >(
                step_name.giveout_value() ) );
 
        return { m_steps.back().get() };
      }
 
    [[nodiscard]]
    scenario_result_t
    result() const noexcept override
      {
        std::lock_guard< std::mutex > lock{ m_lock };
 
        if( scenario_status_t::completed == m_status )
          return { scenario_status_t::completed };
        else
          return { m_status, describe_current_state() };
      }
 
    void
    run_for( std::chrono::steady_clock::duration run_time ) override
      {
        std::unique_lock< std::mutex > lock{ m_lock };
        if( scenario_status_t::not_started == m_status )
          {
            // Note. There is a trick: unfreezing of agents is performed
            // when scenario is locked. It means that event handlers of
            // dispatched messages will wait while that method completes.
            m_unfreezer->unfreeze();
 
            if( m_steps.empty() )
              m_status = scenario_status_t::completed;
            else
              {
                m_status = scenario_status_t::in_progress;
                preactivate_current_step();
 
                ::so_5::details::wait_for_big_interval(
                    lock,
                    m_completion_cv,
                    run_time,
                    [this]{ return scenario_status_t::completed == m_status; });
                if( scenario_status_t::completed != m_status )
                  m_status = scenario_status_t::timed_out;
              }
          }
      }
 
    [[nodiscard]]
    token_t
    pre_handler_hook(
      const incident_info_t & info,
      const message_ref_t & incoming_msg ) noexcept override
      {
        token_t result;
 
        std::lock_guard< std::mutex > lock{ m_lock };
 
        // There can be cases when pre_handler_hook is called
        // when testing scenario is already finished.
        if( scenario_status_t::in_progress == m_status &&
            m_waiting_step_index < m_steps.size() )
          {
            result = react_on_pre_handler_hook( info, incoming_msg );
          }
 
        return result;
      }
 
    void
    post_handler_hook(
      token_t token ) noexcept override
      {
        std::lock_guard< std::mutex > lock{ m_lock };
 
        // There can be cases when post_handler_hook is called
        // when testing scenario is already finished.
        // Also we can ignore that event if token has no valid info inside.
        if( scenario_status_t::in_progress == m_status && token.valid() )
          {
            // There is a waiting step for that post_handler_hook
            // should be called.
            auto & step_to_check = token.activated_step();
 
            step_to_check.post_handler_hook(
                make_accessor(),
                token.step_token() );
 
            if( abstract_scenario_step_t::status_t::completed
                == step_to_check.status() )
              {
                m_active_steps.erase( &step_to_check );
 
                check_scenario_completion();
              }
          }
      }
 
    void
    no_handler_hook(
      const incident_info_t & info,
      const message_ref_t & incoming_msg ) noexcept override
      {
        std::lock_guard< std::mutex > lock{ m_lock };
 
        // There can be cases when no_handler_hook is called
        // when testing scenario is already finished.
        if( scenario_status_t::in_progress == m_status &&
            m_waiting_step_index < m_steps.size() )
          {
            react_on_no_handler_hook( info, incoming_msg );
          }
      }
 
    void
    store_state_name(
      const scenario_in_progress_accessor_t & /*accessor*/,
      const abstract_scenario_step_t & step,
      const std::string & tag,
      const std::string & state_name ) override
      {
        m_stored_states[ std::make_pair(step.name(), tag) ] = state_name;
      }
 
    void
    store_msg_inspection_result(
      const scenario_in_progress_accessor_t & /*accessor*/,
      const abstract_scenario_step_t & step,
      const std::string & tag,
      const std::string & inspection_result ) override
      {
        m_stored_inspection_results[ std::make_pair(step.name(), tag) ]
            = inspection_result;
      }
 
    [[nodiscard]]
    std::string
    stored_state_name(
      const std::string & step_name,
      const std::string & tag ) const override
      {
        std::lock_guard< std::mutex > lock{ m_lock };
 
        if( scenario_status_t::completed != m_status )
          SO_5_THROW_EXCEPTION(
              rc_scenario_must_be_completed,
              "scenario must be completed before call to "
              "stored_state_name()" );
 
        const auto it = m_stored_states.find(
            std::make_pair(step_name, tag) );
        if( it == m_stored_states.end() )
          SO_5_THROW_EXCEPTION(
              rc_stored_state_name_not_found,
              "unable to find stored state name for <" +
              step_name + "," + tag + ">" );
 
        return it->second;
      }
 
    [[nodiscard]]
    bool
    has_stored_state_name(
      const std::string & step_name,
      const std::string & tag ) const override
      {
        std::lock_guard< std::mutex > lock{ m_lock };
 
        if( scenario_status_t::completed != m_status )
          SO_5_THROW_EXCEPTION(
              rc_scenario_must_be_completed,
              "scenario must be completed before call to "
              "stored_state_name()" );
 
        return m_stored_states.end() != m_stored_states.find(
            std::make_pair(step_name, tag) );
      }
 
    [[nodiscard]]
    std::string
    stored_msg_inspection_result(
      const std::string & step_name,
      const std::string & tag ) const override
      {
        std::lock_guard< std::mutex > lock{ m_lock };
 
        if( scenario_status_t::completed != m_status )
          SO_5_THROW_EXCEPTION(
              rc_scenario_must_be_completed,
              "scenario must be completed before call to "
              "stored_msg_inspection_result()" );
 
        const auto it = m_stored_inspection_results.find(
            std::make_pair(step_name, tag) );
        if( it == m_stored_inspection_results.end() )
          SO_5_THROW_EXCEPTION(
              rc_stored_msg_inspection_result_not_found,
              "unable to find stored msg inspection result for <" +
              step_name + "," + tag + ">" );
 
        return it->second;
      }
 
    [[nodiscard]]
    bool
    has_stored_msg_inspection_result(
      const std::string & step_name,
      const std::string & tag ) const override
      {
        std::lock_guard< std::mutex > lock{ m_lock };
 
        if( scenario_status_t::completed != m_status )
          SO_5_THROW_EXCEPTION(
              rc_scenario_must_be_completed,
              "scenario must be completed before call to "
              "has_stored_msg_inspection_result()" );
 
        return m_stored_inspection_results.end() !=
            m_stored_inspection_results.find(
                std::make_pair(step_name, tag) );
      }
 
 
  private :
    void
    preactivate_current_step()
      {
        m_steps[ m_waiting_step_index ]->preactivate();
      }
 
    [[nodiscard]]
    token_t
    react_on_pre_handler_hook(
      const incident_info_t & info,
      const message_ref_t & incoming_msg ) noexcept
      {
        token_t result;
 
        // pre_handler_hook on the current waiting step must be called.
        auto & step_to_check = *(m_steps[ m_waiting_step_index ]);
        auto step_token = step_to_check.pre_handler_hook(
            make_accessor(),
            info,
            incoming_msg );
 
        if( step_token.valid() )
          // Because step's token is not NULL, we should return
          // our valid token.
          // This is the case when token is necessary for the
          // subsequent post_handler_hook() call.
          result = token_t{ &step_to_check, std::move(step_token) };
 
        // The step can change its status...
        switch( step_to_check.status() )
          {
          case abstract_scenario_step_t::status_t::active :
            // The step is activated and we need to wait its completion.
            m_active_steps.insert( &step_to_check );
            switch_to_next_step_if_possible();
          break;
 
          case abstract_scenario_step_t::status_t::completed :
            // There is no need to wait the completion of the step.
            switch_to_next_step_if_possible();
 
            check_scenario_completion();
          break;
 
          case abstract_scenario_step_t::status_t::passive: break;
          case abstract_scenario_step_t::status_t::preactivated: break;
          }
 
        return result;
      }
 
    void
    react_on_no_handler_hook(
      const incident_info_t & info,
      const message_ref_t & incoming_msg ) noexcept
      {
        // no_handler_hook on the current waiting step must be called.
        auto & step_to_check = *(m_steps[ m_waiting_step_index ]);
        step_to_check.no_handler_hook(
            make_accessor(),
            info,
            incoming_msg );
 
        // The step can change its status...
        switch( step_to_check.status() )
          {
          case abstract_scenario_step_t::status_t::active :
            // The step is activated and we need to wait its completion.
            m_active_steps.insert( &step_to_check );
            switch_to_next_step_if_possible();
          break;
 
          case abstract_scenario_step_t::status_t::completed :
            // There is no need to wait the completion of the step.
            switch_to_next_step_if_possible();
 
            check_scenario_completion();
          break;
 
          case abstract_scenario_step_t::status_t::passive: break;
          case abstract_scenario_step_t::status_t::preactivated: break;
          }
      }
 
    void
    switch_to_next_step_if_possible()
      {
        ++m_waiting_step_index;
        if( m_waiting_step_index < m_steps.size() )
          {
            preactivate_current_step();
          }
      }
 
    //! Checks the possibility of completion of the scenario and
    //! completes scenario if it is possible.
    void
    check_scenario_completion() noexcept
      {
        if( m_active_steps.empty() &&
            m_waiting_step_index >= m_steps.size() )
          {
            m_status = scenario_status_t::completed;
            m_completion_cv.notify_all();
          }
      }
 
    [[nodiscard]]
    std::string
    describe_current_state() const
      {
        std::ostringstream ss;
 
        if( m_waiting_step_index < m_steps.size() )
          ss << "preactivated step:"
            << m_steps[ m_waiting_step_index ]->name();
        else
          ss << "all steps handled";
 
        ss << ";";
 
        if( !m_active_steps.empty() )
          {
            ss << " active steps:{";
            bool need_comma = false;
            for( auto * s : m_active_steps )
              {
                if( need_comma )
                  ss << ", ";
                else
                  need_comma = true;
 
                ss << s->name();
              }
            ss << "};";
          }
 
        if( !m_stored_states.empty() )
          {
            ss << " stored states:{";
            bool need_comma = false;
            for( auto & p : m_stored_states )
              {
                if( need_comma )
                  ss << ", ";
                else
                  need_comma = true;
 
                ss << "[" << p.first.first << ", "
                  << p.first.second << "]="
                  << p.second;
              }
            ss << "};";
          }
 
        return ss.str();
      }
  };
 
//
// msg_catcher_map_layer_t
//
 
namespace mbox_receives_msg_impl
{
 
msg_catcher_map_layer_t::msg_catcher_map_layer_t() = default;
msg_catcher_map_layer_t::~msg_catcher_map_layer_t() noexcept = default;
 
} /* namespace mbox_receives_msg_impl */
 
} /* namespace details */
 
namespace impl {
 
namespace details = so_5::experimental::testing::v1::details;
 
 
/*!
 * \brief A special envelope that is necessary for testing scenarios.
 *
 * Testing scenario should know about every handled or rejected message
 * delivered to agents. To make this possible a trick with enveloped
 * messages is used: every message is enveloped into a special envelope.
 * This envelope has a reference to testing scenario and informs this
 * scenario when message is handled by a receiver.
 *
 * But the situation with rejected messages is not that simple.
 * We assume that if access_hook() wasn't called then message was rejected.
 * Because of that envelope has a boolean flag m_handled that is set
 * in access_hook(). This flag is analyzed in the destructor and, if it
 * is not set, we assume that message was rejected.
 *
 * In theory there can be cases when envelope is destroyed without delivery
 * to an agent. But for testing scenarios we just ignore those case.
 *
 * \since v.5.5.24
 */
class special_envelope_t final : public so_5::enveloped_msg::envelope_t
  {
    //! Delivery result for a message inside the envelope.
    //!
    //! If the message is another envelope then there could be
    //! case when the actual message will be suppressed by a nested envelope.
    //! This case has to be handled separatelly: in that case message
    //! isn't handled nor delivered.
    //!
    //! \since v.5.8.3
    enum class delivery_result_t
      {
        //! Message ignored by the destination agent.
        ignored,
        //! Message delivered to the destination agent.
        delivered,
        //! Message suppressed by a nested envelope.
        suppressed_by_envelope
      };
 
    //! A testing scenario for that envelope.
    outliving_reference_t< details::abstract_scenario_t > m_scenario;
    //! Information about enveloped message.
    details::incident_info_t m_demand_info;
    //! Enveloped message.
    message_ref_t m_message;
 
    //! Was this message handled by a receiver?
    delivery_result_t m_delivery_result{ delivery_result_t::ignored };
 
    //! A special invoker to be used to call pre_handler_hook.
    class pre_handler_hook_invoker_t final : public handler_invoker_t
      {
        //! Owner of this invoker.
        outliving_reference_t< special_envelope_t > m_owner;
 
        //! Invoker to be used to call the actual event handler.
        outliving_reference_t< handler_invoker_t > m_actual_invoker;
 
      public:
        //! Intializing constructor.
        pre_handler_hook_invoker_t(
          //! Owner of this invoker.
          outliving_reference_t< special_envelope_t > owner,
          //! Invoker to be used to call the actual event handler.
          outliving_reference_t< handler_invoker_t > actual_invoker )
          : m_owner{ owner }
          , m_actual_invoker{ actual_invoker }
          {}
 
        void
        invoke( const payload_info_t & payload ) noexcept override
          {
            // We must get token...
            auto token = m_owner.get()
                .m_scenario.get()
                    .pre_handler_hook(
                        m_owner.get().m_demand_info,
                        payload.message() );
 
            // Actual event handler has to be called.
            m_actual_invoker.get().invoke( payload );
 
            // And now the token must be passed back.
            m_owner.get().m_scenario.get().post_handler_hook( token );
          }
      };
 
    //! A special invoker to be used to call no_handler_hook.
    class no_handler_invoker_t final : public handler_invoker_t
      {
        //! Owner of this invoker.
        outliving_reference_t< special_envelope_t > m_owner;
 
      public:
        //! Initializing constructor.
        explicit no_handler_invoker_t(
          outliving_reference_t< special_envelope_t > owner )
          : m_owner{ owner }
          {}
 
        void
        invoke( const payload_info_t & payload ) noexcept override
          {
            m_owner.get().m_scenario.get().no_handler_hook(
                m_owner.get().m_demand_info,
                payload.message() );
          }
      };
 
    //! Special handler invoker that tries to extract the actual message.
    //!
    //! This invoker is necessary because the message may be enveloped
    //! more than once and one of the nested envelopes may suppress it.
    //!
    //! \since v.5.8.3
    class invoker_for_message_extraction_t final
      : public so_5::enveloped_msg::handler_invoker_t
      {
        //! Handler invoker that has to be used for extracted message.
        outliving_reference_t< so_5::enveloped_msg::handler_invoker_t > m_invoker;
 
        //! Context for accessing enveloped message.
        const so_5::enveloped_msg::access_context_t m_access_context;
 
        //! Has the message actually been handled?
        bool m_handled{ false };
 
      public:
        //! Initializing constructor.
        invoker_for_message_extraction_t(
          //! Handler invoker that has to be used if message is extracted.
          outliving_reference_t< so_5::enveloped_msg::handler_invoker_t > invoker,
          //! Context for accessing enveloped message.
          so_5::enveloped_msg::access_context_t access_context )
          : m_invoker{ invoker }
          , m_access_context{ access_context }
          {}
 
        void
        invoke( const so_5::enveloped_msg::payload_info_t & payload ) noexcept override
          {
            const auto msg_kind = message_kind( payload.message() );
 
            switch( msg_kind )
              {
              case message_t::kind_t::signal : [[fallthrough]];
              case message_t::kind_t::classical_message : [[fallthrough]];
              case message_t::kind_t::user_type_message :
                m_handled = true;
                m_invoker.get().invoke( payload );
              break;
 
              case message_t::kind_t::enveloped_msg :
                {
                  // Do recurvise call.
                  // Value for was_handled will be detected in the
                  // nested call.
                  auto & nested_envelope =
                      so_5::enveloped_msg::impl::message_to_envelope(
                          payload.message() );
                  nested_envelope.access_hook( m_access_context, *this );
                }
              break;
              }
          }
 
        //! Has the message actually been handled?
        [[nodiscard]] bool
        handled() const noexcept
          {
            return m_handled;
          }
      };
 
  public :
    //! Initializing constructor.
    special_envelope_t(
      outliving_reference_t< details::abstract_scenario_t > scenario,
      const execution_demand_t & demand )
      : m_scenario( scenario )
      , m_demand_info( demand.m_receiver, demand.m_msg_type, demand.m_mbox_id )
      , m_message( demand.m_message_ref )
      {}
    ~special_envelope_t() noexcept override
      {
        // If message wasn't handled we assume that agent rejected
        // this message.
        if( delivery_result_t::ignored == m_delivery_result )
        {
          // But we have to check that message isn't suppressed by
          // a nested envelope.
          no_handler_invoker_t invoker_no_handler_hook{
              outliving_mutable( *this )
            };
          invoker_for_message_extraction_t special_invoker{
              outliving_mutable( invoker_no_handler_hook ),
              access_context_t::inspection
            };
          // If the message is not suppressed then no_handler_hook
          // will be called by invoker_no_handler_hook.
          special_invoker.invoke( payload_info_t{ m_message } );
        }
      }
 
    void
    access_hook(
      //! Why this hook is called.
      access_context_t context,
      //! Proxy object which can call an actual event handler.
      handler_invoker_t & invoker ) noexcept override
      {
        switch( context )
          {
          case access_context_t::handler_found :
            {
              // This invoker will call pre/post_handler_hooks and
              // the actual event-handler.
              pre_handler_hook_invoker_t pre_handler_hook_invoker{
                  outliving_mutable( *this ),
                  outliving_mutable( invoker )
                };
 
              // The message can be envelope itself.
              // And the envelope can hide the message and does not return it.
              // This case has to be handled.
              invoker_for_message_extraction_t special_invoker{
                  outliving_mutable( pre_handler_hook_invoker ),
                  context
                };
              // The special invoker will do the back call of
              // call_handler_invoker method.
              special_invoker.invoke( payload_info_t{ m_message } );
 
              // If we don't change m_handled flag there the
              // destructor will call no_handler_hook().
              m_delivery_result = special_invoker.handled()
                  ? delivery_result_t::delivered
                  : delivery_result_t::suppressed_by_envelope;
            }
          break;
 
          case access_context_t::transformation :
            invoker.invoke( payload_info_t{ m_message } );
          break;
 
          case access_context_t::inspection :
            invoker.invoke( payload_info_t{ m_message } );
          break;
          }
      }
  };
 
/*!
 * \brief A mode of work for special_event_queue.
 *
 * Special event queue can work in two modes:
 * - buffered, when all messages must be stored in a local queue;
 * - direct, when all messages go directly to the original queue.
 *
 * This enumeration describes mode of operation for special_event_queue_t.
 *
 * \since v.5.5.24
 */
enum class queue_mode_t
  {
    //! All messages must be stored locally.
    buffer,
    //! All messages should go to the original queue without buffering.
    direct
  };
 
/*!
 * \brief A special event_queue to be used for testing scenarios.
 *
 * \par Support for agents freeze
 *
 * If a testing scenario is not started yet all registered agents
 * should be in frozen state. It means that they are present in
 * the SObjectizer Environment, but do not receive nor handle any message
 * (even special message for invoking so_evt_start() method).
 *
 * To implement that special event_queue is created for every agent.
 * This event_queue works in two modes, described by
 * queue_mode_t enumeration.
 *
 * In queue_mode_t::buffer mode all messages are stored in local queue
 * and not passed to the actual event_queue created for agent by a dispatcher.
 * This way we prevent delivery of messages to agents.
 *
 * In queue_mode_t::direct mode all message are passed to the actual
 * event_queue directly, without storing them locally. In that mode
 * special event_queue works just as a proxy.
 *
 * Transfer of locally stored events is performed when mode is
 * switched from queue_mode_t::buffer to queue_mode_t::direct.
 *
 * \par Creation of special envelopes
 *
 * There is yet another task for special event_queue: all ordinary
 * messages/signals, service requests and enveloped messages must be
 * wrapped into a special envelope. This is done in push() method.
 *
 * \since v.5.5.24
 */
class special_event_queue_t final : public event_queue_t
  {
    //! Object lock.
    /*!
     * All operations will be performed under that lock.
     */
    std::mutex m_lock;
 
    //! Testing scenario for that this queue was created.
    outliving_reference_t< details::abstract_scenario_t > m_scenario;
    //! Original event_queue.
    outliving_reference_t< event_queue_t > m_original_queue;
 
    //! The current mode of operation.
    queue_mode_t m_mode;
    //! Local storage for demands to be used in buffered mode.
    std::vector< execution_demand_t > m_buffer;
 
    static bool
    is_ordinary_demand( const execution_demand_t & demand ) noexcept
      {
        return agent_t::get_demand_handler_on_message_ptr() ==
                demand.m_demand_handler ||
            agent_t::get_demand_handler_on_enveloped_msg_ptr() ==
                demand.m_demand_handler;
      }
 
    void
    push_to_queue( execution_demand_t demand )
      {
        std::lock_guard< std::mutex > lock{ m_lock };
 
        if( queue_mode_t::buffer == m_mode )
          m_buffer.push_back( std::move(demand) );
        else
          m_original_queue.get().push( std::move(demand) );
      }
 
  public :
    special_event_queue_t(
      outliving_reference_t< details::abstract_scenario_t > scenario,
      outliving_reference_t< event_queue_t > original_queue,
      queue_mode_t queue_mode )
      : m_scenario{ scenario }
      , m_original_queue{ original_queue }
      , m_mode{ queue_mode }
      {}
 
    void
    push( execution_demand_t demand ) override
      {
        if( !is_ordinary_demand( demand ) )
          // Demand must go into the original queue without transformations.
          push_to_queue( std::move(demand) );
        else
          {
            // Original message must be wrapped into a special
            // envelope and original demand must be modified.
            message_ref_t new_env{
              std::make_unique< special_envelope_t >(
                  m_scenario,
                  std::cref(demand) )
            };
 
            demand.m_message_ref = std::move(new_env);
            demand.m_demand_handler =
                agent_t::get_demand_handler_on_enveloped_msg_ptr();
 
            push_to_queue( std::move(demand) );
          }
      }
 
    void
    push_evt_start( execution_demand_t demand ) override
      {
        // Demand must go into the original queue without transformations.
        push_to_queue( std::move(demand) );
      }
 
    void
    push_evt_finish( execution_demand_t demand ) noexcept override
      {
        // Demand must go into the original queue without transformations.
        push_to_queue( std::move(demand) );
      }
 
    void
    switch_to_direct_mode()
      {
        // Cleanup of buffer should be performed when
        // object is unlocked.
        decltype(m_buffer) tmp;
        {
          std::lock_guard< std::mutex > lock{ m_lock };
 
          m_mode = queue_mode_t::direct;
 
          for( auto & d : m_buffer )
            m_original_queue.get().push( std::move(d) );
 
          using std::swap;
          swap( tmp, m_buffer );
        }
      }
  };
 
/*!
 * \brief A special stop guard that unfreezes all agents if this
 * is not done yet.
 *
 * There can be cases when testing environment is started, some
 * agents are registered, but testing scenario is not started. For example
 * the work of test case is cancelled by an exception.
 *
 * In those cases testing environment should be correctly stopped.
 * All agents have to be deregistered. We can do that only if they
 * is not frozen. But they are frozen.
 *
 * This special stop_guard is intended to unfreeze all agents if
 * testing environment finishes its work without launching the
 * testing scenario.
 *
 * \since v.5.5.24
 */
class stop_guard_for_unfreezer_t final
  : public stop_guard_t
  , public std::enable_shared_from_this< stop_guard_for_unfreezer_t >
  {
    outliving_reference_t< details::agent_unfreezer_t > m_unfreezer;
    outliving_reference_t< environment_t > m_env;
 
  public :
    stop_guard_for_unfreezer_t(
      outliving_reference_t< details::agent_unfreezer_t > unfreezer,
      outliving_reference_t< environment_t > env )
      : m_unfreezer{ unfreezer }
      , m_env{ env }
      {}
 
    void
    stop() noexcept override
      {
        so_5::details::invoke_noexcept_code( [this] {
          // Agents should become unfrozen.
          m_unfreezer.get().unfreeze();
 
          // We should remove itself to allow the environment
          // to continue shutdown operation.
          m_env.get().remove_stop_guard( shared_from_this() );
        } );
      }
  };
 
/*!
 * \brief A special event_queue_hook that creates instances of
 * special event_queue for testing scenario.
 *
 * This type is also an implementation of agent_unfreezer_t interface.
 *
 * To implement unfreezing of agents object of this types stores pointers
 * to all created event_queue in internal container. In unfreeze()
 * method all those queues are switched from buffered to direct mode.
 *
 * \since v.5.5.24
 */
class special_event_queue_hook_t final
  : public event_queue_hook_t
  , public details::agent_unfreezer_t
  {
    //! Lock for this object.
    std::mutex m_lock;
 
    //! Mode of operation for new queues.
    queue_mode_t m_mode{ queue_mode_t::buffer };
 
    //! Testing scenario for that this object is created.
    outliving_reference_t< details::abstract_scenario_t > m_scenario;
 
    //! List of all queues created before unfreeze was called.
    /*!
     * If unfreeze() was called then pointers to new event queues
     * are not stored in that list.
     *
     * \note
     * Items from this containers are not removed in on_unbind method.
     * We assume that agents can't be deregistered when all agents
     * are frozen.
     */
    std::vector< special_event_queue_t * > m_created_queues;
 
  public :
    special_event_queue_hook_t(
      outliving_reference_t< details::abstract_scenario_t > scenario )
      : m_scenario{ scenario }
      {}
 
    [[nodiscard]]
    event_queue_t *
    on_bind(
      agent_t * /*agent*/,
      event_queue_t * original_queue ) noexcept override
      {
        std::lock_guard< std::mutex > lock{ m_lock };
 
        auto sq = std::make_unique< special_event_queue_t >(
            m_scenario,
            outliving_mutable( *original_queue ),
            m_mode );
 
        if( queue_mode_t::buffer == m_mode )
          m_created_queues.push_back( sq.get() );
 
        return sq.release();
      }
 
    void
    on_unbind(
      agent_t * /*agent*/,
      event_queue_t * queue ) noexcept override
      {
        // Assume that queue is an instance of special_event_queue_t
        // and simply delete it.
        delete queue;
      }
 
    void
    unfreeze() noexcept override
      {
        // Mode will be switched under locked mutex.
        // But actual switching of queue operation mode
        // for already created queue will be performed with
        // unlocked mutex.
        decltype(m_created_queues) tmp;
        {
          std::lock_guard< std::mutex > lock{ m_lock };
 
          m_mode = queue_mode_t::direct;
 
          using std::swap;
          swap( tmp, m_created_queues );
        }
 
        // Now we can switch mode for all queues those were created
        // in buffered mode.
        for( auto * sq : tmp )
          sq->switch_to_direct_mode();
      }
  };
 
/*!
 * \brief A helper object for synchronization between helper worker where
 * testing environment is launched and user thread.
 *
 * We must stop work of testing_env_t constructor until
 * testing_env_t::tune_environment_on_start() finishes its work.
 * To do that constructor will wait on a future object for that
 * promise, and tune_environment_on_start() will set this promise.
 *
 * \since v.5.5.24
 */
struct init_completed_data_t
  {
    std::promise<void> m_completed;
  };
 
} /* namespace impl */
 
/*!
 * \brief Internal data for testing environment.
 *
 * \attention
 * real_scenario object must be declared before special_hook object.
 */
struct testing_env_t::internals_t
  {
    details::real_scenario_t m_scenario;
    impl::special_event_queue_hook_t m_special_hook;
 
    impl::init_completed_data_t m_init_completed;
 
    internals_t()
      : m_special_hook{ outliving_mutable(m_scenario) }
      {
        m_scenario.setup_unfreezer( m_special_hook );
      }
 
    [[nodiscard]]
    static std::unique_ptr< internals_t >
    make() { return std::make_unique<internals_t>(); }
  };
 
namespace impl {
 
void
setup_special_queue_hook(
  outliving_reference_t< testing_env_t::internals_t > internals,
  environment_params_t & to )
  {
    to.event_queue_hook(
        event_queue_hook_unique_ptr_t{
            std::addressof( internals.get().m_special_hook ),
            event_queue_hook_t::noop_deleter
        } );
  }
 
[[nodiscard]]
environment_params_t
make_tuned_params(
  so_5::generic_simple_so_env_params_tuner_t env_params_tuner )
  {
    environment_params_t result;
    env_params_tuner( result );
 
    return result;
  }
 
[[nodiscard]]
environment_params_t
make_special_params(
  outliving_reference_t< testing_env_t::internals_t > internals,
  environment_params_t && params )
  {
    setup_special_queue_hook( internals, params );
 
    // Special layer has to be added to the environment.
    using so_5::experimental::testing::v1::details::mbox_receives_msg_impl
        ::msg_catcher_map_layer_t;
    params.add_layer(
        std::make_unique< msg_catcher_map_layer_t >() );
 
    return std::move(params);
  }
 
} /* namespace impl */
 
//
// scenario_proxy_t
//
scenario_proxy_t::scenario_proxy_t(
  outliving_reference_t< details::abstract_scenario_t > scenario )
  : m_scenario{ scenario }
  {}
 
step_definition_proxy_t
scenario_proxy_t::define_step(
  nonempty_name_t step_name )
  {
    return m_scenario.get().define_step( std::move(step_name) );
  }
 
scenario_result_t
scenario_proxy_t::result() const
  {
    return m_scenario.get().result();
  }
 
void
scenario_proxy_t::run_for(
  std::chrono::steady_clock::duration run_time )
  {
    return m_scenario.get().run_for( run_time );
  }
 
std::string
scenario_proxy_t::stored_state_name(
  const std::string & step_name,
  const std::string & tag ) const
  {
    return m_scenario.get().stored_state_name( step_name, tag );
  }
 
bool
scenario_proxy_t::has_stored_state_name(
  const std::string & step_name,
  const std::string & tag ) const
  {
    return m_scenario.get().has_stored_state_name( step_name, tag );
  }
 
std::string
scenario_proxy_t::stored_msg_inspection_result(
  const std::string & step_name,
  const std::string & tag ) const
  {
    return m_scenario.get().stored_msg_inspection_result( step_name, tag );
  }
 
bool
scenario_proxy_t::has_stored_msg_inspection_result(
  const std::string & step_name,
  const std::string & tag ) const
  {
    return m_scenario.get().has_stored_msg_inspection_result( step_name, tag );
  }
 
//
// testing_env_t
//
testing_env_t::testing_env_t()
  : testing_env_t{ environment_params_t{} }
  {}
 
testing_env_t::testing_env_t(
  so_5::generic_simple_so_env_params_tuner_t env_params_tuner )
  : testing_env_t{ impl::make_tuned_params( std::move(env_params_tuner) ) }
  {}
 
testing_env_t::testing_env_t(
  environment_params_t && env_params )
  : m_internals{ internals_t::make() }
  , m_sobjectizer{
      [this]( environment_t & env ) { tune_environment_on_start( env ); },
      impl::make_special_params(
          outliving_mutable( *m_internals ),
          std::forward<environment_params_t>(env_params) ) }
  {
    // We must wait completion of tune_environment_on_start().
    wait_init_completion();
  }
 
testing_env_t::~testing_env_t()
  {}
 
environment_t &
testing_env_t::environment() const
  {
    return m_sobjectizer.environment();
  }
 
void
testing_env_t::stop()
  {
    m_sobjectizer.stop();
  }
 
void
testing_env_t::join()
  {
    m_sobjectizer.join();
  }
 
void
testing_env_t::stop_then_join()
  {
    m_sobjectizer.stop_then_join();
  }
 
[[nodiscard]]
scenario_proxy_t
testing_env_t::scenario() noexcept
  {
    return { outliving_mutable(m_internals->m_scenario) };
  }
 
void
testing_env_t::tune_environment_on_start( environment_t & env )
  {
    // stop_guard for unfreezing agents must be installed before
    // an user will start work with the environment.
    env.setup_stop_guard(
        std::make_shared< impl::stop_guard_for_unfreezer_t >(
            outliving_mutable(m_internals->m_special_hook),
            outliving_mutable(env) ) );
 
    // This action was done on separate thread.
    // The constructor of testing_env_t waits completion of
    // this method on another thread.
    // Do allow the constructor to complete its work.
    m_internals->m_init_completed.m_completed.set_value();
  }
 
void
testing_env_t::wait_init_completion()
  {
    m_internals->m_init_completed.m_completed.get_future().wait();
  }
 
} /* namespace v1 */
 
} /* namespace testing */
 
} /* namespace experimental */
 
} /* namespace so_5 */