Browse code

doc: reorganized the content of doc folder

Daniel-Constantin Mierla authored on 07/12/2016 13:54:42
Showing 1 changed files
1 1
deleted file mode 100644
... ...
@@ -1,150 +0,0 @@
1
-
2
-Kamailio Module intialization description
3
-===========================================
4
-
5
-This document is a very brief overview on what possibilities are for a module
6
-to run some initializations (or put in another way: What's safe and what's
7
- not safe to do in mod_init and mod_child_init).
8
-
9
-The interesting function are the mod_init (the init_f memeber of
10
-the module_exports structure) and the mod_child_init (init_child_f in
11
-module_exports) functions.
12
-
13
-mod_init
14
-
15
-mod_init is called after parsing the config, loading all the modules and
16
-going into daemon mode. mod_init is called in the main process context,
17
-before changing the uid or gid (so if you want to do something requiring
18
-higher privileges this is the place to do it). This is not the right place
19
-to fork more Kamailio processes, but instead is the only place where one can 
20
-register future forked processes (see register_procs()).
21
-
22
-mod_init is ideal for initializing per process variables, assuming that you
23
-don't need different values for each Kamailio child (in which case see 
24
-mod_child_init below) and shared memory variables assuming that you don't 
25
-need Kamailio's number of processes (which is not available at this point).
26
-
27
-
28
-mod_child_init
29
-
30
-mod_child_init is called for each forked Kamailio process with 2 exceptions:
31
- - it's called for the main process too and it's called twice
32
- - it's not called for Kamailio processes forked with PROC_NOCHLDINIT
33
-
34
-mod_child_init is always called after mod_init. It takes one parameter, the
35
- process rank. This parameter can be used to differentiate between normal
36
-  new-forked-process calls and some special calls.
37
-There are two very special rank values: PROC_INIT (as of 2007-06-06) and
38
- PROC_MAIN:
39
-mod_child_init(PROC_INIT) is the first mod_child_init call made, and it's
40
- guaranteed to happen before any child process is forked. The process context
41
-  is the "main" process (as for mod_init), but this time we have a little bit
42
- more information: we know the number of Kamailio processes. This is the right
43
-  place to initialize things like shared arrays[get_max_procs()].
44
-Note also that everything done here will be inherited in all the future
45
- children processes (since it's executed in the "main" process context before
46
- forking).
47
-
48
-mod_child_init(PROC_MAIN) is another call that is done in the same "main"
49
- process context. This call happens just before initializing the main tcp
50
-  process. This is the only right place for forking more Kamailio processes
51
-  (see fork_process()). WARNING: the context is the same "main" process as
52
- for mod_child_init(PROC_INIT) and mod_init() so care must be taken not to
53
- initialize things twice or three times for the "main" process.
54
-
55
-Except for the "main" process case mod_child_init(rank) will be called only
56
-once for each new child process, just after forking. A positive non-zero rank
57
- means the current process is a normal Kamailio process and a negative rank has
58
-  some special meaning (grep PROC_ sr_module.h for more info).
59
-mod_child_init(rank) is the best place for initializing per process variables,
60
- opening per process database connections, new sockets a.s.o. Note however
61
- that several mod_child_init()s can execute in the same time (with the
62
-  PROC_INIT exceptions) so this is not a good place for initializing shared
63
-  memory variables.
64
-
65
-
66
-
67
-mod_child_init in the no-fork case
68
-
69
-If Kamailio is started in no-fork mode it will try to start as few processes as
70
-possible (as of this date it will start 3 processes the main process and the
71
-2 timers). In this case mod_child_init() will be called 3 times in the
72
-same "main" process context: mod_child_init(PROC_INIT);
73
-mod_child_init(PROC_MAIN) and mod_child_init(1) (since the first process is
74
-also the "main" one).
75
-
76
-
77
-Forking new Kamailio processes from a module
78
-
79
-static int mod_init()
80
-{
81
-	register_procs(2); /* we want to create 2 extra processes */
82
-	return 0;
83
-}
84
-
85
-static int mod_child(int rank)
86
-{
87
-	int pid;
88
-	
89
-	if (rank==PROC_MAIN){
90
-		pid=fork_process(some_positive_number, "name", 1);
91
-		if (pid<0)
92
-			return -1; /* error */
93
-		else if (pid ==0){
94
-			/* child1_main_loop(); */
95
-		}else{ /* parent */
96
-			pid=fork_process(some_other_postivie_number, "name2", 1);
97
-			if (pid<0) 
98
-			    /* ... same as above */
99
-			...
100
-		}
101
-	}
102
-	return 0;
103
-}
104
-
105
-The forked child process shall also update its local configuration,
106
-please read the section "Refreshing the configuration" in doc/cfg.txt.
107
-
108
-
109
-Summary
110
-
111
-mod_init():
112
- - register the number of processes that will be forked from
113
-   mod_child_init(PROC_MAIN) (if any) , see register_procs().
114
- - initialize things requiring higher privileges
115
- - initialize per process variables with common value (they will be 
116
-   inherited by all the future children)
117
- - initialize shared memory variables if possible (no need for things that
118
-   are available latter like the process count)
119
-
120
-mod_child_init(PROC_INIT)
121
- - same as mod_init except for registering processes & privileged stuff
122
- - the process number is now available so for example initializing shared 
123
-   per process statistics arrays (int stats[proc_no]) is possible
124
- - guaranteed to be run before any process is forked (like mod_init()).
125
-
126
-  WARNING: same process context as mod_init() and mod_child_init(PROC_MAIN) so
127
-  care must be taken not to initialize things 2 or 3 times for the "main"
128
-  process.
129
-
130
-mod_child_init(PROC_MAIN)
131
- - the only place from where another Kamailio process can be forked 
132
-   (see fork_process  ()), but remember first to register the number of 
133
-   to-be-forked processes in mod_init()
134
-
135
-mod_child_init(rank!=PROC_INIT && rank!=PROC_MAIN)
136
- - initialize other per process variables (e.g. different values), whose 
137
-   initial values will be visible only in the current process (they won't
138
-   be inherited anymore).
139
- - open per process db connections, sockets a.s.o.
140
- - seed custom random generators
141
- 
142
-  WARNINGs: - several mod_child_inits() can run in parallel
143
-            - the rank number is not necessarily unique
144
- 
145
- -
Browse code

