so5extra 1.4 Asio Not Thread Safe Infrastructure

Purpose

The main purpose of non-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. It seems to be useful in the following scenarios:

• small and lightweight applications which must do all its work on a single thread but require both Asio- and SObjectizer-functionality. For example, it can be networking utilities like custom implementations of traceroute or DNS lookup utilities. Such utilities do not require to use several working threads because all the work can be done on the main thread. However the application logic can be rather complex and usage of SObjectizer's agents and message-passing between them can simplify application development;
• libraries which require both Asio- and SObjectizer-functionality but must be as lightweight as possible to be embedded into an application with minimal overhead. For example, it can be a library with the implementation of HTTP-entry into an application, for a client library with the implementation of AMQP protocol and so on. Some complex applications may be very CPU and/or RAM-intensive. It is not appropriate to add a heavy library which creates a dozen its own threads into such applications. An implementation of complex communication protocol like AMQP which uses just one thread is more likely to be used in such cases.

How to Use

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

1. Include a header file so_5_extra/env_infrastructures/asio/simple_not_mtsafe.hpp. Note: main SObjectizer's header file so_5/all.hpp may also to 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_not_mtsafe namespace in SObjectizer Environment's params.

It can looks like:

#include <so_5_extra/env_infrastructures/asio/simple_not_mtsafe.hpp>
 
#include <so_5/all.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_not_mtsafe;
         params.infrastructure_factory( factory(io_svc) );
      } );
}

Some Technical Details

Automatic Shutdown When There Is No Any Work

This infrastructure detects the absence of any type of work (either IO-activities related to Asio or message-processing activities related to SObjectizer). If there is no work to do (no IO-events, no timers, no messages to be processed) then SObjectizer's Environment will be shut down automatically.

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.

autoshutdown_disabled Can't Be Used

If autoshutdown_disabled flag is set in so_5::environment_params_t then an attempt to use so_5::extra::env_infrastructure::asio::simple_not_mtsafe infrastructure will lead to an exception at the SObjectizer's start. It is because the automatic shutdown of this infrastructure is one of the main features. This feature can't be disabled.

This Is NOT Thread Safe Environment

If this environment is used inside a multithreaded application then it must be used with big care: there is no protection from access to SObjectizer Environment from other threads. For example, an attempt to send a message from an outside thread can lead to data races and data corruption.