<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

<!-- Include general documentation entities -->
<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
%docentities;

]>
<!-- Module User's Guide -->

<chapter>

	<title>&adminguide;</title>

	<section>
	<title>Overview</title>
	<para>
		This module provides asynchronous operations for handling SIP requests
		in the configuration file.
	</para>
	<para>
		Async uses t_suspend() and t_continue() from the TM and TMX modules.
	</para>
	<para>
		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(...)).
	</para>
	</section>

	<section>
	<title>Dependencies</title>
	<section>
		<title>&kamailio; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>tm</emphasis> - transaction management.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>tmx</emphasis> - transaction management extensions.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before running
		&kamailio; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>None</emphasis>
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>
	<section>
	<title>Parameters</title>
	<section id="async.p.workers">
		<title><varname>workers</varname> (int)</title>
		<para>
			Number of worker processes to be started to handle the asynchronous
			tasks for async_route() and async_sleep().
		</para>
		<para>
		<emphasis>
			Default value is 1.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>workers</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("async", "workers", 2)
...
</programlisting>
		</example>
	</section>
	<section id="async.p.ms_timer">
		<title><varname>ms_timer</varname> (int)</title>
		<para>
			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.
		</para>
		<para>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>ms_timer</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("async", "ms_timer", 10)
...
</programlisting>
		</example>
	</section>
	<section id="async.p.return">
		<title><varname>return</varname> (int)</title>
		<para>
			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.
		</para>
		<para>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>workers</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("async", "return", 1)
...
</programlisting>
		</example>
	</section>
	<section id="async.p.mode">
		<title><varname>mode</varname> (int)</title>
		<para>
			Control if the module should bind (0) to tm or not (1). It may not
			be needed to use tm functions (e.g., when needing async_tkv_emit()
			only).
		</para>
		<para>
		<emphasis>
			Default value is 0 (bind to tm module).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>mode</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("async", "mode", 1)
...
</programlisting>
		</example>
	</section>
	</section>

	<section>
	<title>Functions</title>
	<section id="async.f.async_route">
		<title>
		<function moreinfo="none">async_route(routename, seconds)</function>
		</title>
		<para>
		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).
		</para>
		<para>
		The routename parameter can be a static string or a dynamic string
		value with config variables.
		</para>
		<para>
		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.
		</para>
		<para>
		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.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>async_route</function> usage</title>
		<programlisting format="linespecific">
...
request_route {
    ...
    async_route("RESUME", "4");
    ...
}
route[RESUME] {
   send_reply("404", "Not found");
   exit;
}
...
</programlisting>
		</example>
	</section>
	<section id="async.f.async_ms_route">
		<title>
		<function moreinfo="none">async_ms_route(routename, milliseconds)</function>
		</title>
		<para>
		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 than 0.
		</para>
		<para>
		The routename parameter can be a static string or a dynamic string
		value with config variables.
		</para>
		<para>
		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.
		</para>
		<para>
		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.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>async_ms_route</function> usage</title>
		<programlisting format="linespecific">
...
request_route {
    ...
    async_ms_route("RESUME", "250");
    ...
}
route[RESUME] {
   send_reply("404", "Not found");
   exit;
}
...
</programlisting>
		</example>
	</section>

	<section id="async.f.async_sleep">
		<title>
		<function moreinfo="none">async_sleep(seconds)</function>
		</title>
		<para>
		Simulate a sleep of 'seconds' and then continue the processing of SIP
		request with the next action. Note that the processing continues till
		the last action in the current route block. Consider using async_route()
		instead if you want to control better what is executed after the wait
		time. Beacuse the execution is resumed in another process, do not use
		private memory variables before and after the async sleep.
		</para>
		<para>
		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.
		</para>
		<para>
		In case of internal errors, the function returns false.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>async_sleep</function> usage</title>
		<programlisting format="linespecific">