doc Remove SVN ID's, remove history, change "SIP-router" and "ser" to "Kamailio"

Olle E. Johansson authored on 10/01/2015 08:47:18
Showing 1 changed files
... ...
@@ -1,12 +1,5 @@
1
-#$Id$
2
-#
3
-#
4
-# History
5
-#--------
6
-#  2007-06-07  created by Andrei Pelinescu <andrei@iptel.org>
7
-#
8
-
9
-SIP-router Module intialization description
1
+
2
+Kamailio Module intialization description
10 3
 ===========================================
11 4
 
12 5
 This document is a very brief overview on what possibilities are for a module
... ...
@@ -24,21 +17,21 @@ mod_init is called after parsing the config, loading all the modules and
24 17
 going into daemon mode. mod_init is called in the main process context,
25 18
 before changing the uid or gid (so if you want to do something requiring
26 19
 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 
20
+to fork more Kamailio processes, but instead is the only place where one can 
28 21
 register future forked processes (see register_procs()).
29 22
 
30 23
 mod_init is ideal for initializing per process variables, assuming that you
31
-don't need different values for each SIP-router child (in which case see 
24
+don't need different values for each Kamailio child (in which case see 
32 25
 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).
26
+need Kamailio's number of processes (which is not available at this point).
34 27
 
35 28
 
36 29
 mod_child_init
37 30
 ---------------
38 31
 
39
-mod_child_init is called for each forked SIP-router process with 2 exceptions:
32
+mod_child_init is called for each forked Kamailio process with 2 exceptions:
40 33
  - it's called for the main process too and it's called twice
41
- - it's not called for SIP-router processes forked with PROC_NOCHLDINIT
34
+ - it's not called for Kamailio processes forked with PROC_NOCHLDINIT
42 35
 
43 36
 mod_child_init is always called after mod_init. It takes one parameter, the
44 37
  process rank. This parameter can be used to differentiate between normal
... ...
@@ -48,7 +41,7 @@ There are two very special rank values: PROC_INIT (as of 2007-06-06) and
48 41
 mod_child_init(PROC_INIT) is the first mod_child_init call made, and it's
49 42
  guaranteed to happen before any child process is forked. The process context
50 43
   is the "main" process (as for mod_init), but this time we have a little bit
51
- more information: we know the number of SIP-router processes. This is the right
44
+ more information: we know the number of Kamailio processes. This is the right
52 45
   place to initialize things like shared arrays[get_max_procs()].
53 46
 Note also that everything done here will be inherited in all the future
