[sr-dev] git:4.2: mqueue: elaborated the docs for mq_size() to reflect return codes

Module: sip-router Branch: 4.2 Commit: bcfd43b42eb8115d7698201250a15f5ddd82b4c9 URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=bcfd43b… Author: Daniel-Constantin Mierla &lt;miconda(a)gmail.com&gt; Committer: Daniel-Constantin Mierla &lt;miconda(a)gmail.com&gt; 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 &lt;abalashov(a)evaristesys.com&gt; 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">