async: added module documentation

modules/async/README

@@ -0,0 +1,127 @@
+ASYNC Module
+
+Daniel-Constantin Mierla
+
+   <[email protected]>
+
+Edited by
+
+Daniel-Constantin Mierla
+
+   <[email protected]>
+
+   Copyright © 2011 asipto.com
+     __________________________________________________________________
+
+   Table of Contents
+
+   1. Admin Guide
+
+        1. Overview
+        2. Dependencies
+
+              2.1. Kamailio Modules
+              2.2. External Libraries or Applications
+
+        3. Exported Parameters
+
+              3.1. workers (int)
+
+        4. Exported Functions
+
+              4.1. async_sleep(seconds)
+
+   List of Examples
+
+   1.1. Set workers parameter
+   1.2. async_sleep usage
+
+Chapter 1. Admin Guide
+
+   Table of Contents
+
+   1. Overview
+   2. Dependencies
+
+        2.1. Kamailio Modules
+        2.2. External Libraries or Applications
+
+   3. Exported Parameters
+
+        3.1. workers (int)
+
+   4. Exported Functions
+
+        4.1. async_sleep(seconds)
+
+1. Overview
+
+   This module provides asynchornous operations for handling SIP requests
+   in configuration file.
+
+   It uses t_suspend() and t_continue() from TM module.
+
+   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., $shv(...) of
+   htable $sht(...)).
+
+2. Dependencies
+
+   2.1. Kamailio Modules
+   2.2. External Libraries or Applications
+
+2.1. Kamailio Modules
+
+   The following modules must be loaded before this module:
+     * tm - transaction management.
+
+2.2. External Libraries or Applications
+
+   The following libraries or applications must be installed before
+   running Kamailio with this module loaded:
+     * None
+
+3. Exported Parameters
+
+   3.1. workers (int)
+
+3.1. workers (int)
+
+   Number of worker processes to be started to handle the asynchornous
+   tasks.
+
+   Default value is 1.
+
+   Example 1.1. Set workers parameter
+...
+modparam("async", "workers", 2)
+...
+
+4. Exported Functions
+
+   4.1. async_sleep(seconds)
+
+4.1. async_sleep(seconds)
+
+   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).
+
+   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.
+
+   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.
+
+   Example 1.2. async_sleep usage
+...
+async_sleep("4");
+send_reply("404", "Not found");
+exit;
+...

modules/async/doc/Makefile

@@ -0,0 +1,4 @@
+docs = async.xml
+
+docbook_dir = ../../../docbook
+include $(docbook_dir)/Makefile.module

modules/async/doc/async.xml

@@ -0,0 +1,37 @@
+<?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;
+
+]>
+
+<book xmlns:xi="http://www.w3.org/2001/XInclude">
+    <bookinfo>
+	<title>ASYNC Module</title>
+	<productname class="trade">sip-router.org</productname>
+	<authorgroup>
+	    <author>
+		<firstname>Daniel-Constantin</firstname>
+		<surname>Mierla</surname>
+		<email>[email protected]</email>
+	    </author>
+	    <editor>
+		<firstname>Daniel-Constantin</firstname>
+		<surname>Mierla</surname>
+		<email>[email protected]</email>
+	    </editor>
+	</authorgroup>
+	<copyright>
+	    <year>2011</year>
+	    <holder>asipto.com</holder>
+	</copyright>
+    </bookinfo>
+    <toc></toc>
+    
+    <xi:include href="async_admin.xml"/>
+    
+    
+</book>

modules/async/doc/async_admin.xml

@@ -0,0 +1,124 @@
+<?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., $shv(...)
+		of 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>Exported 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>Exported Functions</title>
+ 	<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>
+		<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>
+