[sr-dev] git:master: async: added module documentation

Module: sip-router Branch: master Commit: bf05608198b343960d85bcfd6d210dba5fada5f5 URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=bf05608… Author: Daniel-Constantin Mierla &lt;miconda(a)gmail.com&gt; Committer: Daniel-Constantin Mierla &lt;miconda(a)gmail.com&gt; Date: Sun Jun 26 11:05:23 2011 +0200 async: added module documentation --- modules/async/README | 127 +++++++++++++++++++++++++++++++++++++ modules/async/doc/Makefile | 4 + modules/async/doc/async.xml | 37 +++++++++++ modules/async/doc/async_admin.xml | 124 ++++++++++++++++++++++++++++++++++++ 4 files changed, 292 insertions(+), 0 deletions(-) diff --git a/modules/async/README b/modules/async/README new file mode 100644 index 0000000..c10a562 --- /dev/null +++ b/modules/async/README @@ -0,0 +1,127 @@ +ASYNC Module + +Daniel-Constantin Mierla + + &lt;miconda(a)gmail.com&gt; + +Edited by + +Daniel-Constantin Mierla + + &lt;miconda(a)gmail.com&gt; + + 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; +... diff --git a/modules/async/doc/Makefile b/modules/async/doc/Makefile new file mode 100644 index 0000000..97b75e9 --- /dev/null +++ b/modules/async/doc/Makefile @@ -0,0 +1,4 @@ +docs = async.xml + +docbook_dir = ../../../docbook +include $(docbook_dir)/Makefile.module diff --git a/modules/async/doc/async.xml b/modules/async/doc/async.xml new file mode 100644 index 0000000..a722fb0 --- /dev/null +++ b/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> + &lt;email&gt;miconda(a)gmail.com&lt;/email&gt; + </author> + <editor> + <firstname>Daniel-Constantin</firstname> + <surname>Mierla</surname> + &lt;email&gt;miconda(a)gmail.com&lt;/email&gt; + </editor> + </authorgroup> + <copyright> + <year>2011</year> + <holder>asipto.com</holder> + </copyright> + </bookinfo> + <toc></toc> + + <xi:include href="async_admin.xml"/> + + +</book> diff --git a/modules/async/doc/async_admin.xml b/modules/async/doc/async_admin.xml new file mode 100644 index 0000000..2506f06 --- /dev/null +++ b/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> +