Browse code

Formatting and doxygen documentation updates

oej authored on 21/10/2009 08:21:47
Showing 7 changed files
... ...
@@ -6,8 +6,8 @@
6 6
 # 2007-06-18  added naptr & friends, dns_srv_lb, more compile options (andrei)
7 7
 #
8 8
 
9
-Overview
9
+SIP-router and DNS Overview
10
+---------------------------
10 11
 
11 12
  The dns subsystem in sip-router can either directly use libresolv and a combination
12 13
   of the locally configured dns server, /etc/hosts and the local Network 
... ...
@@ -7,7 +7,7 @@
7 7
 
8 8
 
9 9
 SIP-router locking interface
10
-
10
+============================
11 11
 
12 12
 1. Why use it?
13 13
 --------------
... ...
@@ -7,7 +7,7 @@
7 7
                          Ondrej Martinek <ondra@iptel.org>
8 8
                                               January 2009
9 9
 
10
-This document contains the short description of the logging API in SER
10
+This document contains the short description of the logging API in SIP-router
11 11
 for developers.
12 12
 
13 13
 Source files:
... ...
@@ -121,7 +121,7 @@ Source files:
121 121
 !!! IMPORTANT! READ ME!
122 122
 !!!
123 123
 !!!  These changes (mainly the first two) require reformating of the most log
124
-!!!  messages in SER core and module source files.  This step can be done
124
+!!!  messages in SIP-router core and module source files.  This step can be done
125 125
 !!!  automatically by running "scripts/logging/fix-logs-all" script BUT it
126 126
 !!!  was NOT originally performed because it would have generated too many
127 127
 !!!  changes in CVS which was discouraged by Andrei.  Instead, the developers
... ...
@@ -1,40 +1,44 @@
1 1
 #$Id$
2 2
 #
3
-# Module intialization description
4 3
 #
5 4
 # History
6 5
 #--------
7 6
 #  2007-06-07  created by Andrei Pelinescu <andrei@iptel.org>
8 7
 #
9 8
 
9
+SIP-router Module intialization description
10
+===========================================
10 11
 
11 12
 This document is a very brief overview on what possibilities are for a module
12
-to run some initializations (or put in another way what's safe and what's
13
+to run some initializations (or put in another way: What's safe and what's
13 14
  not safe to do in mod_init and mod_child_init).
14 15
 
15 16
 The interesting function are the mod_init (the init_f memeber of
16
- the module_exports structure) and the mod_child_init (init_child_f in
17
-  module_exports) functions.
17
+the module_exports structure) and the mod_child_init (init_child_f in
18
+module_exports) functions.
18 19
 
19 20
 mod_init
20 21
 --------
21 22
 
22 23
 mod_init is called after parsing the config, loading all the modules and
23
- going into daemon mode. mod_init is called in the main process context,
24
- before changing the uid or gid (so if you want to do something requiring
25
- higher privileges this is the place to do it). This is not the right place
26
- to fork  more ser processes, but instead is the only place where one can 
27
- register future forked processes (see register_procs()).
24
+going into daemon mode. mod_init is called in the main process context,
25
+before changing the uid or gid (so if you want to do something requiring
26
+higher privileges this is the place to do it). This is not the right place
27
+to fork more SIP-router processes, but instead is the only place where one can 
28
+register future forked processes (see register_procs()).
29
+
28 30
 mod_init is ideal for initializing per process variables, assuming that you
29
- don't need different values for each ser child (in which case see mod_child_init below) and shared memory variables assuming that you don't need ser's number of processes (which is not available at this point).
31
+don't need different values for each SIP-router child (in which case see 
32
+mod_child_init below) and shared memory variables assuming that you don't 
33
+need SIP-router's number of processes (which is not available at this point).
30 34
 
31 35
 
32 36
 mod_child_init
33 37
 ---------------
34 38
 
35
-mod_child_init is called for each forked ser process with 2 exceptions:
39
+mod_child_init is called for each forked SIP-router process with 2 exceptions:
36 40
  - it's called for the main process too and it's called twice
37
- - it's not called for ser processes forked with PROC_NOCHLDINIT
41
+ - it's not called for SIP-router processes forked with PROC_NOCHLDINIT
38 42
 
39 43
 mod_child_init is always called after mod_init. It takes one parameter, the