...
async_sleep("4");
send_reply("404", "Not found");
exit;
...
</programlisting>
		</example>
	</section>

	<section id="async.f.async_ms_sleep">
		<title>
		<function moreinfo="none">async_ms_sleep(milliseconds)</function>
		</title>
		<para>
		Similar to async_sleep(), but with a 'milliseconds' parameter. This
		function works only if the ms_timer parameter has a value greater than 0.
		</para>
		<para>
		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.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>async_ms_sleep</function> usage</title>
		<programlisting format="linespecific">
...
route[REQUESTSHAPER] {
	$var(res) = http_connect("leakybucket",
			"/add?key=$fd", $null, $null,"$avp(delay)");
	$var(d) = $(avp(delay){s.int});
	if ($var(d) &gt; 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;
}
...
</programlisting>
		</example>
	</section>

	<section id="async.f.async_task_route">
		<title>
		<function moreinfo="none">async_task_route(routename)</function>
		</title>
		<para>
		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(...).
		</para>
		<para>
		To enable the core asynchronous framework, you need to set the
		<emphasis>async_workers</emphasis> core parameter in the configuration
		file. See the core cookbook for more information.
		<example>
		<title><function>async_workers</function> usage</title>
		<programlisting format="linespecific">
...
# Enable 8 worker processes used by async and other modules
async_workers=8
...
</programlisting>
		</example>
		</para>
		<para>
		In case of internal errors, the function returns false, otherwise the
		function exits the execution of the script at that moment (return
		0 behaviour).
		</para>
		<para>
		The routename parameter can be a static string or a dynamic string
		value with config variables.
		</para>
		<para>
		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.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>async_task_route</function> usage</title>
		<programlisting format="linespecific">
...
request_route {
    ...
    async_task_route("RESUME");
    ...
}
route[RESUME] {
   t_relay();
   exit;
}
...
</programlisting>
	</example>
	</section>
	<section id="async.f.async_task_group_route">
		<title>
		<function moreinfo="none">async_task_group_route(routename, groupname)</function>
		</title>
		<para>
		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.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>async_task_group_route</function> usage</title>
		<programlisting format="linespecific">
...
async_workers_group="name=abc;workers=4;nonblock=0;usleep=0"
...
request_route {
    ...
    async_task_route("RESUME", "abc");
    ...
}
route[RESUME] {
   t_relay();
   exit;
}
...
</programlisting>
	</example>
	</section>
	<section id="async.f.async_task_data">
		<title>
			<function moreinfo="none">async_task_data(routename, data)</function>
		</title>
		<para>
		Send the data to an asynchronous task process (in the first group) that
		executes the route[rountename] and makes the data available via $async(data).
		</para>
		<para>
		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.
		</para>
		<para>
		The parameters can contain variables.
		</para>
		<para>
		This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>async_task_data</function> usage</title>
		<programlisting format="linespecific">
...
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;
}
...
</programlisting>
	</example>
	</section>
	<section id="async.f.async_task_group_data">
		<title>
			<function moreinfo="none">async_task_group_data(routename, groupname, data)</function>
		</title>
		<para>
		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.
		</para>
		<para>
		This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>async_task_group_data</function> usage</title>
		<programlisting format="linespecific">
...
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;
}
...
</programlisting>
	</example>
	</section>
	<section id="async.f.async_tkv_emit">
		<title>
			<function moreinfo="none">async_tkv_emit(type, key, value)</function>
		</title>
		<para>
		Emit a type-key-value event.
		</para>
		<para>
		This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>async_tkv_emit</function> usage</title>
		<programlisting format="linespecific">
...
async_workers_group="name=tkv;workers=1;nonblock=0;usleep=0"
...
request_route {
    ...
    async_tkv_emit("8000", "call", "caller='$fU';callee='$tU'");
    ...
}
event_route[core:tkv] {
    xinfo("$atkv(type) / $atkv(key) / $atkv(val)\n");
    exit;
}
...
</programlisting>
	</example>
	</section>
	</section>
</chapter>
