mqueue: Add new psuedo-variable to return mqueue size

- Using PV will return a value when the length is zero

modules/mqueue/README

@@ -1,3 +1,4 @@
+
 mqueue Module
 
 Elena-Ramona Modroiu
@@ -18,7 +19,7 @@ Alex Balashov
    <[email protected]>
 
    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/.

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>
 

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) 

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);

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 }
 };