Browse code

dmq: updated documentation

Charles Chance authored on 15/09/2013 22:38:30
Showing 3 changed files
... ...
@@ -21,18 +21,31 @@
21 21
 		<email>bucur_marius_ovidiu@yahoo.com</email>
22 22
 		</address>
23 23
 	    </author>
24
-	    <editor>
25
-		<firstname>Marius Ovidiu</firstname>
26
-		<surname>Bucur</surname>
27
-		<address>
28
-		    <email>bucur_marius_ovidiu@yahoo.com</email>
29
-		</address>
30
-	    </editor>
24
+            <author>
25
+                <firstname>Charles</firstname>
26
+                <surname>Chance</surname>
27
+		<affiliation>Sipcentric Ltd.</affiliation>
28
+            </author>
29
+            <editor>
30
+                <firstname>Marius Ovidiu</firstname>
31
+                <surname>Bucur</surname>
32
+                <address>
33
+                <email>bucur_marius_ovidiu@yahoo.com</email>
34
+                </address>
35
+            </editor>
36
+            <editor>
37
+                <firstname>Charles</firstname>
38
+                <surname>Chance</surname>
39
+            </editor>
31 40
 	</authorgroup>
32 41
 	<copyright>
33 42
 	    <year>2011</year>
34 43
 	    <holder>Marius Bucur</holder>
35 44
 	</copyright>
45
+        <copyright>
46
+            <year>2013</year>
47
+            <holder>Charles Chance, Sipcentric Ltd.</holder>
48
+        </copyright>
36 49
   </bookinfo>
37 50
     <toc></toc>
38 51
     
... ...
@@ -14,12 +14,17 @@
14 14
 	
15 15
 	<section>
16 16
 	<title>Overview</title>
17
-	<para> The DMQ module implements a distributed message passing system on top of Kamailio.
18
-	The DMQ nodes within the system are grouped in a logical entity called DMQ bus and are able to
19
-	communicate with each others by sending/receiving messages (either by broadcast or sending a DMQ
20
-	message to a specific node).
21
-	The system transparently deals with node discovery, node consistency within the DMQ bus, retransmissions,
22
-	etc.
17
+	<para>
18
+	The DMQ module implements a distributed message queue on top of Kamailio in order to enable the 
19
+	passing/replication of data between multiple instances. The DMQ "nodes" within the system are grouped 
20
+	in a logical entity called the DMQ "bus" and are able to communicate with each other by 
21
+	sending/receiving messages (either by broadcast or directly to a specific node). The system 
22
+	transparently deals with node discovery, consistency, retransmissions, etc.
23
+	</para>
24
+	<para>
25
+	Other entities ("peers") are then able to utlize the DMQ bus to pass messages between themselves. 
26
+	Peers are grouped by name in order to ensure the correct messages are passed to the relevant peers. 
27
+	This grouping of peers can be compared to a topic in a typical pub/sub system.
23 28
 	</para>
24 29
 	
25 30
 	</section>
... ...
@@ -51,8 +56,8 @@
51 56
 			<listitem>
52 57
 			<para>
53 58
 				<emphasis>
54
-				Each peer needs to use its own serialization mechanism.
55
-				Some examples are libtpl, protobuf.
59
+				The DMQ module itself has no external dependencies. However, each peer will need 
60
+				to use its own (de)serialization mechanism. Some examples are libtpl, protobuf.
56 61
 				</emphasis>.
57 62
 			</para>
58 63
 			</listitem>
... ...
@@ -63,44 +68,140 @@
63 68
 	<section>
64 69
 	<title>Parameters</title>
65 70
 	<section>
66
-		<title><varname>dmq_server_address</varname>(str)</title>
67
-		<para>
68
-		The local server address.
69
-		</para>
71
+		<title><varname>server_address</varname>(str)</title>
70 72
 		<para>
71
-		The modules needs it to know on which interface the DMQ engine should send and receive messages.
73
+		The local server address. This is the interface over which the DMQ engine will send/receive messages.
72 74
 		</para>
73 75
 		<para>
74
-		<emphasis>Default value is <quote>NULL</quote>.	
75
-		</emphasis>
76
+		<emphasis>Default value is <quote>NULL</quote>.</emphasis>
76 77
 		</para>
77 78
 		<example>
