Browse code

htable: documenting timer_procs module parameter

Daniel-Constantin Mierla authored on 07/10/2015 03:42:04
Showing 2 changed files
... ...
@@ -23,7 +23,7 @@ Ovidiu Sas
23 23
 
24 24
    <osas@voipembedded.com>
25 25
 
26
-   Copyright © 2008-2011 http://www.asipto.com
26
+   Copyright � 2008-2011 http://www.asipto.com
27 27
      __________________________________________________________________
28 28
 
29 29
    Table of Contents
... ...
@@ -52,6 +52,7 @@ Ovidiu Sas
52 52
               3.11. timer_mode (integer)
53 53
               3.12. db_expires (integer)
54 54
               3.13. enable_dmq (integer)
55
+              3.14. timer_procs (integer)
55 56
 
56 57
         4. Functions
57 58
 
... ...
@@ -106,15 +107,16 @@ Ovidiu Sas
106 107
    1.14. Set timer_mode parameter
107 108
    1.15. Set db_expires parameter
108 109
    1.16. Set enable_dmq parameter
109
-   1.17. sht_print usage
110
-   1.18. sht_rm_name_re usage
111
-   1.19. sht_rm_value_re usage
112
-   1.20. sht_reset usage
113
-   1.21. sht_lock usage
114
-   1.22. sht_unlock usage
115
-   1.23. sht_iterator_start usage
116
-   1.24. sht_iterator_end usage
117
-   1.25. sht_iterator_next usage
110
+   1.17. Set timer_procs parameter
111
+   1.18. sht_print usage
112
+   1.19. sht_rm_name_re usage
113
+   1.20. sht_rm_value_re usage
114
+   1.21. sht_reset usage
115
+   1.22. sht_lock usage
116
+   1.23. sht_unlock usage
117
+   1.24. sht_iterator_start usage
118
+   1.25. sht_iterator_end usage
119
+   1.26. sht_iterator_next usage
118 120
 
119 121
 Chapter 1. Admin Guide
120 122
 
... ...
@@ -142,6 +144,7 @@ Chapter 1. Admin Guide
142 144
         3.11. timer_mode (integer)
143 145
         3.12. db_expires (integer)
144 146
         3.13. enable_dmq (integer)
147
+        3.14. timer_procs (integer)
145 148
 
146 149
    4. Functions
147 150
 
... ...
@@ -199,7 +202,7 @@ Chapter 1. Admin Guide
199 202
    You can read more about hash tables at:
200 203
    http://en.wikipedia.org/wiki/Hash_table.
201 204
 
202
-   The “name” can be a static string or can include pseudo- variables that
205
+   The "name" can be a static string or can include pseudo- variables that
203 206
    will be replaced at runtime.
204 207
 
205 208
    Example 1.1. Accessing $sht(htname=>key)
... ...
@@ -213,7 +216,7 @@ $sht(a=>$ci::srcip) = $si;
213 216
    Next example shows a way to protect against dictionary attacks. If
214 217
    someone fails to authenticate 3 times, it is forbidden for 15min.
215 218
    Authenticatiion against database is expensive as it does a select on
216
-   the “subscriberthe” table. By disabling the DB auth for 15min,
219
+   the "subscriberthe" table. By disabling the DB auth for 15min,
217 220
    resources on the server are saved and time to discover the password is
218 221
    increased substantially. Additional alerting can be done by writing a
219 222
    message to syslog or sending email, etc.
... ...
@@ -222,7 +225,7 @@ $sht(a=>$ci::srcip) = $si;
222 225
    the failed authentications per user and one for storing the time of
223 226
    last authentication attempt. To ensure a unique name per user, the hash
224 227
    table uses a combination of authentication username and text
225
-   “::auth_count” and “::last_auth”.
228
+   "::auth_count" and "::last_auth".
226 229
 
227 230
    Example 1.2. Dictionary attack limitation
228 231
 ...
... ...
@@ -414,6 +417,7 @@ $ kamcmd htable.dump htable
414 417
    3.11. timer_mode (integer)
415 418
    3.12. db_expires (integer)
416 419
    3.13. enable_dmq (integer)
420
+   3.14. timer_procs (integer)
417 421
 
418 422
 3.1. htable (str)
