mqueue Module
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview
        1.2. Dependencies

              1.2.1. OpenSIPS Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters

              1.3.1. db_url (str)
              1.3.2. mqueue (string)

        1.4. Exported Functions

              1.4.1. mq_add(queue, key, value)
              1.4.2. mq_fetch(queue)
              1.4.3. mq_pv_free(queue)
              1.4.4. mq_size(queue)

        1.5. Exported MI Functions

              1.5.1. mq_get_size
              1.5.2. mq_fetch
              1.5.3. mq_get_sizes

        1.6. Exported Pseudo-Variables

              1.6.1. $mqk(mqueue)
              1.6.2. $mqv(mqueue)
              1.6.3. $mq_size(mqueue)

   2. Contributors

        2.1. By Commit Statistics
        2.2. By Commit Activity

   3. Documentation

        3.1. Contributors

   List of Tables

   2.1. Top contributors by DevScore^(1), authored commits^(2) and
          lines added/removed^(3)

   2.2. Most recently active contributors^(1) to this module

   List of Examples

   1.1. Set db_url parameter
   1.2. Set mqueue parameter
   1.3. mq_add usage
   1.4. mq_fetch usage
   1.5. mq_pv_free usage
   1.6. mq_size usage
   1.7. mq_get_size usage
   1.8. mq_fetch usage
   1.9. mq_get_sizes usage

Chapter 1. Admin Guide

1.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.

   There can be many defined queues. Access to queued values is
   done via pseudo variables.

1.2. Dependencies

1.2.1. OpenSIPS Modules

   The following modules must be loaded before this module:
     * None.

1.2.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSIPS with this module loaded:
     * None.

1.3. Exported Parameters

1.3.1. db_url (str)

   The URL to connect to database for loading values in mqueue
   table at start up and/or saving values at shutdown.

   Default value is NULL (do not connect).

   Example 1.1. Set db_url parameter
...
modparam("mqueue", "db_url", "mysql://opensips:opensipsrw@localhost/open
sips")

# Example of table in sqlite,
# you have the set the fields to support the length according
# to the data that will be present in the mqueue
CREATE TABLE mqueue_name (
id INTEGER PRIMARY KEY AUTOINCREMENT,
key character varying(64) DEFAULT "" NOT NULL,
val character varying(4096) DEFAULT "" NOT NULL
);
...

1.3.2. mqueue (string)

   Definition of a memory queue

   Default value is “none”.

   Value must be a list of parameters: attr=value;...
     * Mandatory attributes:
          + name: name of the queue.
     * Optional attributes:
          + size: size of the queue. Specifies the maximum number
            of items in queue. If exceeded the oldest one is
            removed. If not set the queue will be limitless.
          + dbmode: If set to 1, the content of the queue is
            written to database table when the SIP server is
            stopped (i.e., ensure persistency over restarts). If
            set to 2, it is written at shutdown but not read at
            startup. If set to 3, it is read at sartup but not
            written at shutdown. Default value is 0 (no db table
            interaction).
          + addmode: how to add new (key,value) pairs.
               o 0: Will push all new (key,value) pairs at the end
                 of the queue. (default)
               o 1: Will keep oldest (key,value) pair in the
                 queue, based on the key.
               o 2: Will keep newest (key,value) pair in the
                 queue, based on the key.

   The parameter can be set many times, each holding the
   definition of one queue.

   Example 1.2. Set mqueue parameter
...
modparam("mqueue", "mqueue", "name=myq;size=20;")
modparam("mqueue", "mqueue", "name=myq;size=10000;addmode=2")
modparam("mqueue", "mqueue", "name=qaz")
modparam("mqueue", "mqueue", "name=qaz;addmode=1")
...

1.4. Exported Functions

1.4.1.  mq_add(queue, key, value)

   Add a new item (key, value) in the queue. If max size of queue
   is exceeded, the oldest one is removed.

   Example 1.3. mq_add usage
...
mq_add("myq", "$rU", "call from $fU");
...

1.4.2.  mq_fetch(queue)

   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 (-2).

   Example 1.4. mq_fetch usage
...
while(mq_fetch("myq"))
{
        xlog("$mqk(myq) - $mqv(myq)\n");
}
...

1.4.3.  mq_pv_free(queue)

   Free the item fetched in pseudo-variables. It is optional, a
   new fetch frees the previous values.

   Example 1.5. mq_pv_free usage
...
mq_pv_free("myq");
...

1.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.6. mq_size usage
...
$var(q_size) = mq_size("queue");
xlog("L_INFO", "Size of queue is: $var(q_size)\n");
...

1.5. Exported MI Functions

1.5.1. mq_get_size

   Get the size of a memory queue.

   Parameters:
     * name - the name of memory queue

   Example 1.7. mq_get_size usage
...
opensips-cli -x mq_get_size xyz
...

1.5.2. mq_fetch

   Fetch a key-value pair from a memory queue.

   Parameters:
     * name - the name of memory queue

   Example 1.8. mq_fetch usage
...
opensips-cli -x mq_fetch xyz
...

1.5.3. mq_get_sizes

   Get the size for all memory queues.

   Parameters: none

   Example 1.9. mq_get_sizes usage
...
opensips-cli -x mq_get_sizes
...

1.6. Exported Pseudo-Variables

1.6.1. $mqk(mqueue)

   The variable is read-only and returns the most recent item key
   fetched from the specified mqueue.

1.6.2. $mqv(mqueue)

   The variable is read-only and returns the most recent item
   value fetched from the specified mqueue.

1.6.3. $mq_size(mqueue)

   The variable is read-only and returns the size of the specified
   mqueue.

Chapter 2. Contributors

2.1. By Commit Statistics

   Table 2.1. Top contributors by DevScore^(1), authored
   commits^(2) and lines added/removed^(3)
               Name           DevScore Commits Lines ++ Lines --
   1. Ovidiu Sas (@ovidiusas)    19       2      1843      34

   (1) DevScore = author_commits + author_lines_added /
   (project_lines_added / project_commits) + author_lines_deleted
   / (project_lines_deleted / project_commits)

   (2) including any documentation-related commits, excluding
   merge commits. Regarding imported patches/code, we do our best
   to count the work on behalf of the proper owner, as per the
   "fix_authors" and "mod_renames" arrays in
   opensips/doc/build-contrib.sh. If you identify any
   patches/commits which do not get properly attributed to you,
   please submit a pull request which extends "fix_authors" and/or
   "mod_renames".

   (3) ignoring whitespace edits, renamed files and auto-generated
   files

2.2. By Commit Activity

   Table 2.2. Most recently active contributors^(1) to this module
               Name             Commit Activity
   1. Ovidiu Sas (@ovidiusas) Feb 2024 - Feb 2024

   (1) including any documentation-related commits, excluding
   merge commits

Chapter 3. Documentation

3.1. Contributors

   Last edited by: Ovidiu Sas (@ovidiusas).

   Documentation Copyrights:

   Copyright © 2010 Elena-Ramona Modroiu

   Copyright © 2018-2020 Julien chavanton, Flowroute

   Copyright © 2024 Ovidiu Sas, VoIP Embedded, Inc.