78
-		<title>Set <varname>dmq_server_address</varname> parameter</title>
79
+		<title>Set <varname>server_address</varname> parameter</title>
79 80
 		<programlisting format="linespecific">
80 81
 ...
81
-modparam("dmq", "dmq_server_address", "&defaultdb;")
82
+modparam("dmq", "server_address", "sip:10.0.0.20:5060")
82 83
 ...
83 84
 </programlisting>
84 85
 		</example>
85 86
 	</section>
86 87
 	<section>
87
-		<title><varname>dmq_notification_address</varname>(str)</title>
88
+		<title><varname>notification_address</varname>(str)</title>
88 89
 		<para>
89
-		The address of the DMQ node from which the local node should retrieve initial information.
90
+		The address of another DMQ node from which the local node should retrieve initial information about all other nodes.
90 91
 		</para>
91 92
 		<para>
92
-		<emphasis>	Default value is <quote>NULL</quote>.
93
-		</emphasis>
93
+		<emphasis>Default value is <quote>NULL</quote>.</emphasis>
94 94
 		</para>
95 95
 		<example>
96
-		<title>Set <varname>dmq_notification_address</varname> parameter</title>
96
+		<title>Set <varname>notification_address</varname> parameter</title>
97 97
 		<programlisting format="linespecific">
98 98
 ...
99
-modparam("dmq", "dmq_notification_address", "&defaultdb;")
99
+modparam("dmq", "notification_address", "sip:10.0.0.21:5060")
100 100
 ...
101 101
 </programlisting>
102 102
 		</example>
103 103
 	</section>
104
+        <section>
105
+                <title><varname>num_workers</varname>(int)</title>
106
+                <para>
107
+                The number of worker threads for sending/receiving messages.
108
+                </para>
109
+                <para>
110
+                <emphasis>Default value is <quote>2</quote>.</emphasis>
111
+                </para>
112
+                <example>
113
+                <title>Set <varname>num_workers</varname> parameter</title>
114
+                <programlisting format="linespecific">
115
+...
116
+modparam("dmq", "num_threads", 4)
117
+...
118
+</programlisting>
119
+                </example>
120
+        </section>
121
+        <section>
122
+                <title><varname>ping_interval</varname>(int)</title>
123
+                <para>
124
+                The number of seconds between node pings (for checking status of other nodes).
125
+                </para>
126
+                <para>
127
+                <emphasis>Minimum value is <quote>60</quote> (default).</emphasis>
128
+                </para>
129
+                <example>
130
+                <title>Set <varname>ping_interval</varname> parameter</title>
131
+                <programlisting format="linespecific">
132
+...
133
+modparam("dmq", "ping_interval", 90)
134
+...
135
+</programlisting>
136
+                </example>
137
+        </section>
138
+	</section>
139
+
140
+	<section>
141
+        <title>Functions</title>
142
+        <section>
143
+                <title>
144
+                <function moreinfo="none">dmq_handle_message()</function>
145
+                </title>
146
+                <para>
147
+                Handles a DMQ message by passing it to the appropriate local peer (module). 
148
+		The peer is identified by the user part of the To header.
149
+                </para>
150
+                <para>
151
+                This function can be used from REQUEST_ROUTE.
152
+                </para>
153
+
154
+                <example>
155
+                <title><function>dmq_handle_message</function> usage</title>
156
+                <programlisting format="linespecific">
157
+...
158
+        if(is_method("KDMQ"))
159
+        {
160
+                dmq_handle_message();
161
+        }
162
+...
163
+</programlisting>
164
+                </example>
165
+        </section>
166
+        <section>
167
+                <title>
168
+               	<function moreinfo="none">dmq_send_message(peer, node, body)</function>
169
+                </title>
170
+                <para>
171
+                Sends a DMQ message directly from config file.
172
+                </para>
173
+		<para>Meaning of parameters:</para>
174
+                <itemizedlist>
175
+	                <listitem>
176
+        	                <para>
177
+               	        	<emphasis>peer</emphasis> - name of peer that should handle the message.
178
+                        	</para>
179
+	                </listitem>
180
+        	        <listitem>
181
+                	        <para>
182
+                       		<emphasis>node</emphasis> - the node to which the message should be sent.
183
+	                        </para>
184
+        	        </listitem>
185
+                	<listitem>
186
+                        	<para>
187
+	                        <emphasis>body</emphasis> - the message body.
188
+	                        </para>
189
+	                </listitem>
190
+		</itemizedlist>
191
+                <para>
192
+                This function can be used from any route.
193
+                </para>
194
+
195
+                <example>
196
+                <title><function>dmq_send_message</function> usage</title>
197
+                <programlisting format="linespecific">
198
+...
199
+	dmq_send_message("peer_name", "sip:10.0.0.21:5060", "Message body...\n");
200
+...
201
+</programlisting>
202
+                </example>
203
+        </section>
104 204
 	</section>
