From openSIPS

Documentation: Asynchronous Statements - 3.1

Documentation -> Manuals -> Manual 3.1 -> Asynchronous Statements

This page has been visited 841 times.


Pages for other versions: devel 3.1 3.0 2.4 Older versions: 2.3 2.2 2.1


Asynchronous Statements v3.1
PrevNext

Table of Content (hide)

  1. 1. Description
  2. 2. Serial asynchronous operations
    1. 2.1 Requirements
    2. 2.2 Script syntax and usage
  3. 3. Parallel asynchronous operations
    1. 3.1 Script syntax and usage
  4. 4. List of async functions
  5. 5. Limitations
    1. 5.1 Async Engine Compatibility
    2. 5.2 TCP Connect Issues
    3. 5.3 Allowed Routes

1.  Description

Asynchronous statements are one of the key features of OpenSIPS 2.X. One of the main reasons to use them is that they allow the performance of the OpenSIPS script to scale with a high number of requests per second even when doing blocking I/O operations such as MySQL queries, exec commands or HTTP requests.


Using the asynchronous, "suspend-resume" logic instead of forking a large number of processes in order to scale also has the advantage of optimizing system resource usage, increasing its maximal throughput. By requiring less processes to complete the same amount of work in the same amount of time, process context switching is minimized and overall CPU usage is improved. Less processes will also eat up less system memory.

2.  Serial asynchronous operations

The async() statement of the OpenSIPS script can be used in situations where the script writer both needs to perform blocking I/O and also depends on the result of this operation. Some example scenarios:

2.1  Requirements

The async() statement depends on the transaction module (tm) - it must be loaded. The SIP transaction will be automatically and transparently created when an async operation is started, if necessary. This transaction contains all the necessary information to suspend script execution (e.g. it stores the updated SIP message, along with all $avp variables).

2.2  Script syntax and usage

Usage is straightforward: if your blocking function supports asynchronous mode (read the module documentation for this), then you can just throw it in the following function call:

async(blocking_function(...), resume_route);

Note that resume_route has to be a simple route.


Because the async() statement is serial with script execution (see below), the script will be immediately halted when calling it, so any code placed after the async() call will be ignored! The current OpenSIPS worker will launch the asynchronous operation, after which it will continue to process other pending tasks (queued SIP messages, timer jobs or possibly other async operations!). As soon as all data is available, it will run the resume route - thus resuming script execution with a minimum of idle time.


The return code of the function executed in async mode is available in the very beginning of the resume route in the $rc or $retcode variable. Also, all output parameters (variables in function parameters used to carry output values) will be available in resume route.


route
{
    /* preparation code */
    ...
    async(avp_db_query("SELECT credit FROM users WHERE uid='$avp(uid)'", "$avp(credit)"), resume_credit);
    /* script execution is paused right away! */
}

route [resume_credit]
{
    if ($rc < 0) {
        xlog("error $rc in avp_db_query()\n");
        exit;
    }

    xlog("Credit of user $avp(uid) is $avp(credit)\n");
    ...
    t_relay();
}


Data is copied over to the resume route as follows:


Preserved data (still available in resume route)

Ignored data (not available anymore in resume route)

3.  Parallel asynchronous operations

The launch() statement of the OpenSIPS script can be used in situations where the script writer needs to perform blocking I/O, but does not depend on the result of this operation in order to continue the current SIP routing decision flow. Some example scenarios:


The launch() statement comes with no additional module dependencies.

3.1  Script syntax and usage

Similarly to the async() statement, if your blocking function supports asynchronous mode (read the module documentation for this), then you can just throw it in the following function calls:

launch(blocking_function(...));
or
launch(blocking_function(...), report_route);

Note that report_route has to be a simple route.


The launch() statement is both asynchronous and parallel with the script execution that follows it (see below). Notice how the "report_route" can be omitted, as script execution does not depend on it. This route may be triggered at any of the following points in time:


The return code of the function executed in async mode is available in the very beginning of the report route in the $rc or $retcode variable. Also, only the output parameters (variables in function parameters used to carry output values) will be available inside this route.


route
{
    /* preparation code */
    ...

    # send a push notification asynchronously, in parallel
    launch(exec("/usr/local/bin/send-google-pn.py"), pn_counter);
    t_relay();
}

route [pn_counter]
{
    if ($rc < 0) {
        xlog("error $rc in pn script!\n");
        update_stat("pn-failure", "1");
        exit;
    }

    update_stat("pn-success", "1");
}


Preserved data (still available in report route)

Ignored data (not available anymore in report route)

4.  List of async functions

The following functions may also be called asynchronously:

The async implementation is not limited to the above functions, but these are the first ones migrated to async support. More I/O related functions will be ported to the async support.

5.  Limitations

5.1  Async Engine Compatibility

The async engine is heavily dependent on non-blocking I/O features exposed by the underlying libraries -- a blocking I/O operation, such as an HTTP or an SQL query can only be made asynchronous if the library additionally provides both:

5.2  TCP Connect Issues

Although they provide async functionality, some libraries only do this for the "transfer" part of the I/O operation, and NOT the initial TCP connect. Consequently, on some corner-case scenarios (e.g. the TCP connect hangs due to an unresponsive server, an in-between firewall which drops packets instead of rejecting them, etc.) the async operation may actually block!


Examples of modules which are affected by this limitation:

Mitigation: depending on your specific setup, you may be severely impacted by these blocking TCP connects or little to not at all. For the former case, we suggest forking external processes responsible for your blocking operations and invoke them asynchronously, using constructs such as:


async(exec("curl my_host", $var(response_body)), resume_route);

or

async(exec("mysql-query 'SELECT * FROM subscriber...'", $var(result_row)), resume_route);

5.3  Allowed Routes

Since the async engine is tightly coupled with the transactional engine, async operations can, at best, only be launched in routes where a SIP transaction is present and is still awaiting completion. This includes:

Async operations performed on any other route types are subject to undefined behavior.

Retrieved from https://www.opensips.org/Documentation/Script-Async-3-1
Page last modified on February 03, 2020, at 04:37 PM