[sr-dev] git:master: async: documentation for async_task_route()

[Daniel-Constantin Mierla]

Module: sip-router
Branch: master
Commit: 272b23738de76d397c145c44c22a943fe198f753
URL:    http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=272b23738de76d397c145c44c22a943fe198f753

Author: Daniel-Constantin Mierla <miconda at gmail.com>
Committer: Daniel-Constantin Mierla <miconda at gmail.com>
Date:   Mon Apr 14 14:28:13 2014 +0200

async: documentation for async_task_route()

---

 modules/async/README              |   36 +++++++++++++++++++++++++++
 modules/async/doc/async_admin.xml |   49 +++++++++++++++++++++++++++++++++++-
 2 files changed, 83 insertions(+), 2 deletions(-)

diff --git a/modules/async/README b/modules/async/README
index 4f2c0ef..3dd83a0 100644
--- a/modules/async/README
+++ b/modules/async/README
@@ -31,12 +31,14 @@ Daniel-Constantin Mierla
 
               4.1. async_route(routename, seconds)
               4.2. async_sleep(seconds)
+              4.3. async_task_route(routename)
 
    List of Examples
 
    1.1. Set workers parameter
    1.2. async_sleep usage
    1.3. async_sleep usage
+   1.4. async_task_route usage
 
 Chapter 1. Admin Guide
 
@@ -56,6 +58,7 @@ Chapter 1. Admin Guide
 
         4.1. async_route(routename, seconds)
         4.2. async_sleep(seconds)
+        4.3. async_task_route(routename)
 
 1. Overview
 
@@ -107,6 +110,7 @@ modparam("async", "workers", 2)
 
    4.1. async_route(routename, seconds)
    4.2. async_sleep(seconds)
+   4.3. async_task_route(routename)
 
 4.1. async_route(routename, seconds)
 
@@ -157,3 +161,35 @@ async_sleep("4");
 send_reply("404", "Not found");
 exit;
 ...
+
+4.3. async_task_route(routename)
+
+   Continue the processing of the SIP request with the route[routename] in
+   one of the processes from 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(...).
+
+   In case of internal errors, the function returns false, otherwise the
+   function exits the execution of the script at that moment (return 0
+   behaviour).
+
+   The routename parameter can be a static string or a dynamic string
+   value with config variables.
+
+   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.
+
+   This function can be used from REQUEST_ROUTE.
+
+   Example 1.4. async_task_route usage
+...
+async_task_rroute("RESUME");
+...
+route[RESUME] {
+   send_reply("404", "Not found");
+   exit;
+}
+...
diff --git a/modules/async/doc/async_admin.xml b/modules/async/doc/async_admin.xml
index 02d4b26..8556fd2 100644
--- a/modules/async/doc/async_admin.xml
+++ b/modules/async/doc/async_admin.xml
@@ -90,7 +90,7 @@ modparam("async", "workers", 2)
 
 	<section>
 	<title>Functions</title>
-	<section>
+	<section id="async.f.async_route">
 	    <title>
 		<function moreinfo="none">async_route(routename, seconds)</function>
 	    </title>
@@ -133,7 +133,7 @@ route[RESUME] {
 	    </example>
 	</section>
 
-	<section>
+	<section id="async.f.async_sleep">
 	    <title>
 		<function moreinfo="none">async_sleep(seconds)</function>
 	    </title>
@@ -161,6 +161,51 @@ 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 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>
+		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">
+...
+async_task_rroute("RESUME");
+...
+route[RESUME] {
+   send_reply("404", "Not found");
+   exit;
+}
+...
+</programlisting>
+	    </example>
+	</section>
 	</section>
 </chapter>