205
+
105 206
 </chapter>
106 207
 
... ...
@@ -10,23 +10,20 @@
10 10
 <!-- Module Developer's Guide -->
11 11
 
12 12
 <chapter>
13
-    <title>&develguide;</title>
14
-    <para>
15
-		The module provides the following functions that can be used
16
-		in other &kamailio; modules.
17
-   </para>
18
- 		<section>
19
-				<title>
20
-				<function moreinfo="none">dmq_load_api(dmq_api_t* api)</function>
21
-				</title>
22
-			<para>
23
-				This function binds the dmq modules and fills the structure 
24
-				with the exported functions
25
-				-> register_dmq_peer - registers an entity as a DMQ peer which permits receiving/sending
26
-				messages between nodes which support the same peer,
27
-				-> bcast_message - broadcast a DMQ message to all peers available in the DMQ bus,
28
-				-> send_message - sends a DMQ message to a specific peer in the local DMQ bus.
29
-			</para>
13
+	<title>&develguide;</title>
14
+	<para>
15
+	The module provides the following functions that can be used
16
+	in other &kamailio; modules.
17
+	</para>
18
+ 	<section>
19
+		<title>
20
+		<function moreinfo="none">dmq_load_api(dmq_api_t* api)</function>
21
+		</title>
22
+		<para>
23
+		This function binds the DMQ module and fills the structure 
24
+		with the exported functions below.
25
+		</para>
26
+
30 27
 		<example>
31 28
 		<title><function>dmq_api_t</function> structure</title>
32 29
 	<programlisting format="linespecific">
... ...
@@ -39,7 +36,65 @@ typedef struct dmq_api {
39 36
 ...
40 37
 </programlisting>
41 38
 		</example>
39
+	</section>
40
+
41
+        <section>
42
+                <title>
43
+                <function moreinfo="none">register_dmq_peer(dmq_peer_t* peer)</function>
44
+                </title>
45
+                <para>
46
+                Registers an entity as a DMQ peer which permits receiving/sending 
47
+                messages between nodes which support the same peer.
48
+                </para>
49
+
50
+                <example>
51
+                <title><function>register_dmq_peer</function> usage</title>
52
+                <programlisting format="linespecific">
53
+...
54
+	Example to follow.
55
+...
56
+</programlisting>
57
+                </example>
58
+        </section>
59
+
60
+        <section>
61
+                <title>
62
+                <function moreinfo="none">bcast_message(dmq_peer_t* peer, str* body, dmq_node_t* except,
63
+                dmq_resp_cback_t* resp_cback, int max_forwards)</function>
64
+                </title>
65
+                <para>
66
+                Broadcast a DMQ message to all nodes in the DMQ bus excluding self, 
67
+		inactive nodes and "except" if specified.
68
+                </para>
69
+		
70
+                <example>
71
+                <title><function>bcast_message</function> usage</title>
72
+                <programlisting format="linespecific">
73
+...
74
+        Example to follow.
75
+...
76
+</programlisting>
77
+                </example>
78
+        </section>
79
+
80
+        <section>
81
+                <title>
82
+                <function moreinfo="none">send_message(dmq_peer_t* peer, str* body, dmq_node_t* node,
83
+                dmq_resp_cback_t* resp_cback, int max_forwards)</function>
84
+                </title>
85
+                <para>
86
+                Send a DMQ message to a single node.
87
+                </para>
88
+
89
+                <example>
90
+                <title><function>send_message</function> usage</title>
91
+                <programlisting format="linespecific">
92
+...
93
+        Example to follow.
94
+...
95
+</programlisting>
96
+                </example>
97
+        </section>
42 98
 
43
-		</section>
44 99
 </chapter>
45 100