From 84898be41740624ceb03a2f135683c880f5f95e0 Mon Sep 17 00:00:00 2001 From: Kamailio Dev Date: Mon, 21 Feb 2022 12:46:21 +0100 Subject: [PATCH] modules: readme files regenerated - async ... [skip ci] --- src/modules/async/README | 412 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 412 insertions(+) diff --git a/src/modules/async/README b/src/modules/async/README index 8b137891791..baaceafeca2 100644 --- a/src/modules/async/README +++ b/src/modules/async/README @@ -1 +1,413 @@ +ASYNC Module +Daniel-Constantin Mierla + + + +Edited by + +Daniel-Constantin Mierla + + + + Copyright © 2011-2016 asipto.com + __________________________________________________________________ + + Table of Contents + + 1. Admin Guide + + 1. Overview + 2. Dependencies + + 2.1. Kamailio Modules + 2.2. External Libraries or Applications + + 3. Parameters + + 3.1. workers (int) + 3.2. ms_timer (int) + 3.3. return (int) + + 4. Functions + + 4.1. async_route(routename, seconds) + 4.2. async_ms_route(routename, milliseconds) + 4.3. async_sleep(seconds) + 4.4. async_ms_sleep(milliseconds) + 4.5. async_task_route(routename) + 4.6. async_task_group_route(routename, groupname) + 4.7. async_task_data(routename, data) + 4.8. async_task_group_data(routename, groupname, data) + + List of Examples + + 1.1. Set workers parameter + 1.2. Set ms_timer parameter + 1.3. Set workers parameter + 1.4. async_route usage + 1.5. async_ms_route usage + 1.6. async_sleep usage + 1.7. async_ms_sleep usage + 1.8. async_workers usage + 1.9. async_task_route usage + 1.10. async_task_group_route usage + 1.11. async_task_data usage + 1.12. async_task_group_data usage + +Chapter 1. Admin Guide + + Table of Contents + + 1. Overview + 2. Dependencies + + 2.1. Kamailio Modules + 2.2. External Libraries or Applications + + 3. Parameters + + 3.1. workers (int) + 3.2. ms_timer (int) + 3.3. return (int) + + 4. Functions + + 4.1. async_route(routename, seconds) + 4.2. async_ms_route(routename, milliseconds) + 4.3. async_sleep(seconds) + 4.4. async_ms_sleep(milliseconds) + 4.5. async_task_route(routename) + 4.6. async_task_group_route(routename, groupname) + 4.7. async_task_data(routename, data) + 4.8. async_task_group_data(routename, groupname, data) + +1. Overview + + This module provides asynchronous operations for handling SIP requests + in the configuration file. + + Async uses t_suspend() and t_continue() from the TM and TMX modules. + + Note that after invoking the asynchronous operation, the processing + will continue later in another application process. Therefore variables + stored in private memory should not be used, try to use shared memory + if you want to get values after the processing is resumed (e.g., + $avp(...), $xavp(...), $shv(...), htable $sht(...)). + +2. Dependencies + + 2.1. Kamailio Modules + 2.2. External Libraries or Applications + +2.1. Kamailio Modules + + The following modules must be loaded before this module: + * tm - transaction management. + * tmx - transaction management extensions. + +2.2. External Libraries or Applications + + The following libraries or applications must be installed before + running Kamailio with this module loaded: + * None + +3. Parameters + + 3.1. workers (int) + 3.2. ms_timer (int) + 3.3. return (int) + +3.1. workers (int) + + Number of worker processes to be started to handle the asynchronous + tasks for async_route() and async_sleep(). + + Default value is 1. + + Example 1.1. Set workers parameter +... +modparam("async", "workers", 2) +... + +3.2. ms_timer (int) + + Enables millisecond timer for async_ms_sleep() and async_ms_route() + functions. The integer value is the timer resolution in milliseconds. A + smaller timer resolution will generate a higher load on the system. If + you set ms_timer to 1 you will get a timer with 1 millisecond + resolution, a setting of 20 provides a resolution of 20ms. + + Default value is 0. + + Example 1.2. Set ms_timer parameter +... +modparam("async", "ms_timer", 10) +... + +3.3. return (int) + + The value to be returned by async functions on success. It does not + apply for async data functions, only for those that suspend the SIP + transaction. + + Default value is 0. + + Example 1.3. Set workers parameter +... +modparam("async", "return", 1) +... + +4. Functions + + 4.1. async_route(routename, seconds) + 4.2. async_ms_route(routename, milliseconds) + 4.3. async_sleep(seconds) + 4.4. async_ms_sleep(milliseconds) + 4.5. async_task_route(routename) + 4.6. async_task_group_route(routename, groupname) + 4.7. async_task_data(routename, data) + 4.8. async_task_group_data(routename, groupname, data) + +4.1. async_route(routename, seconds) + + Simulate a sleep of 'seconds' and then continue the processing of the + SIP request with the route[routename]. In case of internal errors, the + function returns false, otherwise the function exits the execution of + the script at that moment (return 0 behaviour). + + The routename parameter can be a static string or a dynamic string + value with config variables. + + The sleep parameter represent the number of seconds to suspend the + processing of a SIP request. Maximum value is 100. The parameter can be + a static integer or a variable holding an integer. + + Since the SIP request handling is resumed in another process, the + config file execution state is practically lost. Therefore beware that + the execution of config after resume will end once the route[routename] + is finished. + + This function can be used from REQUEST_ROUTE. + + Example 1.4. async_route usage +... +request_route { + ... + async_route("RESUME", "4"); + ... +} +route[RESUME] { + send_reply("404", "Not found"); + exit; +} +... + +4.2. async_ms_route(routename, milliseconds) + + Simulate a sleep of 'milliseconds' and then continue the processing of + the SIP request with the route[routename]. In case of internal errors, + the function returns false, otherwise the function exits the execution + of the script at that moment (return 0 behaviour). This function works + only if the ms_timer parameter has a value greater then 0. + + The routename parameter can be a static string or a dynamic string + value with config variables. + + The sleep parameter represent the number of milliseconds to suspend the + processing of a SIP request. Maximum value is 30000 (30 sec). The + parameter can be a static integer or a variable holding an integer. + + Since the SIP request handling is resumed in another process, the + config file execution state is practically lost. Therefore beware that + the execution of config after resume will end once the route[routename] + is finished. + + This function can be used from REQUEST_ROUTE. + + Example 1.5. async_ms_route usage +... +request_route { + ... + async_ms_route("RESUME", "250"); + ... +} +route[RESUME] { + send_reply("404", "Not found"); + exit; +} +... + +4.3. async_sleep(seconds) + + Simulate a sleep of 'seconds' and then continue the processing of SIP + request with the next action. In case of internal errors, the function + returns false. + + The sleep parameter represent the number of seconds to suspend the + processing of SIP request. Maximum value is 100. The parameter can be a + static integer or a variable holding an integer. + + This function can be used from REQUEST_ROUTE. + + Example 1.6. async_sleep usage +... +async_sleep("4"); +send_reply("404", "Not found"); +exit; +... + +4.4. async_ms_sleep(milliseconds) + + Simulate a sleep of 'milliseconds' and then continue the processing of + SIP request with the next action. In case of internal errors, the + function returns false. This function works only if the ms_timer + parameter has a value greater then 0. + + The sleep parameter represent the number of milliseconds to suspend the + processing of SIP request. Maximum value is 30000 (30 sec). The + parameter can be a static integer or a variable holding an integer. + + This function can be used from REQUEST_ROUTE. + + Example 1.7. async_ms_sleep usage +... +route[REQUESTSHAPER] { + $var(res) = http_connect("leakybucket", + "/add?key=$fd", $null, $null,"$avp(delay)"); + $var(d) = $(avp(delay){s.int}); + if ($var(d) > 0) { + # Delay the request by $avp(delay) ms + async_ms_sleep("$var(d)"); + if (!t_relay()) { + sl_reply_error(); + } + exit; + } + # No delay + if (!t_relay()) { + sl_reply_error(); + } + exit; +} +... + +4.5. async_task_route(routename) + + Continue the processing of the SIP request with the route[routename] in + one of the processes from first group of core asynchronous framework. + The core parameter async_workers has to be set to enable asynchronous + framework. The task is executed as soon as a process from asynchronous + framework is idle, there is no wait time for the task like for + async_route(...). + + To enable the core asynchronous framework, you need to set the + async_workers core parameter in the configuration file. See the core + cookbook for more information. + + Example 1.8. async_workers usage +... +# Enable 8 worker processes used by async and other modules +async_workers=8 +... + + In case of internal errors, the function returns false, otherwise the + function exits the execution of the script at that moment (return 0 + behaviour). + + The routename parameter can be a static string or a dynamic string + value with config variables. + + Since the SIP request handling is resumed in another process, the + config file execution state is practically lost. Therefore beware that + the execution of config after resume will end once the route[routename] + is finished. + + This function can be used from REQUEST_ROUTE. + + Example 1.9. async_task_route usage +... +request_route { + ... + async_task_route("RESUME"); + ... +} +route[RESUME] { + t_relay(); + exit; +} +... + +4.6. async_task_group_route(routename, groupname) + + Similar to async_task_route(), but allows to specify the name of the + group for asynchronous workers. See also 'async_workers_group' core + global parameter. + + This function can be used from REQUEST_ROUTE. + + Example 1.10. async_task_group_route usage +... +async_workers_group="name=abc;workers=4;nonblock=0;usleep=0" +... +request_route { + ... + async_task_route("RESUME", "abc"); + ... +} +route[RESUME] { + t_relay(); + exit; +} +... + +4.7. async_task_data(routename, data) + + Send the data to a asynchronous task process (in the first group) that + executes the route[rountename] and makes the data available via + $async(data). + + The current SIP message is not suspended and it is not available in the + asynchronous task process, a local faked SIP request is used there. + + The parameters can contain variables. + + This function can be used from ANY_ROUTE. + + Example 1.11. async_task_data usage +... +async_workers_group="name=abc;workers=4;nonblock=0;usleep=0" +... +request_route { + ... + async_task_data("RESUME", "caller: $fU - callee: $tU"); + ... +} +route[RESUME] { + xinfo("$async(data)\n"); + exit; +} +... + +4.8. async_task_group_data(routename, groupname, data) + + Similar to async_task_route(), but allows to specify the name of the + group for asynchronous workers. See also 'async_workers_group' core + global parameter. + + This function can be used from ANY_ROUTE. + + Example 1.12. async_task_group_data usage +... +async_workers_group="name=abc;workers=4;nonblock=0;usleep=0" +... +request_route { + ... + async_task_data("RESUME", "abc", "caller: $fU - callee: $tU"); + ... +} +route[RESUME] { + xinfo("$async(data)\n"); + exit; +} +...