Browse code

htable: update documentation for dmq integration

Charles Chance authored on 07/10/2013 06:52:21
Showing 2 changed files
... ...
@@ -45,6 +45,7 @@ Alex Balashov
45 45
               3.10. timer_interval (integer)
46 46
               3.11. timer_mode (integer)
47 47
               3.12. db_expires (integer)
48
+              3.13. enable_dmq (integer)
48 49
 
49 50
         4. Functions
50 51
 
... ...
@@ -92,11 +93,12 @@ Alex Balashov
92 92
    1.12. Set timer_interval parameter
93 93
    1.13. Set timer_mode parameter
94 94
    1.14. Set db_expires parameter
95
-   1.15. sht_print usage
96
-   1.16. sht_rm_name_re usage
97
-   1.17. sht_rm_value_re usage
98
-   1.18. sht_lock usage
99
-   1.19. sht_unlock usage
95
+   1.15. Set enable_dmq parameter
96
+   1.16. sht_print usage
97
+   1.17. sht_rm_name_re usage
98
+   1.18. sht_rm_value_re usage
99
+   1.19. sht_lock usage
100
+   1.20. sht_unlock usage
100 101
 
101 102
 Chapter 1. Admin Guide
102 103
 
... ...
@@ -123,6 +125,7 @@ Chapter 1. Admin Guide
123 123
         3.10. timer_interval (integer)
124 124
         3.11. timer_mode (integer)
125 125
         3.12. db_expires (integer)
126
+        3.13. enable_dmq (integer)
126 127
 
127 128
    4. Functions
128 129
 
... ...
@@ -169,6 +172,9 @@ Chapter 1. Admin Guide
169 169
    expiration time of cached items. The expiration time can be adjusted
170 170
    per itme via assignment operation at runtime.
171 171
 
172
+   Replication between multiple servers is performed automatically (if
173
+   enabled) via the DMQ module.
174
+
172 175
    You can read more about hash tables at:
173 176
    http://en.wikipedia.org/wiki/Hash_table.
174 177
 
... ...
@@ -248,7 +254,8 @@ if(is_present_hf("Authorization"))
248 248
 2.1. Kamailio Modules
249 249
 
250 250
    The following modules must be loaded before this module:
251
-     * No dependencies on other Kamailio modules.
251
+     * If DMQ replication is enabled, the DMQ module must be loaded
252
+       first..
252 253
 
253 254
 2.2. External Libraries or Applications
254 255
 
... ...
@@ -287,6 +294,7 @@ if(is_present_hf("Authorization"))
287 287
    3.10. timer_interval (integer)
288 288
    3.11. timer_mode (integer)
289 289
    3.12. db_expires (integer)
290
+   3.13. enable_dmq (integer)
290 291
 
291 292
 3.1. htable (str)
292 293
 
... ...
@@ -318,6 +326,11 @@ if(is_present_hf("Authorization"))
318 318
        an item is reset when that item is updated. Certain uses of htable
319 319
        may dictate that updates should not reset the expiration timeout,
320 320
        however, in which case this attribute can be set to 0.
321
+     * dmqreplicate - if set to 1, any actions (set, update, delete etc.)
322
+       performed upon entries in this table will be replicated to other
323
+       nodes (htable peers). Please note, module parameter "enable_dmq"
324
+       must also be set in order for this to apply (see below). Default is
325
+       0 (no replication).
321 326
 
322 327
    Default value is NULL.
323 328
 
... ...
@@ -325,7 +338,8 @@ if(is_present_hf("Authorization"))
325 325
 ...
326 326
 modparam("htable", "htable", "a=>size=4;autoexpire=7200;dbtable=htable_a;")
327 327
 modparam("htable", "htable", "b=>size=5;")
