cfg_struct.h

/*
 * $Id$
 *
 * Copyright (C) 2007 iptelorg GmbH
 *
 * This file is part of SIP-router, a free SIP server.
 *
 * SIP-router is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version
 *
 * SIP-router is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 * History
 * -------
 *  2007-12-03  Initial version (Miklos)
 *  2008-01-24  dynamic groups are introduced in order to make
 *              variable declaration possible in the script (Miklos)
 */

#ifndef _CFG_STRUCT_H
#define _CFG_STRUCT_H

#include "../str.h"
#include "../atomic_ops.h"
#include "../mem/shm_mem.h"
#include "../locking.h"
#include "../compiler_opt.h"
#include "../bit_test.h"
#include "cfg.h"

#define CFG_MAX_VAR_NUM 256

#define cfg_var_shmized 1U

typedef struct _cfg_add_var {
        struct _cfg_add_var     *next;
        unsigned int    type;   
        union {
                char    *ch;
                str     s;
                int     i;
        } val;
        unsigned int    group_id; 
        int             name_len;       
        char            name[1];
} cfg_add_var_t;

typedef struct _cfg_mapping {
        cfg_def_t       *def;           
        int             name_len;       
        /* additional information about the cfg variable */
        int             pos;    
        int             offset; 
        unsigned int    flag;   
} cfg_mapping_t;

enum { CFG_GROUP_UNKNOWN = 0, CFG_GROUP_DYNAMIC, CFG_GROUP_STATIC };

typedef struct _cfg_group {
        int             num;            
        cfg_mapping_t   *mapping;       
        char            *vars;          
        cfg_add_var_t   *add_var;       
        int             size;           
        int             meta_offset;    
        int             var_offset;     
        void            **handle;       
        void            *orig_handle;   
        unsigned char   dynamic;        
        struct _cfg_group       *next;
        int             name_len;
        char            name[1];
} cfg_group_t;

typedef struct _cfg_group_inst {
        unsigned int    id;             
        unsigned int    set[CFG_MAX_VAR_NUM/(sizeof(int)*8)];
        unsigned char   vars[1];        
} cfg_group_inst_t;

typedef struct _cfg_group_meta {
        int                     num;    
        cfg_group_inst_t        *array; 
} cfg_group_meta_t;

typedef struct _cfg_block {
        atomic_t        refcnt;         
        unsigned char   vars[1];        
} cfg_block_t;

typedef struct _cfg_child_cb {
        atomic_t                refcnt; 
        atomic_t                cb_count;       
        str                     gname, name;    
        cfg_on_set_child        cb;             
        void                    **replaced;     
        struct _cfg_child_cb    *next;
} cfg_child_cb_t;

extern cfg_group_t      *cfg_group;
extern cfg_block_t      **cfg_global;
extern cfg_block_t      *cfg_local;
extern int              cfg_block_size;
extern gen_lock_t       *cfg_global_lock;
extern gen_lock_t       *cfg_writer_lock;
extern int              cfg_shmized;
extern cfg_child_cb_t   **cfg_child_cb_first;
extern cfg_child_cb_t   **cfg_child_cb_last;
extern cfg_child_cb_t   *cfg_child_cb;
extern int              cfg_ginst_count;

/* magic value for cfg_child_cb for processes that do not want to
   execute per-child callbacks */
#define CFG_NO_CHILD_CBS ((void*)(long)(-1))

/* macros for easier variable access */
#define CFG_VAR_TYPE(var)       CFG_VAR_MASK((var)->def->type)
#define CFG_INPUT_TYPE(var)     CFG_INPUT_MASK((var)->def->type)

/* get the meta-data of a group from the block */
#define CFG_GROUP_META(block, group) \
        ((cfg_group_meta_t *)((block)->vars + (group)->meta_offset))

/* get the data block of a group from the block */
#define CFG_GROUP_DATA(block, group) \
        ((unsigned char *)((block)->vars + (group)->var_offset))

/* Test whether a variable is explicitely set in the group instance,
 * or it uses the default value */
#define CFG_VAR_TEST(group_inst, var) \
        bit_test((var)->pos % (sizeof(int)*8), (group_inst)->set + (var)->pos/(sizeof(int)*8))

