[sr-dev] git:master: Added note on latent operations to xhttp docs in order to help
Alex Balashov
abalashov at evaristesys.com
Wed Oct 6 11:20:10 CEST 2010
Module: sip-router
Branch: master
Commit: 6bd9d264202716617819efc3a551f04ac21f2040
URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=6bd9d264202716617819efc3a551f04ac21f2040
Author: Alex Balashov <abalashov at evaristesys.com>
Committer: Alex Balashov <abalashov at evaristesys.com>
Date: Wed Oct 6 05:19:11 2010 -0400
Added note on latent operations to xhttp docs in order to help
educate users preemptively about a common pitfall that many
implementors of web service interfaces inside Kamailio/sip-router
are likely to make.
---
modules/xhttp/README | 94 +++++++++++++++++++++++++-----------
modules/xhttp/doc/xhttp.xml | 5 ++
modules/xhttp/doc/xhttp_admin.xml | 35 ++++++++++++++
3 files changed, 105 insertions(+), 29 deletions(-)
diff --git a/modules/xhttp/README b/modules/xhttp/README
index 9619be5..edde90f 100644
--- a/modules/xhttp/README
+++ b/modules/xhttp/README
@@ -10,6 +10,12 @@ Daniel-Constantin Mierla
<miconda at gmail.com>
+Edited by
+
+Alex Balashov
+
+ <abalashov at evaristesys.com>
+
Copyright © 2010 asipto.com
__________________________________________________________________
@@ -18,19 +24,20 @@ Daniel-Constantin Mierla
1. Admin Guide
1. Overview
- 2. Dependencies
+ 2. Note on Latency
+ 3. Dependencies
- 2.1. Kamailio Modules
- 2.2. External Libraries or Applications
+ 3.1. Kamailio Modules
+ 3.2. External Libraries or Applications
- 3. Exported Parameters
+ 4. Exported Parameters
- 3.1. url_skip (str)
- 3.2. url_match (str)
+ 4.1. url_skip (str)
+ 4.2. url_match (str)
- 4. Exported Functions
+ 5. Exported Functions
- 4.1. xhttp_reply(code, reason, ctype, body)
+ 5.1. xhttp_reply(code, reason, ctype, body)
List of Examples
@@ -43,19 +50,20 @@ Chapter 1. Admin Guide
Table of Contents
1. Overview
- 2. Dependencies
+ 2. Note on Latency
+ 3. Dependencies
- 2.1. Kamailio Modules
- 2.2. External Libraries or Applications
+ 3.1. Kamailio Modules
+ 3.2. External Libraries or Applications
- 3. Exported Parameters
+ 4. Exported Parameters
- 3.1. url_skip (str)
- 3.2. url_match (str)
+ 4.1. url_skip (str)
+ 4.2. url_match (str)
- 4. Exported Functions
+ 5. Exported Functions
- 4.1. xhttp_reply(code, reason, ctype, body)
+ 5.1. xhttp_reply(code, reason, ctype, body)
1. Overview
@@ -70,28 +78,56 @@ Chapter 1. Admin Guide
use of $ru will raise errors since the structure of an HTTP URL is not
compatible with that of a SIP URI.
-2. Dependencies
+2. Note on Latency
+
+ Because HTTP requests in xhttp are handled by the same, finite number
+ of SIP worker processes that operate on SIP messages, the same general
+ principles regarding script execution speed and throughput should be
+ observed by the writer in event_route[xhttp:request] as in any other
+ part of the route script.
+
+ For example, if you initiate a database query in the HTTP request route
+ that takes a long time to return rows, the SIP worker process in which
+ the request is handled will be blocked for that time and unable to
+ process other SIP messages. In most typical installations, there are
+ only a few of these worker processes running.
+
+ Therefore, it is highly inadvisable to execute particularly slow things
+ in the event_route[xhttp:request], because the request is not handled
+ in an asynchronous manner or otherwise peripherally to general SIP
+ processing. SIP worker threads will block, pending the outcome of the
+ event route just like any other config script route.
+
+ This is no more or less true for xhttp than it is for any other block
+ of script in any other scenario, and does not warrant any extraordinary
+ concern. It nevertheless bears mention here because some processes with
+ embedded HTTP servers have the request processing take place "outside"
+ of the main synchronous event sequence, whether by creating separate
+ threads or by some other asynchronous handling. That is not the case
+ with xhttp.
+
+3. Dependencies
- 2.1. Kamailio Modules
- 2.2. External Libraries or Applications
+ 3.1. Kamailio Modules
+ 3.2. External Libraries or Applications
-2.1. Kamailio Modules
+3.1. Kamailio Modules
The following modules must be loaded before this module:
* sl - stateless reply.
-2.2. External Libraries or Applications
+3.2. External Libraries or Applications
The following libraries or applications must be installed before
running Kamailio with this module loaded:
* None
-3. Exported Parameters
+4. Exported Parameters
- 3.1. url_skip (str)
- 3.2. url_match (str)
+ 4.1. url_skip (str)
+ 4.2. url_match (str)
-3.1. url_skip (str)
+4.1. url_skip (str)
Regular expression to match the HTTP URL. If there is a match, then
event route is not executed.
@@ -103,7 +139,7 @@ Chapter 1. Admin Guide
modparam("xhttp", "url_skip", "^/RPC2")
...
-3.2. url_match (str)
+4.2. url_match (str)
Regular expression to match the HTTP URL. If there is no match, then
event route is not executed. This check is done after url_skip, so if
@@ -117,11 +153,11 @@ modparam("xhttp", "url_skip", "^/RPC2")
modparam("xhttp", "url_match", "^/sip/")
...
-4. Exported Functions
+5. Exported Functions
- 4.1. xhttp_reply(code, reason, ctype, body)
+ 5.1. xhttp_reply(code, reason, ctype, body)
-4.1. xhttp_reply(code, reason, ctype, body)
+5.1. xhttp_reply(code, reason, ctype, body)
Send back a reply with content-type and body.
diff --git a/modules/xhttp/doc/xhttp.xml b/modules/xhttp/doc/xhttp.xml
index b64dd0f..bc915e5 100644
--- a/modules/xhttp/doc/xhttp.xml
+++ b/modules/xhttp/doc/xhttp.xml
@@ -23,6 +23,11 @@
<surname>Mierla</surname>
<email>miconda at gmail.com</email>
</editor>
+ <editor>
+ <firstname>Alex</firstname>
+ <surname>Balashov</surname>
+ <email>abalashov at evaristesys.com</email>
+ </editor>
</authorgroup>
<copyright>
<year>2010</year>
diff --git a/modules/xhttp/doc/xhttp_admin.xml b/modules/xhttp/doc/xhttp_admin.xml
index 44f7ef0..0760a5b 100644
--- a/modules/xhttp/doc/xhttp_admin.xml
+++ b/modules/xhttp/doc/xhttp_admin.xml
@@ -29,6 +29,41 @@
of an HTTP URL is not compatible with that of a SIP URI.
</para>
</section>
+
+ <section>
+ <title>Note on Latency</title>
+ <para>
+ Because HTTP requests in <emphasis>xhttp</emphasis> are handled
+ by the same, finite number of SIP worker processes that operate on
+ SIP messages, the same general principles regarding script execution
+ speed and throughput should be observed by the writer in
+ <emphasis>event_route[xhttp:request]</emphasis> as in any other
+ part of the route script.
+ </para>
+ <para>
+ For example, if you initiate a database query in the HTTP request route
+ that takes a long time to return rows, the SIP worker process in which
+ the request is handled will be blocked for that time and unable to
+ process other SIP messages. In most typical installations, there are
+ only a few of these worker processes running.
+ </para>
+ <para>
+ Therefore, it is highly inadvisable to execute particularly slow things in the
+ <emphasis>event_route[xhttp:request]</emphasis>, because the request is not
+ handled in an asynchronous manner or otherwise peripherally to general
+ SIP processing. SIP worker threads will block, pending the outcome of the
+ event route just like any other config script route.
+ </para>
+ <para> This is no more or less true for <emphasis>xhttp</emphasis> than it is for
+ any other block of script in any other scenario, and does not warrant any
+ extraordinary concern. It nevertheless bears mention here because some
+ processes with embedded HTTP servers have the request processing take place
+ "outside" of the main synchronous event sequence, whether by creating
+ separate threads or by some other asynchronous handling. That is not the
+ case with <emphasis>xhttp</emphasis>.
+ </para>
+ </section>
+
<section>
<title>Dependencies</title>
<section>
More information about the sr-dev
mailing list