<?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 can delegate processing of SIP requests to a group of
		workers in the configuration file by using event_route[core:pre-routing].
		The async workers have to defined with the global parameter. The worker
		process that received the message internally does the usual execution
		of the config script, running request_route or reply_route.
	</para>
	<para>
		Note: the behaviour is different than the async module, because it does
		not create the transaction (obviously also not performing suspend).
	</para>
	<para>
		Note: it does not propagate anything set in the event_route, therefore
		any set flag, or avp, etc. are lost. The SIP message is processed by the
		delegated worker as it was fresh received from the network (including
		parsing).
	</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>None</emphasis>.
			</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>Functions</title>
	<section id="sworker.f.sworker_active">
		<title>
		<function moreinfo="none">sworker_active()</function>
		</title>
		<para>
		Return 1 (true) if the processing happens in an asyn process, or -1
		(false) if the processing is happening in a SIP receiving process.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE|CORE_REPLY_ROUTE.
		</para>
		<example>
		<title><function>sworker_active()</function> usage</title>
		<programlisting format="linespecific">
...
request_route {
    ...
    if(sworker_active()) {
    }
    ...
}
...
</programlisting>
		</example>
	</section>
	<section id="sworker.f.swork_task">
		<title>
		<function moreinfo="none">swork_task(gname)</function>
		</title>
		<para>
		Delegate the processing of SIP message to a group of async workers. The
		function is restricted to be used inside event_route[core:pre-routing].
		</para>
		<para>
		The parameter gname provides the name of the group workers, it can
		contain pseudo-variables.
		</para>
		<para>
		The function returns 1 (true) in case the task is delegated. After that,
		'drop' must be used so processing of the message does not continue to
		request_route or reply_route in the same process, it is going to be done
		by the delegated group of workers. It returns -1 (false) in case there
		was a problem delegating the processing.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE|CORE_REPLY_ROUTE.
		</para>
		<example>
		<title><function>sworker_task()</function> usage</title>
		<programlisting format="linespecific">
...
event_route[core:pre-routing] {
	if(sworker_task("default")) {
		xinfo("===== delegate processing [$Tf] [$si:$sp]\n");
		drop;
	}
	xinfo("===== processing continues [$Tf] [$si:$sp]\n");
    ...
}
...
</programlisting>
		</example>
	</section>

	</section>
</chapter>