54 47
  children processes (since it's executed in the "main" process context before
... ...
@@ -56,14 +49,14 @@ Note also that everything done here will be inherited in all the future
56 49
 
57 50
 mod_child_init(PROC_MAIN) is another call that is done in the same "main"
58 51
  process context. This call happens just before initializing the main tcp
59
-  process. This is the only right place for forking more SIP-router processes
52
+  process. This is the only right place for forking more Kamailio processes
60 53
   (see fork_process()). WARNING: the context is the same "main" process as
61 54
  for mod_child_init(PROC_INIT) and mod_init() so care must be taken not to
62 55
  initialize things twice or three times for the "main" process.
63 56
 
64 57
 Except for the "main" process case mod_child_init(rank) will be called only
65 58
 once for each new child process, just after forking. A positive non-zero rank
66
- means the current process is a normal SIP-router process and a negative rank has
59
+ means the current process is a normal Kamailio process and a negative rank has
67 60
   some special meaning (grep PROC_ sr_module.h for more info).
68 61
 mod_child_init(rank) is the best place for initializing per process variables,
69 62
  opening per process database connections, new sockets a.s.o. Note however
... ...
@@ -76,7 +69,7 @@ mod_child_init(rank) is the best place for initializing per process variables,
76 69
 mod_child_init in the no-fork case
77 70
 ----------------------------------
78 71
 
79
-If SIP-router is started in no-fork mode it will try to start as few processes as
72
+If Kamailio is started in no-fork mode it will try to start as few processes as
80 73
 possible (as of this date it will start 3 processes the main process and the
81 74
 2 timers). In this case mod_child_init() will be called 3 times in the
82 75
 same "main" process context: mod_child_init(PROC_INIT);
... ...
@@ -84,7 +77,7 @@ mod_child_init(PROC_MAIN) and mod_child_init(1) (since the first process is
84 77
 also the "main" one).
85 78
 
86 79
 
87
-Forking new SIP-router processes from a module
80
+Forking new Kamailio processes from a module
88 81
 ---------------------------------------
89 82
 
90 83
 static int mod_init()
... ...
@@ -140,7 +133,7 @@ mod_child_init(PROC_INIT)
140 133
   process.
141 134
 
142 135
 mod_child_init(PROC_MAIN)
143
- - the only place from where another SIP-router process can be forked 
136
+ - the only place from where another Kamailio process can be forked 
144 137
    (see fork_process  ()), but remember first to register the number of 
145 138
    to-be-forked processes in mod_init()
146 139
 
Browse code

fork_process doc: note about config update added

Miklos Tirpak authored on 04/10/2010 15:46:11
Showing 1 changed files
... ...
@@ -113,6 +113,9 @@ static int mod_child(int rank)
113 113
 	return 0;
114 114
 }
115 115
 
116
+The forked child process shall also update its local configuration,
117
+please read the section "Refreshing the configuration" in doc/cfg.txt.
118
+
116 119
 
117 120
 Summary
118 121
 -------
Browse code

Formatting and doxygen documentation updates

oej authored on 21/10/2009 08:21:47
Showing 1 changed files
... ...
@@ -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 48
 mod_child_init(PROC_INIT) is the first mod_child_init call made, and it's
45 49
  guaranteed to happen before any child process is forked. The process context
46 50
   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
51
+ more information: we know the number of SIP-router processes. This is the right
48 52
   place to initialize things like shared arrays[get_max_procs()].
49 53
 Note also that everything done here will be inherited in all the future
50 54
  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 56
 
53 57
 mod_child_init(PROC_MAIN) is another call that is done in the same "main"
54 58
  process context. This call happens just before initializing the main tcp
55
-  process. This is the only right place for forking more ser processes
59
+  process. This is the only right place for forking more SIP-router processes
56 60
   (see fork_process()). WARNING: the context is the same "main" process as
57 61
  for mod_child_init(PROC_INIT) and mod_init() so care must be taken not to
58 62
  initialize things twice or three times for the "main" process.
59 63
 
60 64
 Except for the "main" process case mod_child_init(rank) will be called only
61 65
 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
66
+ means the current process is a normal SIP-router process and a negative rank has
63 67
   some special meaning (grep PROC_ sr_module.h for more info).
64 68
 mod_child_init(rank) is the best place for initializing per process variables,
65 69
  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 76
 mod_child_init in the no-fork case
73 77
 ----------------------------------
74 78
 
75
-If ser is started in no-fork mode it will try to start as few processes as
79
+If SIP-router is started in no-fork mode it will try to start as few processes as
76 80
 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).
81
+2 timers). In this case mod_child_init() will be called 3 times in the
82
+same "main" process context: mod_child_init(PROC_INIT);
83
+mod_child_init(PROC_MAIN) and mod_child_init(1) (since the first process is
84
+also the "main" one).
81 85
 
82 86
 
83
-Forking new ser processes from a module
87
+Forking new SIP-router processes from a module
84 88
 ---------------------------------------
85 89
 
86 90
 static int mod_init()
... ...
@@ -133,8 +137,9 @@ mod_child_init(PROC_INIT)
133 137
   process.
134 138
 
135 139
 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()
140
+ - the only place from where another SIP-router process can be forked 
141
+   (see fork_process  ()), but remember first to register the number of 
142
+   to-be-forked processes in mod_init()
138 143
 
139 144
 mod_child_init(rank!=PROC_INIT && rank!=PROC_MAIN)
140 145
  - initialize other per process variables (e.g. different values), whose 
Browse code

