so5extra 1.4 Asio Thread Safe Infrastructure

The Purpose

The main purpose of thread-safe single-thread environment infrastructure on top of Asio is to provide an ability to use Asio and SObjectizer at the same time on the single working thread when there are some other threads in an application. For example, this environment infrastructure can be used in GUI application when interaction with a user is performed on the main application thread but I/O-related activity is performed on a separate worker thread.

How to Use

There are a few simple steps which are required to use Asio-based simple_mtsafe environment infrastructure:

1. Include a header file so_5_extra/env_infrastructures/asio/simple_mtsafe.hpp. Note: main SObjectizer's header file so_5/all.hpp may also be needed.
2. Create an instance of asio::io_context inside an application. Make sure that this instance will outlive the SObjectizer's Environment where this instance will be used.
3. Specify the infrastructure factory from so_5::extra::env_infrastructures::asio::simple_mtsafe namespace in SObjectizer Environment's params.

It can looks like:

#include <so_5_extra/env_infrastructures/asio/simple_mtsafe.hpp>
 
#include <so_5/app.hpp>
...
int main()
{
   asio::io_context io_svc;
   so_5::launch( [](so_5::environment_t & env) { ... },
      [&](so_5::environment_params_t & params) {
         using namespace so_5::extra::env_infrastructures::asio::simple_mtsafe;
         params.infrastructure_factory( factory(io_svc) );
      } );
}

Some Technical Details

This Infrastructure Doesn't Stop When There Is No Any Work

Unlike so_5::extra::env_infrastructure::asio::simple_not_mtsafe this infrastructure doesn't stop when there is no any type of work (either IO-activities related to Asio or message-processing activities related to SObjectizer). It is because simple_mtsafe environment infrastructure should be used in an application with several worker threads. Some of these threads can create new agents or send new messages to existing agents at any moment. So simple_mtsafe simply doesn't do anything if there are no events to process. An external work thread must call so_5::environment_t::stop() explicitly to shutdown SObjectizer.

This infrastructure supports autoshutdown flag: it means that infrastructure stops automatically if there are no live agents anymore (just like traditional mt_default environment infrastructure). The autoshutdown flag can be disabled in environment parameters. In that case, simple_mtsafe infrastructure will work even if there are no more agents in it. This makes sense in situations where external worker threads create new agents when it is necessary.

Asio Is Used For Timers And For Event Queues

With this environment infrastructure, the SObjectizer doesn't use its own timer mechanisms (like timer_threads or timer_managers). Asio timers are used for delayed and periodic messages.

SObjectizer also doesn't use any demand queues: Asio's io_context::post is used for event scheduling.

This Is Thread Safe Environment

This environment can be easily used inside multithreaded applications: it has thread-safety incorporated. It means that other threads inside an application can create new cooperations or destroy existing coops, or can send messages to existing agents, or can use mchains for communications.

Additional care must be taken to ensure that all worker threads have a valid reference to SObjectizer Environment.