40 44
  process rank. This parameter can be used to differentiate between normal
... ...
@@ -44,7 +48,7 @@ There are two very special rank values: PROC_INIT (as of 2007-06-06) and
44 44
 mod_child_init(PROC_INIT) is the first mod_child_init call made, and it's
45 45
  guaranteed to happen before any child process is forked. The process context
46 46
   is the "main" process (as for mod_init), but this time we have a little bit
47
- more information: we know the number of ser processes. This is the right
47
+ more information: we know the number of SIP-router processes. This is the right
48 48
   place to initialize things like shared arrays[get_max_procs()].
49 49
 Note also that everything done here will be inherited in all the future
50 50
  children processes (since it's executed in the "main" process context before
... ...
@@ -52,14 +56,14 @@ Note also that everything done here will be inherited in all the future
52 52
 
53 53
 mod_child_init(PROC_MAIN) is another call that is done in the same "main"
54 54
  process context. This call happens just before initializing the main tcp
55
-  process. This is the only right place for forking more ser processes
55
+  process. This is the only right place for forking more SIP-router processes
56 56
   (see fork_process()). WARNING: the context is the same "main" process as
57 57
  for mod_child_init(PROC_INIT) and mod_init() so care must be taken not to
58 58
  initialize things twice or three times for the "main" process.
59 59
 
60 60
 Except for the "main" process case mod_child_init(rank) will be called only
61 61
 once for each new child process, just after forking. A positive non-zero rank
62
- means the current process is a normal ser process and a negative rank has
62
+ means the current process is a normal SIP-router process and a negative rank has
63 63
   some special meaning (grep PROC_ sr_module.h for more info).
64 64
 mod_child_init(rank) is the best place for initializing per process variables,
65 65
  opening per process database connections, new sockets a.s.o. Note however
... ...
@@ -72,15 +76,15 @@ mod_child_init(rank) is the best place for initializing per process variables,
72 72
 mod_child_init in the no-fork case
73 73
 ----------------------------------
74 74
 
75
-If ser is started in no-fork mode it will try to start as few processes as
75
+If SIP-router is started in no-fork mode it will try to start as few processes as
76 76
 possible (as of this date it will start 3 processes the main process and the
77
- 2 timers). In this case mod_child_init() will be called 3 times in the
78
-  same "main" process context: mod_child_init(PROC_INIT);
79
-  mod_child_init(PROC_MAIN) and mod_child_init(1) (since the first process is
80
-  also the "main" one).
77
+2 timers). In this case mod_child_init() will be called 3 times in the
78
+same "main" process context: mod_child_init(PROC_INIT);
79
+mod_child_init(PROC_MAIN) and mod_child_init(1) (since the first process is
80
+also the "main" one).
81 81
 
82 82
 
83
-Forking new ser processes from a module
83
+Forking new SIP-router processes from a module
84 84
 ---------------------------------------
85 85
 
86 86
 static int mod_init()
... ...
@@ -133,8 +137,9 @@ mod_child_init(PROC_INIT)
133 133
   process.
134 134
 
135 135
 mod_child_init(PROC_MAIN)
136
- - the only place from where another ser process can be forked (see fork_process  ()), but remember first to register the number of to-be-forked processes in
137
-  mod_init()
136
+ - the only place from where another SIP-router process can be forked 
137
+   (see fork_process  ()), but remember first to register the number of 
138
+   to-be-forked processes in mod_init()
138 139
 
139 140
 mod_child_init(rank!=PROC_INIT && rank!=PROC_MAIN)
140 141
  - initialize other per process variables (e.g. different values), whose 
... ...
@@ -4,20 +4,21 @@
4 4
 # --------
5 5
 # 2006-01-26  created by andrei
6 6
 
7
-TCP Tunning/monitoring for lots of open connections
7
+SIP-router TCP Tunning/monitoring for lots of open connections
8
+==============================================================
8 9
 
9 10
 0. Introduction
10 11
 ----------------
11 12
 
12 13
 This document describes very briefly various settings that should improve