/* Test whether a variable is explicitely set in the group instance,
 * or it uses the default value, and set the flag. */
#define CFG_VAR_TEST_AND_SET(group_inst, var) \
        bit_test_and_set((var)->pos % (sizeof(int)*8), (group_inst)->set + (var)->pos/(sizeof(int)*8))

/* Test whether a variable is explicitely set in the group instance,
 * or it uses the default value, and reset the flag. */
#define CFG_VAR_TEST_AND_RESET(group_inst, var) \
        bit_test_and_reset((var)->pos % (sizeof(int)*8), (group_inst)->set + (var)->pos/(sizeof(int)*8))

/* Return the group instance pointer from a handle,
 * or NULL if the handle points to the default configuration block */
#define CFG_HANDLE_TO_GINST(h) \
        ( (((unsigned char*)(h) < cfg_local->vars) \
                || ((unsigned char*)(h) > cfg_local->vars + cfg_block_size) \
        ) ? \
                (cfg_group_inst_t*)((char*)(h) - (unsigned long)&((cfg_group_inst_t *)0)->vars) \
                : NULL )

/* initiate the cfg framework */
int sr_cfg_init(void);

/* destroy the memory allocated for the cfg framework */
void cfg_destroy(void);

/* Register num number of child processes that will
 * keep updating their local configuration.
 * This function needs to be called from mod_init
 * before any child process is forked.
 */
void cfg_register_child(int num);

/* per-child process init function.
 * It needs to be called from the forked process.
 * cfg_register_child() must be called before this function!
 */
int cfg_child_init(void);

/* Child process init function that can be called
 * without cfg_register_child().
 * Note that the child process may miss some configuration changes.
 */
int cfg_late_child_init(void);

/* per-child init function for non-cb executing processes.
 * Mark this process as not wanting to execute any per-child config
 * callback (it will have only limited config functionality, but is useful
 * when a process needs only to watch some non-callback cfg. values,
 * e.g. the main attendant process, debug and memlog).
 * It needs to be called from the forked process.
 * cfg_register_child must _not_ be called.
 */
int cfg_child_no_cb_init(void);

/* per-child process destroy function
 * Should be called only when the child process exits,
 * but SER continues running.
 *
 * WARNING: this function call must be the very last action
 * before the child process exits, because the local config
 * is not available afterwards.
 */
void cfg_child_destroy(void);

/* creates a new cfg group, and adds it to the linked list */
cfg_group_t *cfg_new_group(char *name, int name_len,
                int num, cfg_mapping_t *mapping,
                char *vars, int size, void **handle);

/* Set the values of an existing cfg group. */
void cfg_set_group(cfg_group_t *group,
                int num, cfg_mapping_t *mapping,
                char *vars, int size, void **handle);

/* copy the variables to shm mem */
int cfg_shmize(void);

/* free the memory of a child cb structure */
static inline void cfg_child_cb_free_item(cfg_child_cb_t *cb)
{
        int     i;

        /* free the changed variables */
        if (cb->replaced) {
                for (i=0; cb->replaced[i]; i++)
                        shm_free(cb->replaced[i]);
                shm_free(cb->replaced);
        }
        shm_free(cb);
}

#define cfg_block_free(block) \
        shm_free(block)

/* Move the group handle to the specified group instance pointed by dst_ginst.
 * src_ginst shall point to the active group instance.
 * Both parameters can be NULL meaning that the src/dst config is the default, 
 * not an additional group instance.
 * The function executes all the per-child process callbacks which are different
 * in the two instaces.
 */
void cfg_move_handle(cfg_group_t *group, cfg_group_inst_t *src_ginst, cfg_group_inst_t *dst_ginst);


/* lock and unlock the global cfg block -- used only at the
 * very last step when the block is replaced */
#define CFG_LOCK()      lock_get(cfg_global_lock);
#define CFG_UNLOCK()    lock_release(cfg_global_lock);

/* lock and unlock used by the cfg drivers to make sure that
 * only one driver process is considering replacing the global
 * cfg block */
#define CFG_WRITER_LOCK()       lock_get(cfg_writer_lock);
#define CFG_WRITER_UNLOCK()     lock_release(cfg_writer_lock);

/* increase and decrease the reference counter of a block */
#define CFG_REF(block) \
        atomic_inc(&(block)->refcnt)

