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
+ -