[sr-dev] git:master: mqueue: elaborated the docs for mq_size() to reflect return codes
Daniel-Constantin Mierla
miconda at gmail.com
Wed Nov 5 14:06:59 CET 2014
Module: sip-router
Branch: master
Commit: cf9303b8063e77426e0506bed09577fe7a584fb1
URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=cf9303b8063e77426e0506bed09577fe7a584fb1
Author: Daniel-Constantin Mierla <miconda at gmail.com>
Committer: Daniel-Constantin Mierla <miconda at gmail.com>
Date: Wed Nov 5 14:04:33 2014 +0100
mqueue: elaborated the docs for mq_size() to reflect return codes
---
modules/mqueue/README | 76 ++++++++++++++++++-----------------
modules/mqueue/doc/mqueue_admin.xml | 4 ++
2 files changed, 43 insertions(+), 37 deletions(-)
diff --git a/modules/mqueue/README b/modules/mqueue/README
index b58607c..952e900 100644
--- a/modules/mqueue/README
+++ b/modules/mqueue/README
@@ -1,4 +1,3 @@
-
mqueue Module
Elena-Ramona Modroiu
@@ -19,7 +18,7 @@ Alex Balashov
<abalashov at evaristesys.com>
Copyright © 2010 Elena-Ramona Modroiu (asipto.com)
- _________________________________________________________________
+ __________________________________________________________________
Table of Contents
@@ -37,10 +36,10 @@ Alex Balashov
4. Functions
- 4.1. mq_add(queue, key, value)
- 4.2. mq_fetch(queue)
- 4.3. mq_pv_free(queue)
- 4.4. mq_size(queue)
+ 4.1. mq_add(queue, key, value)
+ 4.2. mq_fetch(queue)
+ 4.3. mq_pv_free(queue)
+ 4.4. mq_size(queue)
5. Exported Pseudo-variables
@@ -68,22 +67,22 @@ Chapter 1. Admin Guide
4. Functions
- 4.1. mq_add(queue, key, value)
- 4.2. mq_fetch(queue)
- 4.3. mq_pv_free(queue)
- 4.4. mq_size(queue)
+ 4.1. mq_add(queue, key, value)
+ 4.2. mq_fetch(queue)
+ 4.3. mq_pv_free(queue)
+ 4.4. mq_size(queue)
5. Exported Pseudo-variables
1. Overview
- The mqueue module offers a generic message queue system in shared
- memory for inter-process communication using the config file. One
- example of usage is to send time consuming operations to one or
- several timer processes that consumes items in the queue, without
- affecting SIP message handling in the socket-listening process.
+ The mqueue module offers a generic message queue system in shared
+ memory for inter-process communication using the config file. One
+ example of usage is to send time consuming operations to one or several
+ timer processes that consumes items in the queue, without affecting SIP
+ message handling in the socket-listening process.
- There can be many defined queues. Access to queued values is done via
+ There can be many defined queues. Access to queued values is done via
pseudo variables.
2. Dependencies
@@ -98,7 +97,7 @@ Chapter 1. Admin Guide
2.2. External Libraries or Applications
- The following libraries or applications must be installed before
+ The following libraries or applications must be installed before
running Kamailio with this module loaded:
* None.
@@ -110,15 +109,15 @@ Chapter 1. Admin Guide
Definition of a memory queue
- Default value is "none".
+ Default value is "none".
- Value must be a list of parameters: attr=value;... The attribute
- 'name' is mandatory, defining the name of the queue. Optional
- attribute 'size' specifies the maximum number of items in queue, if it
- is execeeded the oldest one is removed.
+ Value must be a list of parameters: attr=value;... The attribute 'name'
+ is mandatory, defining the name of the queue. Optional attribute 'size'
+ specifies the maximum number of items in queue, if it is execeeded the
+ oldest one is removed.
- The parameter can be set many times, each holding the definition of
- one queue.
+ The parameter can be set many times, each holding the definition of one
+ queue.
Example 1.1. Set mqueue parameter
...
@@ -128,14 +127,14 @@ modparam("mqueue", "mqueue", "name=qaz")
4. Functions
- 4.1. mq_add(queue, key, value)
- 4.2. mq_fetch(queue)
- 4.3. mq_pv_free(queue)
- 4.4. mq_size(queue)
+ 4.1. mq_add(queue, key, value)
+ 4.2. mq_fetch(queue)
+ 4.3. mq_pv_free(queue)
+ 4.4. mq_size(queue)
-4.1. mq_add(queue, key, value)
+4.1. mq_add(queue, key, value)
- Add a new item (key, value) in the queue. If max size of queue is
+ Add a new item (key, value) in the queue. If max size of queue is
exceeded, the oldest one is removed.
Example 1.2. mq_add usage
@@ -143,12 +142,12 @@ modparam("mqueue", "mqueue", "name=qaz")
mq_add("myq", "$rU", "call from $fU");
...
-4.2. mq_fetch(queue)
+4.2. mq_fetch(queue)
- Take oldest item from queue and fill $mqk(queue) and $mqv(queue)
- pseudo variables.
+ Take oldest item from queue and fill $mqk(queue) and $mqv(queue) pseudo
+ variables.
- Return: true on success (1); false on failure (-1) or no item fetched
+ Return: true on success (1); false on failure (-1) or no item fetched
(-2).
Example 1.3. mq_fetch usage
@@ -159,7 +158,7 @@ while(mq_fetch("myq"))
}
...
-4.3. mq_pv_free(queue)
+4.3. mq_pv_free(queue)
Free the item fetched in pseudo-variables. It is optional, a new fetch
frees the previous values.
@@ -169,10 +168,13 @@ while(mq_fetch("myq"))
mq_pv_free("myq");
...
-4.4. mq_size(queue)
+4.4. mq_size(queue)
Returns the current number of elements in the mqueue.
+ If the mqueue is empty, the function returns -1. If the mqueue is not
+ found, the function returns -2.
+
Example 1.5. mq_size usage
...
$var(q_size) = mq_size("queue");
@@ -183,7 +185,7 @@ xlog("L_INFO", "Size of queue is: $var(q_size)\n");
* $mqv(mqueue) - the most recent item key fetched from the specified
mqueue
- * $mqv(mqueue) - the most recent item value fetched from the
+ * $mqv(mqueue) - the most recent item value fetched from the
specified mqueue
* $mq_size(mqueue) - the size of the specified mqueue
diff --git a/modules/mqueue/doc/mqueue_admin.xml b/modules/mqueue/doc/mqueue_admin.xml
index 1aee029..2e9c3e8 100644
--- a/modules/mqueue/doc/mqueue_admin.xml
+++ b/modules/mqueue/doc/mqueue_admin.xml
@@ -164,6 +164,10 @@ mq_pv_free("myq");
<para>
Returns the current number of elements in the mqueue.
</para>
+ <para>
+ If the mqueue is empty, the function returns -1. If the
+ mqueue is not found, the function returns -2.
+ </para>
<example>
<title><function>mq_size</function> usage</title>
<programlisting format="linespecific">
More information about the sr-dev
mailing list