328
-modparam("htable", "htable", "c=>size=4;autoexpire=7200;initval=1;")
328
+modparam("htable", "htable", "c=>size=4;autoexpire=7200;initval=1;dmqreplicate=1
329
+;")
329 330
 ...
330 331
 
331 332
 3.2. db_url (str)
... ...
@@ -453,6 +467,26 @@ modparam("htable", "timer_mode", 1)
453 453
 modparam("htable", "db_expires", 1)
454 454
 ...
455 455
 
456
+3.13. enable_dmq (integer)
457
+
458
+   If set to 1, will enable DMQ replication of actions performed upon
459
+   entries in all tables having "dmqreplicate" parameter set. Any update
460
+   action performed via psuedo-variables, MI and RPC commands will be
461
+   repeated on all other nodes. Therefore, it is important to ensure the
462
+   table definition (size, autoexpire etc.) is identical across all
463
+   instances.
464
+
465
+   Currently, values are not replicated on load from DB as it is expected
466
+   that in these cases, all servers will load their values from the same
467
+   DB.
468
+
469
+   Default value is 0.
470
+
471
+   Example 1.15. Set enable_dmq parameter
472
+...
473
+modparam("htable", "enable_dmq", 1)
474
+...
475
+
456 476
 4. Functions
457 477
 
458 478
    4.1. sht_print()
... ...
@@ -469,7 +503,7 @@ modparam("htable", "db_expires", 1)
469 469
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
470 470
    ONREPLY_ROUTE, BRANCH_ROUTE.
471 471
 
472
-   Example 1.15. sht_print usage
472
+   Example 1.16. sht_print usage
473 473
 ...
474 474
 sht_print();
475 475
 ...
... ...
@@ -482,7 +516,7 @@ sht_print();
482 482
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
483 483
    ONREPLY_ROUTE, BRANCH_ROUTE.
484 484
 
485
-   Example 1.16. sht_rm_name_re usage
485
+   Example 1.17. sht_rm_name_re usage
486 486
 ...
487 487
 sht_rm_name_re("ha=>.*");
488 488
 ...
... ...
@@ -495,7 +529,7 @@ sht_rm_name_re("ha=>.*");
495 495
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
496 496
    ONREPLY_ROUTE, BRANCH_ROUTE.
497 497
 
498
-   Example 1.17. sht_rm_value_re usage
498
+   Example 1.18. sht_rm_value_re usage
499 499
 ...
500 500
 sht_rm_value_re("ha=>.*");
501 501
 ...
... ...
@@ -506,7 +540,7 @@ sht_rm_value_re("ha=>.*");
506 506
 
507 507
    This function can be used from ANY_ROUTE.
508 508
 
509
-   Example 1.18. sht_lock usage
509
+   Example 1.19. sht_lock usage
510 510
 ...
511 511
 sht_lock("ha=>test");
512 512
 ...
... ...
@@ -517,7 +551,7 @@ sht_lock("ha=>test");
517 517
 
518 518
    This function can be used from ANY_ROUTE.
519 519
 
520
-   Example 1.19. sht_unlock usage
520
+   Example 1.20. sht_unlock usage
521 521
 ...
522 522
 sht_lock("ha=>test");
523 523
 $sht(ha=>test) = $sht(ha=>test) + 10;
... ...
@@ -31,6 +31,10 @@
31 31
 		be adjusted per itme via assignment operation at runtime.
32 32
 	</para>
33 33
 	<para>
34
+		Replication between multiple servers is performed automatically (if 
35
+		enabled) via the DMQ module.
36
+	</para>
37
+	<para>
34 38
 		You can read more about hash tables at:
35 39
 		http://en.wikipedia.org/wiki/Hash_table.
36 40
 	</para>
... ...
@@ -121,7 +125,7 @@ if(is_present_hf("Authorization"))
121 121
 			<itemizedlist>
122 122
 			<listitem>
123 123
 			<para>
124
-				<emphasis>No dependencies on other &kamailio; modules</emphasis>.
124
+				<emphasis>If DMQ replication is enabled, the DMQ module must be loaded first.</emphasis>.
125 125
 			</para>
126 126
 			</listitem>
127 127
 			</itemizedlist>
... ...
@@ -272,6 +276,11 @@ if(is_present_hf("Authorization"))
272 272
 			<emphasis>updateexpire</emphasis> - if set to 1 (default), the time until expiration of an item is reset when that item is updated.  Certain uses of htable may dictate that updates should not reset the expiration timeout, however, in which case this attribute can be set to 0.
273 273
 		</para>
274 274
 		</listitem>
275
+		<listitem>
276
+		<para>
277
+			<emphasis>dmqreplicate</emphasis> - if set to 1, any actions (set, update, delete etc.) performed upon entries in this table will be replicated to other nodes (htable peers). Please note, module parameter "enable_dmq" must also be set in order for this to apply (see below). Default is 0 (no replication).
278
+		</para>
279
+		</listitem>
275 280
 		</itemizedlist>
276 281
 		<para>
277 282
 		<emphasis>
... ...
@@ -284,7 +293,7 @@ if(is_present_hf("Authorization"))
284 284
 ...
285 285
 modparam("htable", "htable", "a=&gt;size=4;autoexpire=7200;dbtable=htable_a;")
286 286
 modparam("htable", "htable", "b=&gt;size=5;")
287
-modparam("htable", "htable", "c=&gt;size=4;autoexpire=7200;initval=1;")
287
+modparam("htable", "htable", "c=&gt;size=4;autoexpire=7200;initval=1;dmqreplicate=1;")
288 288
 ...
289 289
 </programlisting>
290 290
 		</example>
... ...
@@ -504,6 +513,33 @@ modparam("htable", "db_expires", 1)
504 504
 </programlisting>
505 505
 		</example>
506 506
 	</section>
507
+	<section>
508
+		<title><varname>enable_dmq</varname> (integer)</title>
509
+		<para>
510
+			If set to 1, will enable DMQ replication of actions performed upon 
511
+			entries in all tables having "dmqreplicate" parameter set. Any update 
512
+			action performed via psuedo-variables, MI and RPC commands will be 
513
+			repeated on all other nodes. Therefore, it is important to ensure the
514
+			table definition (size, autoexpire etc.) is identical across all instances.
515
+		</para>
516
+		<para>
517
+			Currently, values are not replicated on load from DB as it is expected 
518
+			that in these cases, all servers will load their values from the same DB.
519
+		</para>
520
+		<para>
521
+		<emphasis>
522
+			Default value is 0.
523
+		</emphasis>
524
+		</para>
525
+		<example>
526
+		<title>Set <varname>enable_dmq</varname> parameter</title>
527
+		<programlisting format="linespecific">
528
+...
529
+modparam("htable", "enable_dmq", 1)
530
+...
531
+</programlisting>
532
+		</example>
533
+	</section>
507 534
 	</section>
508 535
 	<section>
509 536
 	<title>Functions</title>