419 423
 
... ...
@@ -447,7 +451,7 @@ $ kamcmd htable.dump htable
447 451
        however, in which case this attribute can be set to 0.
448 452
      * dmqreplicate - if set to 1, any actions (set, update, delete etc.)
449 453
        performed upon entries in this table will be replicated to other
450
-       nodes (htable peers). Please note, module parameter “enable_dmq”
454
+       nodes (htable peers). Please note, module parameter "enable_dmq"
451 455
        must also be set in order for this to apply (see below). Default is
452 456
        0 (no replication).
453 457
 
... ...
@@ -610,6 +614,20 @@ modparam("htable", "db_expires", 1)
610 614
 modparam("htable", "enable_dmq", 1)
611 615
 ...
612 616
 
617
+3.14. timer_procs (integer)
618
+
619
+   If set to 1, the module will create its own timer process to scan for
620
+   expired items in hash tables. If set to zero, it will use the core
621
+   timer for this task. Set it to 1 if you store a lot of items with
622
+   autoexpire property.
623
+
624
+   Default value is 0.
625
+
626
+   Example 1.17. Set timer_procs parameter
627
+...
628
+modparam("htable", "timer_procs", 1)
629
+...
630
+
613 631
 4. Functions
614 632
 
615 633
    4.1. sht_print()
... ...
@@ -622,7 +640,7 @@ modparam("htable", "enable_dmq", 1)
622 640
    4.8. sht_iterator_end(iname)
623 641
    4.9. sht_iterator_next(iname)
624 642
 
625
-4.1.  sht_print()
643
+4.1. sht_print()
626 644
 
627 645
    Dump content of hash table to L_ERR log level. Intended for debug
628 646
    purposes.
... ...
@@ -630,12 +648,12 @@ modparam("htable", "enable_dmq", 1)
630 648
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
631 649
    ONREPLY_ROUTE, BRANCH_ROUTE.
632 650
 
633
-   Example 1.17. sht_print usage
651
+   Example 1.18. sht_print usage
634 652
 ...
635 653
 sht_print();
636 654
 ...
637 655
 
638
-4.2.  sht_rm_name_re(htable=>regexp)
656
+4.2. sht_rm_name_re(htable=>regexp)
639 657
 
640 658
    Delete all entries in the htable that match the name against regular
641 659
    expression.
... ...
@@ -643,12 +661,12 @@ sht_print();
643 661
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
644 662
    ONREPLY_ROUTE, BRANCH_ROUTE.
645 663
 
646
-   Example 1.18. sht_rm_name_re usage
664
+   Example 1.19. sht_rm_name_re usage
647 665
 ...
648 666
 sht_rm_name_re("ha=>.*");
649 667
 ...
650 668
 
651
-4.3.  sht_rm_value_re(htable=>regexp)
669
+4.3. sht_rm_value_re(htable=>regexp)
652 670
 
653 671
    Delete all entries in the htable that match the value against regular
654 672
    expression.
... ...
@@ -656,24 +674,24 @@ sht_rm_name_re("ha=>.*");
656 674
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
657 675
    ONREPLY_ROUTE, BRANCH_ROUTE.
658 676
 
659
-   Example 1.19. sht_rm_value_re usage
677
+   Example 1.20. sht_rm_value_re usage
660 678
 ...
661 679
 sht_rm_value_re("ha=>.*");
662 680
 ...
663 681
 
664
-4.4.  sht_reset(htable)
682
+4.4. sht_reset(htable)
665 683
 
666 684
    Delete all entries in the htable. The name of the hash table can be a
667 685
    dynamic string with variables.
668 686
 
669 687
    This function can be used from ANY_ROUTE.
670 688
 
671
-   Example 1.20. sht_reset usage
689
+   Example 1.21. sht_reset usage
672 690
 ...
673 691
 sht_reset("ha$var(x)");
674 692
 ...
675 693
 
676
-4.5.  sht_lock(htable=>key)
694
+4.5. sht_lock(htable=>key)
677 695
 
678 696
    Lock the slot in htable corespoding to the key item. Note that the
679 697
    locking is re-entrant for the process, therefore the lock and unlock
... ...
@@ -681,12 +699,12 @@ sht_reset("ha$var(x)");
681 699
 
