From 10292cf151bd4d0ab9d2926d6acc9e2642b6f6da Mon Sep 17 00:00:00 2001
From: Daniel-Constantin Mierla <miconda@gmail.com>
Date: Thu, 26 Nov 2020 13:44:27 +0100
Subject: [PATCH] sworker: docs update to reflect use with
 event_route[core:pre-routing]

---
 src/modules/sworker/doc/sworker_admin.xml | 31 ++++++++++++++++-------
 1 file changed, 22 insertions(+), 9 deletions(-)

diff --git a/src/modules/sworker/doc/sworker_admin.xml b/src/modules/sworker/doc/sworker_admin.xml
index e1675a45bf4..9656ff1071f 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");
     ...