New subject: git:master: mqueue: Add new psuedo-variable to return mqueue size

30 Jan 2014

Module: sip-router
Branch: master
Commit: 40ea6ffd76cf32aafc594038d17555edbc816b50
URL:    http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=40ea6ffd...
Author: Hugh Waite hugh.waite@crocodile-rcs.com
Committer: Hugh Waite hugh.waite@crocodile-rcs.com
Date:   Thu Jan 30 21:58:43 2014 +0000
mqueue: Add new psuedo-variable to return mqueue size
- Using PV will return a value when the length is zero
---
modules/mqueue/README               |   78 +++++++++++++++++++++--------------
 modules/mqueue/doc/mqueue_admin.xml |   30 +++++++++++---
 modules/mqueue/mqueue_api.c         |   25 +++++++++++
 modules/mqueue/mqueue_api.h         |    2 +
 modules/mqueue/mqueue_mod.c         |    2 +
 5 files changed, 100 insertions(+), 37 deletions(-)

diff --git a/modules/mqueue/README b/modules/mqueue/README
index 8d41f8a..b58607c 100644
--- a/modules/mqueue/README
+++ b/modules/mqueue/README
@@ -1,3 +1,4 @@
+
 mqueue Module
Elena-Ramona Modroiu
@@ -18,7 +19,7 @@ Alex Balashov
    abalashov@evaristesys.com
Copyright � 2010 Elena-Ramona Modroiu (asipto.com)
-     __________________________________________________________________
+     _________________________________________________________________
Table of Contents
@@ -36,10 +37,12 @@ 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
List of Examples
@@ -65,20 +68,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
@@ -93,7 +98,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.
@@ -105,15 +110,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
 ...
@@ -123,14 +128,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)
-   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
@@ -140,10 +145,10 @@ mq_add("myq", "$rU", "call from $fU");
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
@@ -173,3 +178,14 @@ mq_pv_free("myq");
 $var(q_size) = mq_size("queue");
 xlog("L_INFO", "Size of queue is: $var(q_size)\n");
 ...
+
+5. Exported Pseudo-variables
+
+     * $mqv(mqueue) - the most recent item key fetched from the specified
+       mqueue
+     * $mqv(mqueue)  -  the  most  recent  item  value  fetched  from the
+       specified mqueue
+     * $mq_size(mqueue) - the size of the specified mqueue
+
+   Exported pseudo-variables are documented at
+   http://www.kamailio.org/wiki/.
diff --git a/modules/mqueue/doc/mqueue_admin.xml b/modules/mqueue/doc/mqueue_admin.xml
index a444cc4..1aee029 100644
--- a/modules/mqueue/doc/mqueue_admin.xml
+++ b/modules/mqueue/doc/mqueue_admin.xml
@@ -61,7 +61,7 @@
     <section>
    <title>Parameters</title>
-	<section>
+	<section id="mqueue.p.mqueue">
        <title><varname>mqueue</varname> (string)</title>
        <para>
    	Definition of a memory queue
@@ -96,7 +96,7 @@ modparam("mqueue", "mqueue", "name=qaz")
    
     <section>
    <title>Functions</title>
- 	<section>
+ 	<section id="mqueue.f.mq_add">
        <title>
    	<function moreinfo="none">mq_add(queue, key, value)</function>
        </title>
@@ -114,7 +114,7 @@ mq_add("myq", "$rU", "call from $fU");
        </example>
    </section>
    
- 	<section>
+ 	<section id="mqueue.f.mq_fetch">
        <title>
    	<function moreinfo="none">mq_fetch(queue)</function>
        </title>
@@ -139,7 +139,7 @@ while(mq_fetch("myq"))
        </example>
    </section>
    
- 	<section>
+ 	<section id="mqueue.f.mq_pv_free">
        <title>
    	<function moreinfo="none">mq_pv_free(queue)</function>
        </title>
@@ -157,7 +157,7 @@ mq_pv_free("myq");
        </example>
    </section>
-	<section>
+	<section id="mqueue.f.mq_size">
        <title>
    	<function moreinfo="none">mq_size(queue)</function>
        </title>
@@ -176,6 +176,24 @@ xlog("L_INFO", "Size of queue is: $var(q_size)\n");
    </section>
    
     </section>
-	
+
+    <section>
+	<title>Exported Pseudo-variables</title>
+		<itemizedlist>
+			<listitem>
+				<emphasis>$mqv(mqueue)</emphasis> - the most recent item key fetched from the specified mqueue
+			</listitem>
+			<listitem>
+				<emphasis>$mqv(mqueue)</emphasis> - the most recent item value fetched from the specified mqueue
+			</listitem>
+			<listitem>
+				<emphasis>$mq_size(mqueue)</emphasis> - the size of the specified mqueue
+			</listitem>
+		</itemizedlist>
+		<para>
+		Exported pseudo-variables are documented at &kamwikilink;.
+		</para>
+    </section>
+
 </chapter>
diff --git a/modules/mqueue/mqueue_api.c b/modules/mqueue/mqueue_api.c
index 4a36909..e060991 100644
--- a/modules/mqueue/mqueue_api.c
+++ b/modules/mqueue/mqueue_api.c
@@ -456,6 +456,31 @@ int pv_get_mqv(struct sip_msg *msg, pv_param_t *param,
    return pv_get_strval(msg, param, res, &mp->item->val);
 }
+/**
+ *
+ */
+int pv_get_mq_size(struct sip_msg *msg, pv_param_t *param,
+		pv_value_t *res)
+{
+	int mqs = -1;
+	str *in = pv_get_mq_name(msg, &param->pvn.u.isname.name.s);
+
+	if (in == NULL)
+	{
+		LM_ERR("failed to get mq name\n");
+		return -1;
+	}
+
+	mqs = _mq_get_csize(in);
+
+	if (mqs < 0)
+	{
+		LM_ERR("mqueue not found: %.*s\n", in->len, in->s);
+		return -1;
+	}
+
+	return pv_get_sintval(msg, param, res, mqs);
+}
 /* Return head->csize for a given queue */
int _mq_get_csize(str *name) 
diff --git a/modules/mqueue/mqueue_api.h b/modules/mqueue/mqueue_api.h
index cb695f1..1c69c69 100644
--- a/modules/mqueue/mqueue_api.h
+++ b/modules/mqueue/mqueue_api.h
@@ -33,6 +33,8 @@ int pv_get_mqk(struct sip_msg *msg, pv_param_t *param,
    	pv_value_t *res);
 int pv_get_mqv(struct sip_msg *msg, pv_param_t *param,
    	pv_value_t *res);
+int pv_get_mq_size(struct sip_msg *msg, pv_param_t *param,
+		pv_value_t *res);
int mq_head_defined(void);
 void mq_destroy(void);
diff --git a/modules/mqueue/mqueue_mod.c b/modules/mqueue/mqueue_mod.c
index 3eacf02..2115630 100644
--- a/modules/mqueue/mqueue_mod.c
+++ b/modules/mqueue/mqueue_mod.c
@@ -59,6 +59,8 @@ static pv_export_t mod_pvs[] = {
    	pv_parse_mq_name, 0, 0, 0 },
    { {"mqv", sizeof("mqv")-1}, PVT_OTHER, pv_get_mqv, 0,
    	pv_parse_mq_name, 0, 0, 0 },
+	{ {"mq_size", sizeof("mq_size")-1}, PVT_OTHER, pv_get_mq_size, 0,
+		pv_parse_mq_name, 0, 0, 0 },
    { {0, 0}, 0, 0, 0, 0, 0, 0, 0 }
 };

    