682 700
    This function can be used from ANY_ROUTE.
683 701
 
684
-   Example 1.21. sht_lock usage
702
+   Example 1.22. sht_lock usage
685 703
 ...
686 704
 sht_lock("ha=>test");
687 705
 ...
688 706
 
689
-4.6.  sht_unlock(htable=>key)
707
+4.6. sht_unlock(htable=>key)
690 708
 
691 709
    Unlock the slot in htable corespoding to the key item. Note that the
692 710
    locking is re-entrant for the process, therefore the lock and unlock
... ...
@@ -694,14 +712,14 @@ sht_lock("ha=>test");
694 712
 
695 713
    This function can be used from ANY_ROUTE.
696 714
 
697
-   Example 1.22. sht_unlock usage
715
+   Example 1.23. sht_unlock usage
698 716
 ...
699 717
 sht_lock("ha=>test");
700 718
 $sht(ha=>test) = $sht(ha=>test) + 10;
701 719
 sht_unlock("ha=>test");
702 720
 ...
703 721
 
704
-4.7.  sht_iterator_start(iname, hname)
722
+4.7. sht_iterator_start(iname, hname)
705 723
 
706 724
    Start an iterator for hash table named by the value of parameter hname.
707 725
    The parameter iname is used to identify the iterator. There can be up
... ...
@@ -716,12 +734,12 @@ sht_unlock("ha=>test");
716 734
 
717 735
    This function can be used from ANY_ROUTE.
718 736
 
719
-   Example 1.23. sht_iterator_start usage
737
+   Example 1.24. sht_iterator_start usage
720 738
 ...
721 739
 sht_iterator_start("i1", "h1");
722 740
 ...
723 741
 
724
-4.8.  sht_iterator_end(iname)
742
+4.8. sht_iterator_end(iname)
725 743
 
726 744
    Close the iterator identified by iname parameter and release the hash
727 745
    table slot aquired by the iterator. The iname value must be the same
... ...
@@ -731,12 +749,12 @@ sht_iterator_start("i1", "h1");
731 749
 
732 750
    This function can be used from ANY_ROUTE.
733 751
 
734
-   Example 1.24. sht_iterator_end usage
752
+   Example 1.25. sht_iterator_end usage
735 753
 ...
736 754
 sht_iterator_end("i1");
737 755
 ...
738 756
 
739
-4.9.  sht_iterator_next(iname)
757
+4.9. sht_iterator_next(iname)
740 758
 
741 759
    Move the iterator to the next item in hash table. It must be called
742 760
    also after sht_iterator_start() to get the first item in the hash
... ...
@@ -753,7 +771,7 @@ sht_iterator_end("i1");
753 771
 
754 772
    This function can be used from ANY_ROUTE.
755 773
 
756
-   Example 1.25. sht_iterator_next usage
774
+   Example 1.26. sht_iterator_next usage
757 775
 ...
758 776
     sht_iterator_start("i1", "h1");
