kamailio/modules/async/doc/async_admin.xml

<?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 "../../../docbook/entities.xml">
%docentities;

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

<chapter>
	
	<title>&adminguide;</title>
	
	<section>
	<title>Overview</title>
	<para>
		This module provides asynchornous operations for handling SIP requests
		in configuration file.
	</para>
	<para>
		It uses t_suspend() and t_continue() from TM module.
	</para>
	<para>
		Note that after invoking the an asyncronous operation, the processing
		will continue later, in another application process. Therefore, do not
		rely on variables stored in private memory, used shared memory if you
		want to get values after the processing is resumend (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>
			</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>
		<title><varname>workers</varname> (int)</title>
		<para>
			Number of worker processes to be started to handle the asynchornous
			tasks.
		</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>

	<section>
	<title>Functions</title>
	<section>
	    <title>
		<function moreinfo="none">async_route(routename, seconds)</function>
	    </title>
	    <para>
		Simulate a sleep of 'seconds' and then continue the processing of SIP
		request with the route[routename]. In case of internal errors, the
		function returns false, otherwise the function exits the execution of
		config 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 suppend the
		processing of SIP request. Maximum value is 100. The parameter can be
		a static integer or a varaible holding an integer.
		</para>
		<para>
		Since the SIP request handling is resumed in another process,
		practically the config file execution state is 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_sleep</function> usage</title>
		<programlisting format="linespecific">
...
async_route("RESUME", "4");
...
route[RESUME] {
   send_reply("404", "Not found");
   exit;
}
...
</programlisting>
	    </example>
	</section>

	<section>
	    <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. In case of internal errors, the function
		returns false, otherwise the function exits the execution of config
		at that moment (return 0 behaviour).
		</para>
		<para>
		The sleep parameter represent the number of seconds to suppend the
		processing of SIP request. Maximum value is 100. The parameter can be
		a static integer or a varaible holding an integer.
		</para>
		<para>
		Since the SIP request handling is resumed in another process,
		practically the config file execution state is lost. Therefore beware
		that the execution of config after resume will end once the route block
		where async_sleep() is called is finished.
		</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>
</chapter>