Browse code

dmq: regenerated readme

Charles Chance authored on 15/09/2013 22:38:45
Showing 1 changed files
... ...
@@ -2,11 +2,21 @@ Distributed Message Queue Module
2 2
 
3 3
 Marius Ovidiu Bucur
4 4
 
5
+Charles Chance
6
+
7
+   Sipcentric Ltd.
8
+
5 9
 Edited by
6 10
 
7 11
 Marius Ovidiu Bucur
8 12
 
9
-   Copyright � 2011 Marius Bucur
13
+Edited by
14
+
15
+Charles Chance
16
+
17
+   Copyright © 2011 Marius Bucur
18
+
19
+   Copyright © 2013 Charles Chance, Sipcentric Ltd.
10 20
      __________________________________________________________________
11 21
 
12 22
    Table of Contents
... ...
@@ -21,18 +31,38 @@ Marius Ovidiu Bucur
21 31
 
22 32
         3. Parameters
23 33
 
24
-              3.1. dmq_server_address(str)
25
-              3.2. dmq_notification_address(str)
34
+              3.1. server_address(str)
35
+              3.2. notification_address(str)
36
+              3.3. num_workers(int)
37
+              3.4. ping_interval(int)
38
+
39
+        4. Functions
40
+
41
+              4.1. dmq_handle_message()
42
+              4.2. dmq_send_message(peer, node, body)
26 43
 
27 44
    2. Developer Guide
28 45
 
29 46
         1. dmq_load_api(dmq_api_t* api)
47
+        2. register_dmq_peer(dmq_peer_t* peer)
48
+        3. bcast_message(dmq_peer_t* peer, str* body, dmq_node_t* except,
49
+                dmq_resp_cback_t* resp_cback, int max_forwards)
50
+
51
+        4. send_message(dmq_peer_t* peer, str* body, dmq_node_t* node,
52
+                dmq_resp_cback_t* resp_cback, int max_forwards)
30 53
 
31 54
    List of Examples
32 55
 
33
-   1.1. Set dmq_server_address parameter
34
-   1.2. Set dmq_notification_address parameter
56
+   1.1. Set server_address parameter
57
+   1.2. Set notification_address parameter
58
+   1.3. Set num_workers parameter
59
+   1.4. Set ping_interval parameter
60
+   1.5. dmq_handle_message usage
61
+   1.6. dmq_send_message usage
35 62
    2.1. dmq_api_t structure
63
+   2.2. register_dmq_peer usage
64
+   2.3. bcast_message usage
65
+   2.4. send_message usage
36 66
 
37 67
 Chapter 1. Admin Guide
38 68
 
... ...
@@ -46,17 +76,31 @@ Chapter 1. Admin Guide
46 76
 
47 77
    3. Parameters
48 78
 
49
-        3.1. dmq_server_address(str)
50
-        3.2. dmq_notification_address(str)
79
+        3.1. server_address(str)
80
+        3.2. notification_address(str)
81
+        3.3. num_workers(int)
82
+        3.4. ping_interval(int)
83
+
84
+   4. Functions
85
+
86
+        4.1. dmq_handle_message()
87
+        4.2. dmq_send_message(peer, node, body)
51 88
 
52 89
 1. Overview
53 90
 
54
-   The DMQ module implements a distributed message passing system on top
55
-   of Kamailio. The DMQ nodes within the system are grouped in a logical
56
-   entity called DMQ bus and are able to communicate with each others by
57
-   sending/receiving messages (either by broadcast or sending a DMQ
58
-   message to a specific node). The system transparently deals with node
59
-   discovery, node consistency within the DMQ bus, retransmissions, etc.
91
+   The DMQ module implements a distributed message queue on top of
92
+   Kamailio in order to enable the passing/replication of data between
93
+   multiple instances. The DMQ "nodes" within the system are grouped in a
94
+   logical entity called the DMQ "bus" and are able to communicate with
95
+   each other by sending/receiving messages (either by broadcast or
96
+   directly to a specific node). The system transparently deals with node
97
+   discovery, consistency, retransmissions, etc.
98
+
99
+   Other entities ("peers") are then able to utlize the DMQ bus to pass
100
+   messages between themselves. Peers are grouped by name in order to
101
+   ensure the correct messages are passed to the relevant peers. This
102
+   grouping of peers can be compared to a topic in a typical pub/sub
103
+   system.
60 104
 
61 105
 2. Dependencies
62 106
 
... ...
@@ -71,40 +115,99 @@ Chapter 1. Admin Guide
71 115
 
72 116
 2.2. External Libraries or Applications
73 117
 
74
-     * Each peer needs to use its own serialization mechanism. Some
118
+     * The DMQ module itself has no external dependencies. However, each
119
+       peer will need to use its own (de)serialization mechanism. Some
75 120
        examples are libtpl, protobuf. .
76 121
 
77 122
 3. Parameters
78 123
 
79
-   3.1. dmq_server_address(str)
80
-   3.2. dmq_notification_address(str)
124
+   3.1. server_address(str)
125
+   3.2. notification_address(str)
126
+   3.3. num_workers(int)
127
+   3.4. ping_interval(int)
128
+
129
+3.1. server_address(str)
130
+
131
+   The local server address. This is the interface over which the DMQ
132
+   engine will send/receive messages.
133
+
134
+   Default value is “NULL”.
135
+
136
+   Example 1.1. Set server_address parameter
137
+...
138
+modparam("dmq", "server_address", "sip:10.0.0.20:5060")
139
+...
140
+
141
+3.2. notification_address(str)
142
+
143
+   The address of another DMQ node from which the local node should
144
+   retrieve initial information about all other nodes.
145
+
146
+   Default value is “NULL”.
147
+
148
+   Example 1.2. Set notification_address parameter
149
+...
150
+modparam("dmq", "notification_address", "sip:10.0.0.21:5060")
151
+...
152
+
153
+3.3. num_workers(int)
154
+
155
+   The number of worker threads for sending/receiving messages.
156
+
157
+   Default value is “2”.
81 158
 
