async: small extension of the description for the ms_timer parameter
[kamailio] / src / modules / async / doc / async_admin.xml
1 <?xml version="1.0" encoding='ISO-8859-1'?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
5 <!-- Include general documentation entities -->
6 <!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
7 %docentities;
8
9 ]>
10 <!-- Module User's Guide -->
11
12 <chapter>
13
14         <title>&adminguide;</title>
15
16         <section>
17         <title>Overview</title>
18         <para>
19                 This module provides asynchronous operations for handling SIP requests
20                 in the configuration file.
21         </para>
22         <para>
23                 Async uses t_suspend() and t_continue() from the TM and TMX modules.
24         </para>
25         <para>
26                 Note that after invoking the asynchronous operation, the processing
27                 will continue later in another application process. Therefore variables
28                 stored in private memory should not be used, try to use shared memory if you
29                 want to get values after the processing is resumed (e.g., $avp(...),
30                 $xavp(...), $shv(...), htable $sht(...)).
31         </para>
32         </section>
33
34         <section>
35         <title>Dependencies</title>
36         <section>
37                 <title>&kamailio; Modules</title>
38                 <para>
39                 The following modules must be loaded before this module:
40                         <itemizedlist>
41                         <listitem>
42                         <para>
43                                 <emphasis>tm</emphasis> - transaction management.
44                         </para>
45                         </listitem>
46                         <listitem>
47                         <para>
48                                 <emphasis>tmx</emphasis> - transaction management extensions.
49                         </para>
50                         </listitem>
51                         </itemizedlist>
52                 </para>
53         </section>
54         <section>
55                 <title>External Libraries or Applications</title>
56                 <para>
57                 The following libraries or applications must be installed before running
58                 &kamailio; with this module loaded:
59                         <itemizedlist>
60                         <listitem>
61                         <para>
62                                 <emphasis>None</emphasis>
63                         </para>
64                         </listitem>
65                         </itemizedlist>
66                 </para>
67         </section>
68         </section>
69         <section>
70         <title>Parameters</title>
71         <section>
72                 <title><varname>workers</varname> (int)</title>
73                 <para>
74                         Number of worker processes to be started to handle the asynchronous
75                         tasks for async_route() and async_sleep().
76                 </para>
77                 <para>
78                 <emphasis>
79                         Default value is 1.
80                 </emphasis>
81                 </para>
82                 <example>
83                 <title>Set <varname>workers</varname> parameter</title>
84                 <programlisting format="linespecific">
85 ...
86 modparam("async", "workers", 2)
87 ...
88 </programlisting>
89                 </example>
90         </section>
91         <section>
92                 <title><varname>ms_timer</varname> (int)</title>
93                 <para>
94                         Enables millisecond timer for async_ms_sleep() and async_ms_route() functions.
95                         The integer value is the timer resolution in milliseconds. A smaller timer
96                         resultion will generate a higher load on the system. If you set ms_timer
97                         to 1 you will get a timer with 1 millisecond resultion, a setting of 20
98                         provides a resultion of 20ms.
99                 </para>
100                 <para>
101                 <emphasis>
102                         Default value is 0.
103                 </emphasis>
104                 </para>
105                 <example>
106                 <title>Set <varname>ms_timer</varname> parameter</title>
107                 <programlisting format="linespecific">
108 ...
109 modparam("async", "ms_timer", 10)
110 ...
111 </programlisting>
112                 </example>
113         </section>
114         </section>
115
116         <section>
117         <title>Functions</title>
118         <section id="async.f.async_route">
119                 <title>
120                 <function moreinfo="none">async_route(routename, seconds)</function>
121                 </title>
122                 <para>
123                 Simulate a sleep of 'seconds' and then continue the processing of the SIP
124                 request with the route[routename]. In case of internal errors, the
125                 function returns false, otherwise the function exits the execution of
126                 the script at that moment (return 0 behaviour).
127                 </para>
128                 <para>
129                 The routename parameter can be a static string or a dynamic string
130                 value with config variables.
131                 </para>
132                 <para>
133                 The sleep parameter represent the number of seconds to suspend the
134                 processing of a SIP request. Maximum value is 100. The parameter can be
135                 a static integer or a variable holding an integer.
136                 </para>
137                 <para>
138                 Since the SIP request handling is resumed in another process,
139                 the config file execution state is practically lost. Therefore beware
140                 that the execution of config after resume will end once the
141                 route[routename] is finished.
142                 </para>
143                 <para>
144                 This function can be used from REQUEST_ROUTE.
145                 </para>
146                 <example>
147                 <title><function>async_route</function> usage</title>
148                 <programlisting format="linespecific">
149 ...
150 request_route {
151     ...
152     async_route("RESUME", "4");
153     ...
154 }
155 route[RESUME] {
156    send_reply("404", "Not found");
157    exit;
158 }
159 ...
160 </programlisting>
161                 </example>
162         </section>
163         <section id="async.f.async_ms_route">
164                 <title>
165                 <function moreinfo="none">async_ms_route(routename, milliseconds)</function>
166                 </title>
167                 <para>
168                 Simulate a sleep of 'milliseconds' and then continue the processing of the SIP
169                 request with the route[routename]. In case of internal errors, the
170                 function returns false, otherwise the function exits the execution of
171                 the script at that moment (return 0 behaviour).
172                 This function works only if the ms_timer parameter has a value greater then 0.
173                 </para>
174                 <para>
175                 The routename parameter can be a static string or a dynamic string
176                 value with config variables.
177                 </para>
178                 <para>
179                 The sleep parameter represent the number of milliseconds to suspend the
180                 processing of a SIP request. Maximum value is 30000 (30 sec). The parameter can be
181                 a static integer or a variable holding an integer.
182                 </para>
183                 <para>
184                 Since the SIP request handling is resumed in another process,
185                 the config file execution state is practically lost. Therefore beware
186                 that the execution of config after resume will end once the
187                 route[routename] is finished.
188                 </para>
189                 <para>
190                 This function can be used from REQUEST_ROUTE.
191                 </para>
192                 <example>
193                 <title><function>async_ms_route</function> usage</title>
194                 <programlisting format="linespecific">
195 ...
196 request_route {
197     ...
198     async_ms_route("RESUME", "250");
199     ...
200 }
201 route[RESUME] {
202    send_reply("404", "Not found");
203    exit;
204 }
205 ...
206 </programlisting>
207                 </example>
208         </section>
209
210         <section id="async.f.async_sleep">
211                 <title>
212                 <function moreinfo="none">async_sleep(seconds)</function>
213                 </title>
214                 <para>
215                 Simulate a sleep of 'seconds' and then continue the processing of SIP
216                 request with the next action. In case of internal errors, the function
217                 returns false.
218                 </para>
219                 <para>
220                 The sleep parameter represent the number of seconds to suspend the
221                 processing of SIP request. Maximum value is 100. The parameter can be
222                 a static integer or a variable holding an integer.
223                 </para>
224                 <para>
225                 This function can be used from REQUEST_ROUTE.
226                 </para>
227                 <example>
228                 <title><function>async_sleep</function> usage</title>
229                 <programlisting format="linespecific">
230 ...
231 async_sleep("4");
232 send_reply("404", "Not found");
233 exit;
234 ...
235 </programlisting>
236                 </example>
237         </section>
238
239         <section id="async.f.async_ms_sleep">
240                 <title>
241                 <function moreinfo="none">async_ms_sleep(milliseconds)</function>
242                 </title>
243                 <para>
244                 Simulate a sleep of 'milliseconds' and then continue the processing of SIP
245                 request with the next action. In case of internal errors, the function
246                 returns false.
247                 This function works only if the ms_timer parameter has a value greater then 0.
248                 </para>
249                 <para>
250                 The sleep parameter represent the number of milliseconds to suspend the
251                 processing of SIP request. Maximum value is 30000 (30 sec). The parameter can be
252                 a static integer or a variable holding an integer.
253                 </para>
254                 <para>
255                 This function can be used from REQUEST_ROUTE.
256                 </para>
257                 <example>
258                 <title><function>async_ms_sleep</function> usage</title>
259                 <programlisting format="linespecific">
260 ...
261 route[REQUESTSHAPER] {
262         $var(res) = http_connect("leakybucket",
263                         "/add?key=$fd", $null, $null,"$avp(delay)");
264         $var(d) = $(avp(delay){s.int});
265         if ($var(d) &gt; 0) {
266                 # Delay the request by $avp(delay) ms
267                 async_ms_sleep("$var(d)");
268                 if (!t_relay()) {
269                         sl_reply_error();
270                 }
271                 exit;
272         }
273         # No delay
274         if (!t_relay()) {
275                 sl_reply_error();
276         }
277         exit;
278 }
279 ...
280 </programlisting>
281                 </example>
282         </section>
283
284         <section id="async.f.async_task_route">
285                 <title>
286                 <function moreinfo="none">async_task_route(routename)</function>
287                 </title>
288                 <para>
289                 Continue the processing of the SIP request with the route[routename]
290                 in one of the processes from core asynchronous framework. The core
291                 parameter async_workers has to be set to enable asynchronous
292                 framework. The task is executed as soon as a process from asynchronous
293                 framework is idle, there is no wait time for the task like for
294                 async_route(...).
295                 </para>
296                 <para>
297                 To enable the core asynchronous framework, you need to set the
298                 <emphasis>async_workers</emphasis> core parameter in the configuration
299                 file. See the core cookbook for more information.
300                 <example>
301                 <title><function>async_workers</function> usage</title>
302                 <programlisting format="linespecific">
303 ...
304 # Enable 8 worker processes used by async and other modules
305 async_workers=8
306 ...
307 </programlisting>
308                 </example>
309                 </para>
310                 <para>
311                 In case of internal errors, the function returns false, otherwise the
312                 function exits the execution of the script at that moment (return
313                 0 behaviour).
314                 </para>
315                 <para>
316                 The routename parameter can be a static string or a dynamic string
317                 value with config variables.
318                 </para>
319                 <para>
320                 Since the SIP request handling is resumed in another process,
321                 the config file execution state is practically lost. Therefore beware
322                 that the execution of config after resume will end once the
323                 route[routename] is finished.
324                 </para>
325                 <para>
326                 This function can be used from REQUEST_ROUTE.
327                 </para>
328                 <example>
329                 <title><function>async_task_route</function> usage</title>
330                 <programlisting format="linespecific">
331 ...
332 request_route {
333     ...
334     async_task_route("RESUME");
335     ...
336 }
337 route[RESUME] {
338    t_relay();
339    exit;
340 }
341 ...
342 </programlisting>
343         </example>
344         </section>
345         </section>
346 </chapter>