modules: readme files regenerated - http_client ... [skip ci]
[sip-router] / src / modules / mqueue / README
1 mqueue Module
2
3 Elena-Ramona Modroiu
4
5    asipto.com
6
7 Edited by
8
9 Elena-Ramona Modroiu
10
11    <ramona@asipto.com>
12
13 Edited by
14
15 Alex Balashov
16
17    Evariste Systems
18    <abalashov@evaristesys.com>
19
20 Edited by
21
22 Ovidiu Sas
23
24    VoIP Embedded, Inc.
25    <osas@voipembedded.com>
26
27 Edited by
28
29 Julien Chavanton
30
31    <jchavanton@gmail.com>
32
33    Copyright © 2010 Elena-Ramona Modroiu (asipto.com)
34
35    Copyright © 2018 Julien chavanton, Flowroute
36      __________________________________________________________________
37
38    Table of Contents
39
40    1. Admin Guide
41
42         1. Overview
43         2. Dependencies
44
45               2.1. Kamailio Modules
46               2.2. External Libraries or Applications
47
48         3. Parameters
49
50               3.1. mqueue (string)
51
52         4. Functions
53
54               4.1. mq_add(queue, key, value)
55               4.2. mq_fetch(queue)
56               4.3. mq_pv_free(queue)
57               4.4. mq_size(queue)
58
59         5. Exported Variables
60         6. RPC Commands
61
62               6.1. mqueue.get_size
63               6.2. mqueue.fetch
64
65    List of Examples
66
67    1.1. Set mqueue parameter
68    1.2. mq_add usage
69    1.3. mq_fetch usage
70    1.4. mq_pv_free usage
71    1.5. mq_size usage
72    1.6. mqueue.get_size usage
73    1.7. mqueue.fetch usage
74
75 Chapter 1. Admin Guide
76
77    Table of Contents
78
79    1. Overview
80    2. Dependencies
81
82         2.1. Kamailio Modules
83         2.2. External Libraries or Applications
84
85    3. Parameters
86
87         3.1. mqueue (string)
88
89    4. Functions
90
91         4.1. mq_add(queue, key, value)
92         4.2. mq_fetch(queue)
93         4.3. mq_pv_free(queue)
94         4.4. mq_size(queue)
95
96    5. Exported Variables
97    6. RPC Commands
98
99         6.1. mqueue.get_size
100         6.2. mqueue.fetch
101
102 1. Overview
103
104    The mqueue module offers a generic message queue system in shared
105    memory for inter-process communication using the config file. One
106    example of usage is to send time consuming operations to one or several
107    timer processes that consumes items in the queue, without affecting SIP
108    message handling in the socket-listening process.
109
110    There can be many defined queues. Access to queued values is done via
111    pseudo variables.
112
113 2. Dependencies
114
115    2.1. Kamailio Modules
116    2.2. External Libraries or Applications
117
118 2.1. Kamailio Modules
119
120    The following modules must be loaded before this module:
121      * None.
122
123 2.2. External Libraries or Applications
124
125    The following libraries or applications must be installed before
126    running Kamailio with this module loaded:
127      * None.
128
129 3. Parameters
130
131    3.1. mqueue (string)
132
133 3.1. mqueue (string)
134
135    Definition of a memory queue
136
137    Default value is “none”.
138
139    Value must be a list of parameters: attr=value;...
140      * Mandatory attributes:
141           + name: name of the queue.
142      * Optional attributes:
143           + size: size of the queue. Specifies the maximum number of items
144             in queue. If exceeded the oldest one is removed. If not set
145             the queue will be limitless.
146
147    The parameter can be set many times, each holding the definition of one
148    queue.
149
150    Example 1.1. Set mqueue parameter
151 ...
152 modparam("mqueue", "mqueue", "name=myq;size=20;")
153 modparam("mqueue", "mqueue", "name=qaz")
154 ...
155
156 4. Functions
157
158    4.1. mq_add(queue, key, value)
159    4.2. mq_fetch(queue)
160    4.3. mq_pv_free(queue)
161    4.4. mq_size(queue)
162
163 4.1.  mq_add(queue, key, value)
164
165    Add a new item (key, value) in the queue. If max size of queue is
166    exceeded, the oldest one is removed.
167
168    Example 1.2. mq_add usage
169 ...
170 mq_add("myq", "$rU", "call from $fU");
171 ...
172
173 4.2.  mq_fetch(queue)
174
175    Take oldest item from queue and fill $mqk(queue) and $mqv(queue) pseudo
176    variables.
177
178    Return: true on success (1); false on failure (-1) or no item fetched
179    (-2).
180
181    Example 1.3. mq_fetch usage
182 ...
183 while(mq_fetch("myq"))
184 {
185    xlog("$mqk(myq) - $mqv(myq)\n");
186 }
187 ...
188
189 4.3.  mq_pv_free(queue)
190
191    Free the item fetched in pseudo-variables. It is optional, a new fetch
192    frees the previous values.
193
194    Example 1.4. mq_pv_free usage
195 ...
196 mq_pv_free("myq");
197 ...
198
199 4.4.  mq_size(queue)
200
201    Returns the current number of elements in the mqueue.
202
203    If the mqueue is empty, the function returns -1. If the mqueue is not
204    found, the function returns -2.
205
206    Example 1.5. mq_size usage
207 ...
208 $var(q_size) = mq_size("queue");
209 xlog("L_INFO", "Size of queue is: $var(q_size)\n");
210 ...
211
212 5. Exported Variables
213
214      * $mqk(mqueue) - the most recent item key fetched from the specified
215        mqueue
216      * $mqv(mqueue) - the most recent item value fetched from the
217        specified mqueue
218      * $mq_size(mqueue) - the size of the specified mqueue
219
220    Exported pseudo-variables are documented at
221    https://www.kamailio.org/wiki/.
222
223 6. RPC Commands
224
225    6.1. mqueue.get_size
226    6.2. mqueue.fetch
227
228 6.1. mqueue.get_size
229
230    Get the size of a memory queue.
231
232    Parameters:
233      * name - the name of memory queue
234
235    Example 1.6. mqueue.get_size usage
236 ...
237 kamcmd mqueue.get_size xyz
238 ...
239
240 6.2. mqueue.fetch
241
242    Fetch a key-value pair from a memory queue.
243
244    Parameters:
245      * name - the name of memory queue
246
247    Example 1.7. mqueue.fetch usage
248 ...
249 kamcmd mqueue.fetch xyz
250 ...