Module: sip-router Branch: 4.2 Commit: bcfd43b42eb8115d7698201250a15f5ddd82b4c9 URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=bcfd43b4...
Author: Daniel-Constantin Mierla miconda@gmail.com Committer: Daniel-Constantin Mierla miconda@gmail.com Date: Wed Nov 5 14:04:33 2014 +0100
mqueue: elaborated the docs for mq_size() to reflect return codes
(cherry picked from commit cf9303b8063e77426e0506bed09577fe7a584fb1)
---
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@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">