Documentation |
Documentation -> Manuals -> Manual 2.2 -> Asynchronous StatementsThis page has been visited 7767 times. Pages for other versions: devel 3.5 3.4 Older versions: 3.3 3.2 3.1 3.0 2.4 2.3 2.2 2.1
Table of Content (hide) 1. DescriptionAsynchronous script operations are one of the key features of OpenSIPS 2.2. The main advantage of using them is the fact 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.
2. Module requirementsThe asynchronous script logic is based on the transaction module (tm) - it must be loaded. The SIP transaction is automatically and transparently created (if not existing yet) when an async operation is started. This transaction contains all necessary information to properly suspend script execution (e.g. it stores the updated SIP message, along with all $avp variables). 3. Script syntax and usageUsage is quite 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.
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 the 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"); }
Ignored data (not available anymore in resume route)
4. List of async functionsThe 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. Limitations5.1 Async Engine CompatibilityThe 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 IssuesAlthough 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!
Mitigation: depending on your specific setup, you may be severely impacted by these blocking TCP connects or little to no at all. For the former case, we suggest forking external processes responsible for your blocking operations and invoke them asynchronously, using constructs such as:
or
5.3 Allowed RoutesSince 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. |