759 777
     while(sht_iterator_next("i1")) {
... ...
@@ -781,7 +799,7 @@ sht_iterator_end("i1");
781 799
    6.2. sht_dump
782 800
    6.3. sht_delete
783 801
 
784
-6.1.  sht_reload
802
+6.1. sht_reload
785 803
 
786 804
    Reload a hash table from database.
787 805
 
... ...
@@ -794,7 +812,7 @@ sht_iterator_end("i1");
794 812
                 _hash_table_name_
795 813
                 _empty_line_
796 814
 
797
-6.2.  sht_dump
815
+6.2. sht_dump
798 816
 
799 817
    Dump content of a hash table via MI.
800 818
 
... ...
@@ -807,7 +825,7 @@ sht_iterator_end("i1");
807 825
                 _hash_table_name_
808 826
                 _empty_line_
809 827
 
810
-6.3.  sht_delete
828
+6.3. sht_delete
811 829
 
812 830
    Delete a key from a hash table via MI.
813 831
 
... ...
@@ -837,7 +855,7 @@ sht_iterator_end("i1");
837 855
    7.7. htable.listTables
838 856
    7.8. htable.stats
839 857
 
840
-7.1.  htable.get htable key
858
+7.1. htable.get htable key
841 859
 
842 860
    Lists one value in a hash table
843 861
 
... ...
@@ -856,7 +874,7 @@ kamcmd htable.get students daniel
856 874
 kamcmd htable.get students course[0]
857 875
 ...
858 876
 
859
-7.2.  htable.delete htable key
877
+7.2. htable.delete htable key
860 878
 
861 879
    Delete one value in a hash table
862 880
 
... ...
@@ -875,7 +893,7 @@ kamcmd htable.delete students anna
875 893
 kamcmd htable.delete students course[0]
876 894
 ...
877 895
 
878
-7.3.  htable.sets htable key value
896
+7.3. htable.sets htable key value
879 897
 
880 898
    Set an item in hash table to string value.
881 899
 
... ...
@@ -895,7 +913,7 @@ kamcmd htable.sets test x abc
895 913
 kamcmd htable.sets test x[0] abc
896 914
 ...
897 915
 
898
-7.4.  htable.seti htable key value
916
+7.4. htable.seti htable key value
899 917
 
900 918
    Set an item in hash table to integer value.
901 919
 
... ...
@@ -915,7 +933,7 @@ kamcmd htable.seti test x 123
915 933
 kamcmd htable.sets test x[0] 123
916 934
 ...
917 935
 
918
-7.5.  htable.dump htable
936
+7.5. htable.dump htable
919 937
 
920 938
    Lists all the values in a hash table
921 939
 
... ...
@@ -929,7 +947,7 @@ kamcmd htable.sets test x[0] 123
929 947
 kamcmd htable.dump ipban
930 948
 ...
931 949
 
932
-7.6.  htable.reload htable
950
+7.6. htable.reload htable
933 951
 
934 952
    Reload hash table from database.
935 953
 
... ...
@@ -943,7 +961,7 @@ kamcmd htable.dump ipban
943 961
 kamcmd htable.reload ipban
944 962
 ...
945 963
 
946
-7.7.  htable.listTables
964
+7.7. htable.listTables
947 965
 
948 966
    Lists all defined tables
949 967
 
... ...
@@ -957,7 +975,7 @@ kamcmd htable.reload ipban
957 975
 kamcmd htable.listTables
958 976
 ...
959 977
 
960
-7.8.  htable.stats
978
+7.8. htable.stats
961 979
 
962 980
    Get statistics for hash tables - name, number of slots, number of
963 981
    items, max number of items per slot, min number of items per slot.
... ...
@@ -977,7 +995,7 @@ kamcmd htable.stats
977 995
    8.1. htable:mod-init
978 996
    8.2. htable:expired:<table>
979 997
 
980
-8.1.  htable:mod-init
998
+8.1. htable:mod-init
981 999
 
982 1000
    When defined, the module calls event_route[htable:mod-init] after all
983 1001
    modules have been initialized. A typical use case is to initialise
... ...
@@ -990,7 +1008,7 @@ event_route[htable:mod-init] {
990 1008
 }
991 1009
 ...
992 1010
 
993
-8.2.  htable:expired:<table>
1011
+8.2. htable:expired:<table>
994 1012
 
995 1013
    When defined, the module calls event_route[htable:expired:<table>] when
996 1014
    an entry in the given table expires. In this event route, the key and
... ...
@@ -652,6 +652,28 @@ modparam("htable", "db_expires", 1)
652 652
 ...
653 653
 modparam("htable", "enable_dmq", 1)
654 654
 ...
655
+</programlisting>
656
+		</example>
657
+	</section>
658
+	<section id="htable.p.timer_procs">
659
+		<title><varname>timer_procs</varname> (integer)</title>
660
+		<para>
661
+			If set to 1, the module will create its own timer process to scan
662
+			for expired items in hash tables. If set to zero, it will use the
663
+			core timer for this task. Set it to 1 if you store a lot of items
664
+			with autoexpire property.
665
+		</para>
666
+		<para>
667
+		<emphasis>
668
+			Default value is 0.
669
+		</emphasis>
670
+		</para>
671
+		<example>
672
+		<title>Set <varname>timer_procs</varname> parameter</title>
673
+		<programlisting format="linespecific">
674
+...
675
+modparam("htable", "timer_procs", 1)
676
+...
655 677
 </programlisting>
656 678
 		</example>
657 679
 	</section>