#define CFG_UNREF(block) \
        do { \
                if (atomic_dec_and_test(&(block)->refcnt)) \
                        cfg_block_free(block); \
        } while(0)

/* updates all the module handles and calls the
 * per-child process callbacks -- not intended to be used
 * directly, use cfg_update() instead!
 * params:
 *   no_cbs - if 1, do not call per child callbacks
 */
static inline void cfg_update_local(int no_cbs)
{
        cfg_group_t     *group;
        cfg_child_cb_t  *last_cb;
        cfg_child_cb_t  *prev_cb;

        if (cfg_local) CFG_UNREF(cfg_local);
        CFG_LOCK();
        CFG_REF(*cfg_global);
        cfg_local = *cfg_global;
        /* the value of the last callback must be read within the lock */
        last_cb = *cfg_child_cb_last;

        /* I unlock now, because the child process can update its own private
        config without the lock held. In the worst case, the process will get the
        lock once more to set cfg_child_cb_first, but only one of the child
        processes will do so, and only if a value, that has per-child process
        callback defined, was changed. */
        CFG_UNLOCK();

        /* update the handles */
        for (   group = cfg_group;
                group;
                group = group->next
        )
                *(group->handle) = CFG_GROUP_DATA(cfg_local, group);

        if (unlikely(cfg_child_cb==CFG_NO_CHILD_CBS || no_cbs))
                return;
        /* call the per-process callbacks */
        while (cfg_child_cb != last_cb) {
                prev_cb = cfg_child_cb;
                cfg_child_cb = cfg_child_cb->next;
                atomic_inc(&cfg_child_cb->refcnt);
                if (atomic_dec_and_test(&prev_cb->refcnt)) {
                        /* No more pocess refers to this callback.
                        Did this process block the deletion,
                        or is there any other process that has not
                        reached prev_cb yet? */
                        CFG_LOCK();
                        if (*cfg_child_cb_first == prev_cb) {
                                /* yes, this process was blocking the deletion */
                                *cfg_child_cb_first = cfg_child_cb;
                                CFG_UNLOCK();
                                cfg_child_cb_free_item(prev_cb);
                        } else {
                                CFG_UNLOCK();
                        }
                }
                if (cfg_child_cb->cb
                        && (atomic_add(&cfg_child_cb->cb_count, -1) >= 0) /* the new value is returned
                                                                        by atomic_add() */
                )
                        /* execute the callback */
                        cfg_child_cb->cb(&cfg_child_cb->gname, &cfg_child_cb->name);
                /* else the callback no longer needs to be executed */
        }
}

/* Reset all the group handles to the default, local configuration */
static inline void cfg_reset_handles(void)
{
        cfg_group_t     *group;

        if (!cfg_local)
                return;

        for (   group = cfg_group;
                group && cfg_ginst_count; /* cfg_ginst_count is decreased every time
                                        a group handle is reset. When it reaches 0,
                                        needless to continue the loop */
                group = group->next
        ) {
                if (((unsigned char*)*(group->handle) < cfg_local->vars)
                        || ((unsigned char*)*(group->handle) > cfg_local->vars + cfg_block_size)
                )
                        cfg_move_handle(group,
                                        CFG_HANDLE_TO_GINST(*(group->handle)),
                                        NULL);
        }
}

/* sets the local cfg block to the active block
 * 
 * If your module forks a new process that implements
 * an infinite loop, put cfg_update() to the beginning of
 * the cycle to make sure, that subsequent function calls see the
 * up-to-date config set.
 */
#define cfg_update() \
        do { \
                if (unlikely(cfg_ginst_count)) \
                        cfg_reset_handles(); \
                if (unlikely(cfg_local != *cfg_global)) \
                        cfg_update_local(0); \
        } while(0)

/* like cfg_update(), but does not execute callbacks
 * (it should be used sparingly only in special cases, since it
 *  breaks an important cfg framework feature)
 */
#define cfg_update_no_cbs() \
        do { \
                if (unlikely(cfg_local != *cfg_global)) \
                        cfg_update_local(1); \
        } while(0)

/* Reset all the group handles in the child process,
 * i.e. move them back to the default local configuration.
 */