82
-3.1. dmq_server_address(str)
159
+   Example 1.3. Set num_workers parameter
160
+...
161
+modparam("dmq", "num_threads", 4)
162
+...
163
+
164
+3.4. ping_interval(int)
165
+
166
+   The number of seconds between node pings (for checking status of other
167
+   nodes).
168
+
169
+   Minimum value is “60” (default).
170
+
171
+   Example 1.4. Set ping_interval parameter
172
+...
173
+modparam("dmq", "ping_interval", 90)
174
+...
175
+
176
+4. Functions
83 177
 
84
-   The local server address.
178
+   4.1. dmq_handle_message()
179
+   4.2. dmq_send_message(peer, node, body)
85 180
 
86
-   The modules needs it to know on which interface the DMQ engine should
87
-   send and receive messages.
181
+4.1.  dmq_handle_message()
88 182
 
89
-   Default value is "NULL".
183
+   Handles a DMQ message by passing it to the appropriate local peer
184
+   (module). The peer is identified by the user part of the To header.
90 185
 
91
-   Example 1.1. Set dmq_server_address parameter
186
+   This function can be used from REQUEST_ROUTE.
187
+
188
+   Example 1.5. dmq_handle_message usage
92 189
 ...
93
-modparam("dmq", "dmq_server_address", "mysql://openser:openserrw@localhost/opens
94
-er")
190
+        if(is_method("KDMQ"))
191
+        {
192
+                dmq_handle_message();
193
+        }
95 194
 ...
96 195
 
97
-3.2. dmq_notification_address(str)
196
+4.2.  dmq_send_message(peer, node, body)
197
+
198
+   Sends a DMQ message directly from config file.
98 199
 
99
-   The address of the DMQ node from which the local node should retrieve
100
-   initial information.
200
+   Meaning of parameters:
201
+     * peer - name of peer that should handle the message.
202
+     * node - the node to which the message should be sent.
203
+     * body - the message body.
101 204
 
102
-   Default value is "NULL".
205
+   This function can be used from any route.
103 206
 
104
-   Example 1.2. Set dmq_notification_address parameter
207
+   Example 1.6. dmq_send_message usage
105 208
 ...
106
-modparam("dmq", "dmq_notification_address", "mysql://openser:openserrw@localhost
107
-/openser")
209
+        dmq_send_message("peer_name", "sip:10.0.0.21:5060", "Message body...\n")
210
+;
108 211
 ...
109 212
 
110 213
 Chapter 2. Developer Guide
... ...
@@ -112,18 +215,20 @@ Chapter 2. Developer Guide
112 215
    Table of Contents
113 216
 
114 217
    1. dmq_load_api(dmq_api_t* api)
218
+   2. register_dmq_peer(dmq_peer_t* peer)
219
+   3. bcast_message(dmq_peer_t* peer, str* body, dmq_node_t* except,
220
+          dmq_resp_cback_t* resp_cback, int max_forwards)
221
+
222
+   4. send_message(dmq_peer_t* peer, str* body, dmq_node_t* node,
223
+          dmq_resp_cback_t* resp_cback, int max_forwards)
115 224
 
116 225
    The module provides the following functions that can be used in other
117 226
    Kamailio modules.
118 227
 
119
-1. dmq_load_api(dmq_api_t* api)
228
+1.  dmq_load_api(dmq_api_t* api)
120 229
 
121
-   This function binds the dmq modules and fills the structure with the
122
-   exported functions -> register_dmq_peer - registers an entity as a DMQ
123
-   peer which permits receiving/sending messages between nodes which
124
-   support the same peer, -> bcast_message - broadcast a DMQ message to
125
-   all peers available in the DMQ bus, -> send_message - sends a DMQ
126
-   message to a specific peer in the local DMQ bus.
230
+   This function binds the DMQ module and fills the structure with the
231
+   exported functions below.
127 232
 
128 233
    Example 2.1. dmq_api_t structure
129 234
 ...
... ...
@@ -133,3 +238,34 @@ typedef struct dmq_api {
133 238
         send_message_t send_message;
134 239
 } dmq_api_t;
135 240
 ...
241
+
242
+2.  register_dmq_peer(dmq_peer_t* peer)
243
+
244
+   Registers an entity as a DMQ peer which permits receiving/sending
245
+   messages between nodes which support the same peer.
246
+
247
+   Example 2.2. register_dmq_peer usage
248
+...
249
+        Example to follow.
250
+...
251
+
252
+3.  bcast_message(dmq_peer_t* peer, str* body, dmq_node_t* except,
253
+dmq_resp_cback_t* resp_cback, int max_forwards)
254
+
255
+   Broadcast a DMQ message to all nodes in the DMQ bus excluding self,
256
+   inactive nodes and "except" if specified.
257
+
258
+   Example 2.3. bcast_message usage
259
+...
260
+        Example to follow.
261
+...
262
+
263
+4.  send_message(dmq_peer_t* peer, str* body, dmq_node_t* node,
264
+dmq_resp_cback_t* resp_cback, int max_forwards)
265
+
266
+   Send a DMQ message to a single node.
267
+
268
+   Example 2.4. send_message usage
269
+...
270
+        Example to follow.
271
+...