- short module initialization functions description: what you should and shouldn't do in mod_init, child_init(PROC_MAIN), child_init(PROC_INIT) and child_int(other_values)

Andrei Pelinescu-Onciul authored on 07/06/2007 21:34:03
Showing 1 changed files
1 1
new file mode 100644
... ...
@@ -0,0 +1,149 @@
1
+#$Id$
2
+#
3
+# Module intialization description
4
+#
5
+# History
6
+#--------
7
+#  2007-06-07  created by Andrei Pelinescu <andrei@iptel.org>
8
+#
9
+
10
+
11
+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
+ not safe to do in mod_init and mod_child_init).
14
+
15
+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.
18
+
19
+mod_init
20
+--------
21
+
22
+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()).
28
+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).
30
+
31
+
32
+mod_child_init
33
+---------------
34
+
35
+mod_child_init is called for each forked ser process with 2 exceptions:
36
+ - 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
38
+
39
+mod_child_init is always called after mod_init. It takes one parameter, the
40
+ process rank. This parameter can be used to differentiate between normal
41
+  new-forked-process calls and some special calls.
42
+There are two very special rank values: PROC_INIT (as of 2007-06-06) and
43
+ PROC_MAIN:
44
+mod_child_init(PROC_INIT) is the first mod_child_init call made, and it's
45
+ guaranteed to happen before any child process is forked. The process context
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
48
+  place to initialize things like shared arrays[get_max_procs()].
49
+Note also that everything done here will be inherited in all the future
50
+ children processes (since it's executed in the "main" process context before
51
+ forking).
52
+
53
+mod_child_init(PROC_MAIN) is another call that is done in the same "main"
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
56
+  (see fork_process()). WARNING: the context is the same "main" process as
57
+ for mod_child_init(PROC_INIT) and mod_init() so care must be taken not to
58
+ initialize things twice or three times for the "main" process.
59
+
60
+Except for the "main" process case mod_child_init(rank) will be called only
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
63
+  some special meaning (grep PROC_ sr_module.h for more info).
64
+mod_child_init(rank) is the best place for initializing per process variables,
65
+ opening per process database connections, new sockets a.s.o. Note however
66
+ that several mod_child_init()s can execute in the same time (with the
67
+  PROC_INIT exceptions) so this is not a good place for initializing shared
68
+  memory variables.
69
+
70
+
71
+
72
+mod_child_init in the no-fork case
73
+----------------------------------
74
+
75
+If ser is started in no-fork mode it will try to start as few processes as
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).
81
+
82
+
83
+Forking new ser processes from a module
84
+---------------------------------------
85
+
86
+static int mod_init()
87
+{
88
+	register_procs(2); /* we want to create 2 extra processes */
89
+	return 0;
90
+}
91
+
92
+static int mod_child(int rank)
93
+{
94
+	int pid;
95
+	
96
+	if (rank==PROC_MAIN){
97
+		pid=fork_process(some_positive_number, "name", 1);
98
+		if (pid<0)
99
+			return -1; /* error */
100
+		else if (pid ==0){
101
+			/* child1_main_loop(); */
102
+		}else{ /* parent */
103
+			pid=fork_process(some_other_postivie_number, "name2", 1);
104
+			if (pid<0) 
105
+			    /* ... same as above */
106
+			...
107
+		}
108
+	}
109
+	return 0;
110
+}
111
+
112
+
113
+Summary
114
+-------
115
+
116
+mod_init():
117
+ - register the number of processes that will be forked from
118
+   mod_child_init(PROC_MAIN) (if any) , see register_procs().
119
+ - initialize things requiring higher privileges
120
+ - initialize per process variables with common value (they will be 
121
+   inherited by all the future children)
122
+ - initialize shared memory variables if possible (no need for things that
123
+   are available latter like the process count)
124
+
125
+mod_child_init(PROC_INIT)
126
+ - same as mod_init except for registering processes & privileged stuff
127
+ - the process number is now available so for example initializing shared 
128
+   per process statistics arrays (int stats[proc_no]) is possible
129
+ - guaranteed to be run before any process is forked (like mod_init()).
130
+
131
+  WARNING: same process context as mod_init() and mod_child_init(PROC_MAIN) so
132
+  care must be taken not to initialize things 2 or 3 times for the "main"
133
+  process.
134
+
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()
138
+
139
+mod_child_init(rank!=PROC_INIT && rank!=PROC_MAIN)
140
+ - initialize other per process variables (e.g. different values), whose 
141
+   initial values will be visible only in the current process (they won't
142
+   be inherited anymore).
143
+ - open per process db connections, sockets a.s.o.
144
+ - seed custom random generators
145
+ 
146
+  WARNINGs: - several mod_child_inits() can run in parallel
147
+            - the rank number is not necessarily unique
148
+ 
149
+ -