[sr-dev] git:master: async: added module documentation
Daniel-Constantin Mierla
miconda at gmail.com
Sun Jun 26 11:52:40 CEST 2011
Module: sip-router
Branch: master
Commit: bf05608198b343960d85bcfd6d210dba5fada5f5
URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=bf05608198b343960d85bcfd6d210dba5fada5f5
Author: Daniel-Constantin Mierla <miconda at gmail.com>
Committer: Daniel-Constantin Mierla <miconda at gmail.com>
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
+
+ <miconda at gmail.com>
+
+Edited by
+
+Daniel-Constantin Mierla
+
+ <miconda at gmail.com>
+
+ 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>
+ <email>miconda at gmail.com</email>
+ </author>
+ <editor>
+ <firstname>Daniel-Constantin</firstname>
+ <surname>Mierla</surname>
+ <email>miconda at gmail.com</email>
+ </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>
+
More information about the sr-dev
mailing list