13
-ser+tcp performance for sites handling a lot of tcp traffic (> 1000 open
14
+sip-router+TCP performance for sites handling a lot of TCP traffic (> 1000 open
14 15
 connections or very high connection/disconnection rates).
15 16
 
16 17
 For now it deals only with Linux specific optimizations.
17 18
 
18 19
 
19
-1. Useful kernel settings
20
+1. Useful Linux kernel settings
21
+-------------------------------
20 22
 
21 23
 1.1 Connection rate/pending connections: by default the connection rate is
22 24
  too small
... ...
@@ -32,7 +33,7 @@ net.ipv4.tcp_timestamps        - default on., should be on (along with
32 32
 
33 33
  Connection should stay as little as possible
34 34
  in close_wait to quickly free the fd/resources for new connections attempts
35
- WARNING: this could break normal tcp use, use it only if you know what you are
35
+ WARNING: this could break normal TCP use, use it only if you know what you are
36 36
   doing
37 37
  
38 38
 net.ipv4.tcp_max_tw_buckets - maximum number of timewait sockets
... ...
@@ -48,6 +49,7 @@ net.ipv4.tcp_syncookies     - default off, in this case it's probably better to
48 48
                               keep it off
49 49
 
50 50
 1.3 Port range
51
+
51 52
 net.ipv4.ip_local_port_range - should be increased (e.g. 4096-65534)
52 53
 
53 54
 1.4 Open file descriptors
... ...
@@ -5,20 +5,25 @@
5 5
 # 2005-11-30    created by andrei
6 6
 
7 7
 
8
-New timer interface
8
+SIP-router :: timer interface
9
+=============================
9 10
 
10 11
 
11 12
 1. Introduction
12 13
 ---------------
13 14
 
14
- ser's new timer interface is based on a 3 level hierarchical timing wheel
15
+SIP-router's timer interface is based on a 3 level hierarchical timing wheel
15 16
 (see [1]). Most timeouts will go in the first "wheel" (all timeouts < 1<<14 
16
- ticks, which by default mean 1024 s). Each wheel acts as a circular buffer.
17
- The big advantage of this scheme is that most of the time you just run all the timer handlers from the current entry in the first wheel (no comparisons necessary). Each 2^14 ticks, all the timers in the second wheel's current entry are redistributed and each 2^23 ticks all the timers in the third wheel's current entry are redistributed.
17
+ticks, which by default mean 1024 s). Each wheel acts as a circular buffer.
18
+The big advantage of this scheme is that most of the time you just run all the 
19
+timer handlers from the current entry in the first wheel (no comparisons necessary). 
20
+Each 2^14 ticks, all the timers in the second wheel's current entry are redistributed 
21
+and each 2^23 ticks all the timers in the third wheel's current entry are redistributed.
18 22
 
19
- The new timer interfaces allows adding timers dynamically, supports one shot
20
- and periodic timers, is precise and fast (very low overhead) and supports
21
-"fast" and "slow" timers. For now it uses setitimer to "generate" the ticks and form time to time it re-adjusts them based on the real system time.
23
+The timer interfaces allows adding timers dynamically, supports one shot
24
+and periodic timers, is precise and fast (very low overhead) and supports
25
+"fast" and "slow" timers. For now it uses setitimer to "generate" the ticks and from 
26
+time to time it re-adjusts them based on the real system time.
22 27
 
23 28
 
24 29
 [1] - G. Varghese, T. Lauck,  Hashed and Hierarchical Timing Wheels: Efficient
... ...
@@ -29,7 +34,7 @@ New timer interface
29 29
 -----------------
30 30
 
31 31
 All the public functions are defined in timer.h. timer_ticks.h contains
32
- ticks conversion related macros (ticks to seconds, ms or viceversa).
32
+ticks conversion related macros (ticks to seconds, ms or viceversa).
33 33
 
34 34
 
35 35
 3. Example usage
... ...
@@ -29,7 +29,24 @@
29 29
  */
30 30
 /* History:
31 31
  * --------
32
- *  2005-07-27  complete re-design/re-implemnetation (andrei)
32
+ *  2005-07-27  complete re-design/re-implementation (andrei)
33
+ */
34
+
35
+/**
36
+ * @file
37
+ * @brief SIP-router core :: timer related functions (public interface)
38
+ * @ingroup core
39
+ *
40
+ * Module: \ref core
41
+ *
42
+ * - \ref TimerDoc
43
+ */
44
+
45
+
46
+/**
47
+ * @page TimerDoc SIP-router's timer documentation
48
+ * @verbinclude timers.txt
49
+ *
33 50
  */
34 51
 
35 52