all: updated FSF address in GPL text
[sip-router] / cfg / cfg_struct.h
1 /*
2  * $Id$
3  *
4  * Copyright (C) 2007 iptelorg GmbH
5  *
6  * This file is part of SIP-router, a free SIP server.
7  *
8  * SIP-router is free software; you can redistribute it and/or modify
9  * it under the terms of the GNU General Public License as published by
10  * the Free Software Foundation; either version 2 of the License, or
11  * (at your option) any later version
12  *
13  * SIP-router is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16  * GNU General Public License for more details.
17  *
18  * You should have received a copy of the GNU General Public License
19  * along with this program; if not, write to the Free Software
20  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
21  *
22  * History
23  * -------
24  *  2007-12-03  Initial version (Miklos)
25  *  2008-01-24  dynamic groups are introduced in order to make
26  *              variable declaration possible in the script (Miklos)
27  */
28
29 #ifndef _CFG_STRUCT_H
30 #define _CFG_STRUCT_H
31
32 #include "../str.h"
33 #include "../atomic_ops.h"
34 #include "../mem/shm_mem.h"
35 #include "../locking.h"
36 #include "../compiler_opt.h"
37 #include "../bit_test.h"
38 #include "cfg.h"
39
40 /*! \brief Maximum number of variables within a configuration group. */
41 #define CFG_MAX_VAR_NUM 256
42
43 /*! \brief indicates that the variable has been already shmized */
44 #define cfg_var_shmized 1U
45
46 /*! \brief Structure for storing additional values of a variable.
47  * When the config is shmzied, these variables are combined in
48  * an array.
49  */
50 typedef struct _cfg_add_var {
51         struct _cfg_add_var     *next;
52         unsigned int    type;   /*!< type == 0 is also valid, it indicates that the group
53                                 must be created with the default values */
54         union {
55                 char    *ch;
56                 str     s;
57                 int     i;
58         } val;
59         unsigned int    group_id; /*!< Id of the group instance */
60         int             name_len;       /*!< Name of the variable. The variable may not be known,
61                                         for example the additional group value is set in the script
62                                         before the cfg group is declared. Hence, the pointer cannot
63                                         be stored here. */
64         char            name[1];
65 } cfg_add_var_t;
66
67 /*! \brief structure used for variable - pointer mapping */
68 typedef struct _cfg_mapping {
69         cfg_def_t       *def;           /*!< one item of the cfg structure definition */
70         int             name_len;       /*!< length of def->name */
71
72         /* additional information about the cfg variable */
73         int             pos;    /*!< position of the variable within the group starting from 0 */
74         int             offset; /*!< offest within the memory block */
75         unsigned int    flag;   /*!< flag indicating the state of the variable */
76 } cfg_mapping_t;
77
78 /*! \brief type of the group */
79 enum { CFG_GROUP_UNKNOWN = 0, CFG_GROUP_DYNAMIC, CFG_GROUP_STATIC };
80
81 /*! \brief linked list of registered groups */
82 typedef struct _cfg_group {
83         int             num;            /*!< number of variables within the group */
84         cfg_mapping_t   *mapping;       /*!< describes the mapping betweeen
85                                         the cfg variable definition and the memory block */
86         char            *vars;          /*!< pointer to the memory block where the values
87                                         are stored -- used only before the config is
88                                         shmized. */
89         cfg_add_var_t   *add_var;       /*!< Additional instances of the variables.
90                                         This linked list is used only before the config is
91                                         shmized. */
92         int             size;           /*!< size of the memory block that has to be
93                                         allocated to store the values */
94         int             meta_offset;    /*!< offset of the group within the
95                                         shmized memory block for the meta_data */
96         int             var_offset;     /*!< offset of the group within the
97                                         shmized memory block for the variables */
98         void            **handle;       /*!< per-process handle that can be used
99                                         by the modules to access the variables.
100                                         It is registered when the group is created,
101                                         and updated every time the block is replaced */
102         void            *orig_handle;   /*!< Original value that the handle points to
103                                         when the config group is registered. This is needed
104                                         to temporary set the handle in the main process and
105                                         restore it later to its original value. */
106
107         unsigned char   dynamic;        /*!< indicates whether the variables within the group
108                                         are dynamically allocated or not */
109         struct _cfg_group       *next;
110         int             name_len;
111         char            name[1];
112 } cfg_group_t;
113
114 /*! \brief One instance of the cfg group variables which stores
115  * the additional values. These values can overwrite the default values. */
116 typedef struct _cfg_group_inst {
117         unsigned int    id;             /*!< identifier of the group instance */
118         unsigned int    set[CFG_MAX_VAR_NUM/(sizeof(int)*8)];
119                                         /*!< Bitmap indicating whether or not a value is explicitely set
120                                         within this instance. If the value is not set,
121                                         then the default value is used, and copied into this instance. */
122         unsigned char   vars[1];        /*!< block for the values */
123 } cfg_group_inst_t;
124
125 /*! \brief Meta-data which is stored before each variable group
126  * within the blob. This structure is used to handle the multivalue
127  * instances of the variables, i.e. manages the array for the
128  * additional values. */
129 typedef struct _cfg_group_meta {
130         int                     num;    /*!< Number of items in the array */
131         cfg_group_inst_t        *array; /*!< Array of cfg groups with num number of items */
132 } cfg_group_meta_t;
133
134 /*! \brief single memoy block that contains all the cfg values */
135 typedef struct _cfg_block {
136         atomic_t        refcnt;         /*!< reference counter,
137                                         the block is automatically deleted
138                                         when it reaches 0 */
139         unsigned char   vars[1];        /*!< blob that contains the values */
140 } cfg_block_t;
141
142 /*! \brief Linked list of per-child process callbacks.
143  * Each child process has a local pointer, and executes the callbacks
144  * when the pointer is not pointing to the end of the list.
145  * Items from the begginning of the list are deleted when the starter
146  * pointer is moved, and no more child process uses them.
147  */
148 typedef struct _cfg_child_cb {
149         atomic_t                refcnt; /*!< number of child processes
150                                         referring to the element */
151         atomic_t                cb_count;       /*!< This counter is used to track
152                                                  * how many times the callback needs
153                                                  * to be executed.
154                                                  * >0 the cb needs to be executed
155                                                  * <=0 the cb no longer needs to be executed
156                                                  */
157         str                     gname, name;    /*!< name of the variable that has changed */
158         cfg_on_set_child        cb;             /*!< callback function that has to be called */
159         void                    **replaced;     /*!< set of strings and other memory segments
160                                                 that must be freed together with this structure.
161                                                 The content depends on the new config block.
162                                                 This makes sure that the replaced strings are freed
163                                                 after all the child processes release the old configuration. */
164
165         struct _cfg_child_cb    *next;
166 } cfg_child_cb_t;
167
168 extern cfg_group_t      *cfg_group;
169 extern cfg_block_t      **cfg_global;
170 extern cfg_block_t      *cfg_local;
171 extern int              cfg_block_size;
172 extern gen_lock_t       *cfg_global_lock;
173 extern gen_lock_t       *cfg_writer_lock;
174 extern int              cfg_shmized;
175 extern cfg_child_cb_t   **cfg_child_cb_first;
176 extern cfg_child_cb_t   **cfg_child_cb_last;
177 extern cfg_child_cb_t   *cfg_child_cb;
178 extern int              cfg_ginst_count;
179
180 /* magic value for cfg_child_cb for processes that do not want to
181    execute per-child callbacks */
182 #define CFG_NO_CHILD_CBS ((void*)(long)(-1))
183
184 /* macros for easier variable access */
185 #define CFG_VAR_TYPE(var)       CFG_VAR_MASK((var)->def->type)
186 #define CFG_INPUT_TYPE(var)     CFG_INPUT_MASK((var)->def->type)
187
188 /* get the meta-data of a group from the block */
189 #define CFG_GROUP_META(block, group) \
190         ((cfg_group_meta_t *)((block)->vars + (group)->meta_offset))
191
192 /* get the data block of a group from the block */
193 #define CFG_GROUP_DATA(block, group) \
194         ((unsigned char *)((block)->vars + (group)->var_offset))
195
196 /* Test whether a variable is explicitely set in the group instance,
197  * or it uses the default value */
198 #define CFG_VAR_TEST(group_inst, var) \
199         bit_test((var)->pos % (sizeof(int)*8), (group_inst)->set + (var)->pos/(sizeof(int)*8))
200
201 /* Test whether a variable is explicitely set in the group instance,
202  * or it uses the default value, and set the flag. */
203 #define CFG_VAR_TEST_AND_SET(group_inst, var) \
204         bit_test_and_set((var)->pos % (sizeof(int)*8), (group_inst)->set + (var)->pos/(sizeof(int)*8))
205
206 /* Test whether a variable is explicitely set in the group instance,
207  * or it uses the default value, and reset the flag. */
208 #define CFG_VAR_TEST_AND_RESET(group_inst, var) \
209         bit_test_and_reset((var)->pos % (sizeof(int)*8), (group_inst)->set + (var)->pos/(sizeof(int)*8))
210
211 /* Return the group instance pointer from a handle,
212  * or NULL if the handle points to the default configuration block */
213 #define CFG_HANDLE_TO_GINST(h) \
214         ( (((unsigned char*)(h) < cfg_local->vars) \
215                 || ((unsigned char*)(h) > cfg_local->vars + cfg_block_size) \
216         ) ? \
217                 (cfg_group_inst_t*)((char*)(h) - (unsigned long)&((cfg_group_inst_t *)0)->vars) \
218                 : NULL )
219
220 /* initiate the cfg framework */
221 int sr_cfg_init(void);
222
223 /* destroy the memory allocated for the cfg framework */
224 void cfg_destroy(void);
225
226 /* Register num number of child processes that will
227  * keep updating their local configuration.
228  * This function needs to be called from mod_init
229  * before any child process is forked.
230  */
231 void cfg_register_child(int num);
232
233 /* per-child process init function.
234  * It needs to be called from the forked process.
235  * cfg_register_child() must be called before this function!
236  */
237 int cfg_child_init(void);
238
239 /* Child process init function that can be called
240  * without cfg_register_child().
241  * Note that the child process may miss some configuration changes.
242  */
243 int cfg_late_child_init(void);
244
245 /* per-child init function for non-cb executing processes.
246  * Mark this process as not wanting to execute any per-child config
247  * callback (it will have only limited config functionality, but is useful
248  * when a process needs only to watch some non-callback cfg. values,
249  * e.g. the main attendant process, debug and memlog).
250  * It needs to be called from the forked process.
251  * cfg_register_child must _not_ be called.
252  */
253 int cfg_child_no_cb_init(void);
254
255 /* per-child process destroy function
256  * Should be called only when the child process exits,
257  * but SER continues running.
258  *
259  * WARNING: this function call must be the very last action
260  * before the child process exits, because the local config
261  * is not available afterwards.
262  */
263 void cfg_child_destroy(void);
264
265 /* creates a new cfg group, and adds it to the linked list */
266 cfg_group_t *cfg_new_group(char *name, int name_len,
267                 int num, cfg_mapping_t *mapping,
268                 char *vars, int size, void **handle);
269
270 /* Set the values of an existing cfg group. */
271 void cfg_set_group(cfg_group_t *group,
272                 int num, cfg_mapping_t *mapping,
273                 char *vars, int size, void **handle);
274
275 /* copy the variables to shm mem */
276 int cfg_shmize(void);
277
278 /* free the memory of a child cb structure */
279 static inline void cfg_child_cb_free_item(cfg_child_cb_t *cb)
280 {
281         int     i;
282
283         /* free the changed variables */
284         if (cb->replaced) {
285                 for (i=0; cb->replaced[i]; i++)
286                         shm_free(cb->replaced[i]);
287                 shm_free(cb->replaced);
288         }
289         shm_free(cb);
290 }
291
292 #define cfg_block_free(block) \
293         shm_free(block)
294
295 /* Move the group handle to the specified group instance pointed by dst_ginst.
296  * src_ginst shall point to the active group instance.
297  * Both parameters can be NULL meaning that the src/dst config is the default, 
298  * not an additional group instance.
299  * The function executes all the per-child process callbacks which are different
300  * in the two instaces.
301  */
302 void cfg_move_handle(cfg_group_t *group, cfg_group_inst_t *src_ginst, cfg_group_inst_t *dst_ginst);
303
304
305 /* lock and unlock the global cfg block -- used only at the
306  * very last step when the block is replaced */
307 #define CFG_LOCK()      lock_get(cfg_global_lock);
308 #define CFG_UNLOCK()    lock_release(cfg_global_lock);
309
310 /* lock and unlock used by the cfg drivers to make sure that
311  * only one driver process is considering replacing the global
312  * cfg block */
313 #define CFG_WRITER_LOCK()       lock_get(cfg_writer_lock);
314 #define CFG_WRITER_UNLOCK()     lock_release(cfg_writer_lock);
315
316 /* increase and decrease the reference counter of a block */
317 #define CFG_REF(block) \
318         atomic_inc(&(block)->refcnt)
319
320 #define CFG_UNREF(block) \
321         do { \
322                 if (atomic_dec_and_test(&(block)->refcnt)) \
323                         cfg_block_free(block); \
324         } while(0)
325
326 /* updates all the module handles and calls the
327  * per-child process callbacks -- not intended to be used
328  * directly, use cfg_update() instead!
329  * params:
330  *   no_cbs - if 1, do not call per child callbacks
331  */
332 static inline void cfg_update_local(int no_cbs)
333 {
334         cfg_group_t     *group;
335         cfg_child_cb_t  *last_cb;
336         cfg_child_cb_t  *prev_cb;
337
338         if (cfg_local) CFG_UNREF(cfg_local);
339         CFG_LOCK();
340         CFG_REF(*cfg_global);
341         cfg_local = *cfg_global;
342         /* the value of the last callback must be read within the lock */
343         last_cb = *cfg_child_cb_last;
344
345         /* I unlock now, because the child process can update its own private
346         config without the lock held. In the worst case, the process will get the
347         lock once more to set cfg_child_cb_first, but only one of the child
348         processes will do so, and only if a value, that has per-child process
349         callback defined, was changed. */
350         CFG_UNLOCK();
351
352         /* update the handles */
353         for (   group = cfg_group;
354                 group;
355                 group = group->next
356         )
357                 *(group->handle) = CFG_GROUP_DATA(cfg_local, group);
358
359         if (unlikely(cfg_child_cb==CFG_NO_CHILD_CBS || no_cbs))
360                 return;
361         /* call the per-process callbacks */
362         while (cfg_child_cb != last_cb) {
363                 prev_cb = cfg_child_cb;
364                 cfg_child_cb = cfg_child_cb->next;
365                 atomic_inc(&cfg_child_cb->refcnt);
366                 if (atomic_dec_and_test(&prev_cb->refcnt)) {
367                         /* No more pocess refers to this callback.
368                         Did this process block the deletion,
369                         or is there any other process that has not
370                         reached prev_cb yet? */
371                         CFG_LOCK();
372                         if (*cfg_child_cb_first == prev_cb) {
373                                 /* yes, this process was blocking the deletion */
374                                 *cfg_child_cb_first = cfg_child_cb;
375                                 CFG_UNLOCK();
376                                 cfg_child_cb_free_item(prev_cb);
377                         } else {
378                                 CFG_UNLOCK();
379                         }
380                 }
381                 if (cfg_child_cb->cb
382                         && (atomic_add(&cfg_child_cb->cb_count, -1) >= 0) /* the new value is returned
383                                                                         by atomic_add() */
384                 )
385                         /* execute the callback */
386                         cfg_child_cb->cb(&cfg_child_cb->gname, &cfg_child_cb->name);
387                 /* else the callback no longer needs to be executed */
388         }
389 }
390
391 /* Reset all the group handles to the default, local configuration */
392 static inline void cfg_reset_handles(void)
393 {
394         cfg_group_t     *group;
395
396         if (!cfg_local)
397                 return;
398
399         for (   group = cfg_group;
400                 group && cfg_ginst_count; /* cfg_ginst_count is decreased every time
401                                         a group handle is reset. When it reaches 0,
402                                         needless to continue the loop */
403                 group = group->next
404         ) {
405                 if (((unsigned char*)*(group->handle) < cfg_local->vars)
406                         || ((unsigned char*)*(group->handle) > cfg_local->vars + cfg_block_size)
407                 )
408                         cfg_move_handle(group,
409                                         CFG_HANDLE_TO_GINST(*(group->handle)),
410                                         NULL);
411         }
412 }
413
414 /* sets the local cfg block to the active block
415  * 
416  * If your module forks a new process that implements
417  * an infinite loop, put cfg_update() to the beginning of
418  * the cycle to make sure, that subsequent function calls see the
419  * up-to-date config set.
420  */
421 #define cfg_update() \
422         do { \
423                 if (unlikely(cfg_ginst_count)) \
424                         cfg_reset_handles(); \
425                 if (unlikely(cfg_local != *cfg_global)) \
426                         cfg_update_local(0); \
427         } while(0)
428
429 /* like cfg_update(), but does not execute callbacks
430  * (it should be used sparingly only in special cases, since it
431  *  breaks an important cfg framework feature)
432  */
433 #define cfg_update_no_cbs() \
434         do { \
435                 if (unlikely(cfg_local != *cfg_global)) \
436                         cfg_update_local(1); \
437         } while(0)
438
439 /* Reset all the group handles in the child process,
440  * i.e. move them back to the default local configuration.
441  */
442 #define cfg_reset_all() \
443         do { \
444                 if (unlikely(cfg_ginst_count)) \
445                         cfg_reset_handles(); \
446         } while(0)
447
448
449 /* searches a group by name */
450 cfg_group_t *cfg_lookup_group(char *name, int len);
451         
452 /* searches a variable definition by group and variable name */
453 int cfg_lookup_var(str *gname, str *vname,
454                         cfg_group_t **group, cfg_mapping_t **var);
455
456 /* searches a variable definition within a group by its name */
457 cfg_mapping_t *cfg_lookup_var2(cfg_group_t *group, char *name, int len);
458
459 /* clones the global config block
460  * WARNING: unsafe, cfg_writer_lock or cfg_global_lock must be held!
461  */
462 cfg_block_t *cfg_clone_global(void);
463
464 /* Clone an array of configuration group instances. */
465 cfg_group_inst_t *cfg_clone_array(cfg_group_meta_t *meta, cfg_group_t *group);
466
467 /* Extend the array of configuration group instances with one more instance.
468  * Only the ID of the new group is set, nothing else. */
469 cfg_group_inst_t *cfg_extend_array(cfg_group_meta_t *meta, cfg_group_t *group,
470                                 unsigned int group_id,
471                                 cfg_group_inst_t **new_group);
472
473 /* Remove an instance from a group array.
474  * inst must point to an instance within meta->array.
475  * *_new_array is set to the newly allocated array. */
476 int cfg_collapse_array(cfg_group_meta_t *meta, cfg_group_t *group,
477                                 cfg_group_inst_t *inst,
478                                 cfg_group_inst_t **_new_array);
479
480 /* clones a string to shared memory */
481 int cfg_clone_str(str *src, str *dst);
482
483 /* Find the group instance within the meta-data based on the group_id */
484 cfg_group_inst_t *cfg_find_group(cfg_group_meta_t *meta, int group_size, unsigned int group_id);
485
486 /* append new callbacks to the end of the child callback list
487  *
488  * WARNING: the function is unsafe, either hold CFG_LOCK(),
489  * or call the function before forking
490  */
491 void cfg_install_child_cb(cfg_child_cb_t *cb_first, cfg_child_cb_t *cb_last);
492
493 /* installs a new global config
494  *
495  * replaced is an array of strings that must be freed together
496  * with the previous global config.
497  * cb_first and cb_last define a linked list of per-child process
498  * callbacks. This list is added to the global linked list.
499  */
500 void cfg_install_global(cfg_block_t *block, void **replaced,
501                         cfg_child_cb_t *cb_first, cfg_child_cb_t *cb_last);
502
503 /* creates a structure for a per-child process callback */
504 cfg_child_cb_t *cfg_child_cb_new(str *gname, str *name,
505                         cfg_on_set_child cb,
506                         unsigned int type);
507
508 /* free the memory allocated for a child cb list */
509 void cfg_child_cb_free_list(cfg_child_cb_t *child_cb_first);
510
511 /* Allocate memory for a new additional variable
512  * and link it to a configuration group.
513  * type==0 results in creating a new group instance with the default values.
514  * The group is created with CFG_GROUP_UNKNOWN type if it does not exist.
515  * Note: this function is usable only before the configuration is shmized.
516  */
517 int new_add_var(str *group_name, unsigned int group_id, str *var_name,
518                                 void *val, unsigned int type);
519
520 /* Move the group handle to the specified group instance. */
521 int cfg_select(cfg_group_t *group, unsigned int id);
522
523 /* Reset the group handle to the default, local configuration */
524 int cfg_reset(cfg_group_t *group);
525
526 /* Move the group handle to the first group instance.
527  * This function together with cfg_select_next() can be used
528  * to iterate though the list of instances.
529  *
530  * Return value:
531  *      -1: no group instance found
532  *       0: first group instance is successfully selected.
533  */
534 int cfg_select_first(cfg_group_t *group);
535
536 /* Move the group handle to the next group instance.
537  * This function together with cfg_select_first() can be used
538  * to iterate though the list of instances.
539  *
540  * Return value:
541  *      -1: no more group instance found. Note, that the active group
542  *              instance is not changed in this case.
543  *       0: the next group instance is successfully selected.
544  */
545 int cfg_select_next(cfg_group_t *group);
546
547 /* Temporary set the local configuration in the main process before forking.
548  * This makes the group instances usable in the main process after
549  * the configuration is shmized, but before the children are forked.
550  */
551 void cfg_main_set_local(void);
552
553 /* Reset the local configuration of the main process back to its original state
554  * to make sure that the forked processes are not affected.
555  */
556 void cfg_main_reset_local(void);
557
558 #endif /* _CFG_STRUCT_H */