#define cfg_reset_all() \
        do { \
                if (unlikely(cfg_ginst_count)) \
                        cfg_reset_handles(); \
        } while(0)


/* searches a group by name */
cfg_group_t *cfg_lookup_group(char *name, int len);
        
/* searches a variable definition by group and variable name */
int cfg_lookup_var(str *gname, str *vname,
                        cfg_group_t **group, cfg_mapping_t **var);

/* searches a variable definition within a group by its name */
cfg_mapping_t *cfg_lookup_var2(cfg_group_t *group, char *name, int len);

/* clones the global config block
 * WARNING: unsafe, cfg_writer_lock or cfg_global_lock must be held!
 */
cfg_block_t *cfg_clone_global(void);

/* Clone an array of configuration group instances. */
cfg_group_inst_t *cfg_clone_array(cfg_group_meta_t *meta, cfg_group_t *group);

/* Extend the array of configuration group instances with one more instance.
 * Only the ID of the new group is set, nothing else. */
cfg_group_inst_t *cfg_extend_array(cfg_group_meta_t *meta, cfg_group_t *group,
                                unsigned int group_id,
                                cfg_group_inst_t **new_group);

/* Remove an instance from a group array.
 * inst must point to an instance within meta->array.
 * *_new_array is set to the newly allocated array. */
int cfg_collapse_array(cfg_group_meta_t *meta, cfg_group_t *group,
                                cfg_group_inst_t *inst,
                                cfg_group_inst_t **_new_array);

/* clones a string to shared memory */
int cfg_clone_str(str *src, str *dst);

/* Find the group instance within the meta-data based on the group_id */
cfg_group_inst_t *cfg_find_group(cfg_group_meta_t *meta, int group_size, unsigned int group_id);

/* append new callbacks to the end of the child callback list
 *
 * WARNING: the function is unsafe, either hold CFG_LOCK(),
 * or call the function before forking
 */
void cfg_install_child_cb(cfg_child_cb_t *cb_first, cfg_child_cb_t *cb_last);

/* installs a new global config
 *
 * replaced is an array of strings that must be freed together
 * with the previous global config.
 * cb_first and cb_last define a linked list of per-child process
 * callbacks. This list is added to the global linked list.
 */
void cfg_install_global(cfg_block_t *block, void **replaced,
                        cfg_child_cb_t *cb_first, cfg_child_cb_t *cb_last);

/* creates a structure for a per-child process callback */
cfg_child_cb_t *cfg_child_cb_new(str *gname, str *name,
                        cfg_on_set_child cb,
                        unsigned int type);

/* free the memory allocated for a child cb list */
void cfg_child_cb_free_list(cfg_child_cb_t *child_cb_first);

/* Allocate memory for a new additional variable
 * and link it to a configuration group.
 * type==0 results in creating a new group instance with the default values.
 * The group is created with CFG_GROUP_UNKNOWN type if it does not exist.
 * Note: this function is usable only before the configuration is shmized.
 */
int new_add_var(str *group_name, unsigned int group_id, str *var_name,
                                void *val, unsigned int type);

/* Move the group handle to the specified group instance. */
int cfg_select(cfg_group_t *group, unsigned int id);

/* Reset the group handle to the default, local configuration */
int cfg_reset(cfg_group_t *group);

/* Move the group handle to the first group instance.
 * This function together with cfg_select_next() can be used
 * to iterate though the list of instances.
 *
 * Return value:
 *      -1: no group instance found
 *       0: first group instance is successfully selected.
 */
int cfg_select_first(cfg_group_t *group);

/* Move the group handle to the next group instance.
 * This function together with cfg_select_first() can be used
 * to iterate though the list of instances.
 *
 * Return value:
 *      -1: no more group instance found. Note, that the active group
 *              instance is not changed in this case.
 *       0: the next group instance is successfully selected.
 */
int cfg_select_next(cfg_group_t *group);

/* Temporary set the local configuration in the main process before forking.
 * This makes the group instances usable in the main process after
 * the configuration is shmized, but before the children are forked.
 */
void cfg_main_set_local(void);

/* Reset the local configuration of the main process back to its original state
 * to make sure that the forked processes are not affected.
 */
void cfg_main_reset_local(void);

#endif /* _CFG_STRUCT_H */