git:master:10292cf1: sworker: docs update to reflect use with event_route[core:pre-routing] - sr-dev

26 Nov 2020

Module: kamailio
Branch: master
Commit: 10292cf151bd4d0ab9d2926d6acc9e2642b6f6da
URL: https://github.com/kamailio/kamailio/commit/10292cf151bd4d0ab9d2926d6acc9e26...
Author: Daniel-Constantin Mierla miconda@gmail.com
Committer: Daniel-Constantin Mierla miconda@gmail.com
Date: 2020-11-26T13:44:27+01:00
sworker: docs update to reflect use with event_route[core:pre-routing]
---
Modified: src/modules/sworker/doc/sworker_admin.xml
---
Diff:  https://github.com/kamailio/kamailio/commit/10292cf151bd4d0ab9d2926d6acc9e26...
Patch: https://github.com/kamailio/kamailio/commit/10292cf151bd4d0ab9d2926d6acc9e26...
---

diff --git a/src/modules/sworker/doc/sworker_admin.xml b/src/modules/sworker/doc/sworker_admin.xml
index e1675a45bf..9656ff1071 100644
--- a/src/modules/sworker/doc/sworker_admin.xml
+++ b/src/modules/sworker/doc/sworker_admin.xml
@@ -17,11 +17,20 @@
    <title>Overview</title>
    <para>
    	This module can delegate processing of SIP requests to a group of
-		workers in the configuration file. The async workers have to defined
-		with the global parameter.
+		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>
-		It does not create the transaction and nor suspend it.
+		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>
@@ -88,14 +97,19 @@ request_route {
    	<function moreinfo="none">swork_task(gname)</function>
    	</title>
    	<para>
-		Delegate the processing of SIP message to a group of async workers.
+		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 0 (exit) in case the task is delegated.
+		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 proble delegating the processing.
    	</para>
    	<para>
    	This function can be used from REQUEST_ROUTE|CORE_REPLY_ROUTE.
@@ -104,11 +118,10 @@ request_route {
    	<title><function>sworker_task()</function> usage</title>
    	<programlisting format="linespecific">
 ...
-request_route {
-	if(!sworker_active()) {
+event_route[core:pre-routing] {
+	if(sworker_task("default")) {
    	xinfo("===== delegate processing [$Tf] [$si:$sp]\n");
-		sworker_task("default");
-		exit;
+		drop;
    }
    xinfo("===== processing continues [$Tf] [$si:$sp]\n");
     ...

    