X-Git-Url: http://mj.ucw.cz/gitweb/?a=blobdiff_plain;f=ucw%2Fconf.h;h=0ff991309f146bfb1505c77ed7fa9a2d23219239;hb=841068939a49153d682f15e8fefa1d950f7179c0;hp=a387f274d57966818aa0c9e76d3bb6c36ae886ab;hpb=b3d3d2847cb34363c5e7a5a6bf8155b710d7afcd;p=libucw.git diff --git a/ucw/conf.h b/ucw/conf.h index a387f274..0ff99130 100644 --- a/ucw/conf.h +++ b/ucw/conf.h @@ -24,7 +24,7 @@ struct mempool; * One such context is automatically created during initialization of the library * and you need not care about more, as long as you use a single configuration file. * - * In full generality, you can define as many context as you wish and switch + * In full generality, you can define as many contexts as you wish and switch * between them. Each thread has its own pointer to the current context, which * must not be shared with other threads. ***/ @@ -41,7 +41,7 @@ struct cf_context *cf_new_context(void); * of the context is freed, which includes memory obtained by calls to * cf_malloc(). **/ -void cf_free_context(struct cf_context *cc); +void cf_delete_context(struct cf_context *cc); /** * Make the given configuration context current and return the previously @@ -63,6 +63,7 @@ struct cf_context *cf_switch_context(struct cf_context *cc); * configuration specified in the file are undone. **/ int cf_load(const char *file); + /** * Reload configuration from @file, replace the old one. * If @file is NULL, reload all loaded configuration files and re-apply @@ -71,6 +72,7 @@ int cf_load(const char *file); * settings are rolled back to the state before calling this function. **/ int cf_reload(const char *file); + /** * Parse some part of configuration passed in @string. * The syntax is the same as in the <>. @@ -97,6 +99,12 @@ void cf_open_group(void); **/ int cf_close_group(void); +/** + * Return all configuration items to their initial state before loading the + * configuration file. If journalling is disabled, it does nothing. + **/ +void cf_revert(void); + /*** === Data types [[conf_types]] ***/ enum cf_class { /** Class of the configuration item. **/ @@ -400,6 +408,9 @@ struct cf_section { /** A section. **/ * reloaded or rolled back, or the context is deleted, it gets lost). * * Memory allocated from within custom parsers should be allocated from the pools. + * + * Please note that the pool is not guaranteed to exist before you call cf_load(), + * cf_set(), or cf_getopt() on the particular context. ***/ struct mempool *cf_get_pool(void); /** Return a pointer to the current configuration pool. **/ void *cf_malloc(uns size); /** Returns @size bytes of memory allocated from the current configuration pool. **/ @@ -412,16 +423,21 @@ char *cf_printf(const char *fmt, ...) FORMAT_CHECK(printf,1,2); /** printf() int * Undo journal * ~~~~~~~~~~~~ * - * The configuration system uses journaling to safely reload - * configuration. It begins a transaction and tries to load the - * configuration. If it fails, it restores the original state. + * The configuration system uses a simple journaling mechanism, which makes + * it possible to undo changes to configuration. A typical example is loading + * of configuration by cf_load(): internally, it creates a transaction, applies + * all changes specified by the configuration and if one of them fails, the whole + * journal is replayed to restore the whole original state. Similarly, cf_reload() + * uses the journal to switch between configurations. * - * The behaviour of journal is described in <>. + * In most cases, you need not care about the journal, except when you need + * to change some data from a <>, or if you want to call cf_modify_item() and then + * undo the changes. ***/ /** - * By default, the configuration mechanism remembers all changes in a journal, - * so that the configuration can be rolled back or reloaded. This function - * can be used to disable journalling, which saves some memory. + * This function can be used to disable the whole journalling mechanism. + * It saves some memory, but it makes undoing of configuration changes impossible, + * which breaks for example cf_reload(). **/ void cf_set_journalling(int enable); /** @@ -432,7 +448,7 @@ void cf_set_journalling(int enable); * before them. **/ void cf_journal_block(void *ptr, uns len); -#define CF_JOURNAL_VAR(var) cf_journal_block(&(var), sizeof(var)) // Store single value into journal. +#define CF_JOURNAL_VAR(var) cf_journal_block(&(var), sizeof(var)) // Store a single value into the journal struct cf_journal_item; /** Opaque identifier of the journal state. **/ /** @@ -472,8 +488,17 @@ void cf_journal_rollback_transaction(uns new_pool, struct cf_journal_item *oldj) * If @allow_unknown is set to 0 and a variable not described in @sec * is found in the configuration file, it produces an error. * If you set it to 1, all such variables are ignored. + * + * Please note that a single section definition cannot be used in multiple + * configuration contexts simultaneously. **/ void cf_declare_section(const char *name, struct cf_section *sec, uns allow_unknown); +/** + * Like @cf_declare_section(), but instead of item pointers, the section + * contains offsets relative to @ptr. In other words, it does the same + * as `CF_SECTION`, but for top-level sections. + **/ +void cf_declare_rel_section(const char *name, struct cf_section *sec, void *ptr, uns allow_unknown); /** * If you have a section in a structure and you want to initialize it * (eg. if you want a copy of default values outside the configuration), @@ -504,7 +529,8 @@ char *cf_parse_ip(const char *p, u32 *varp); /** Parser for IP addresses. **/ * ~~~~~~~~~~~~~ * * Direct access to configuration items. - * You probably should not need this. + * You probably should not need this, but in your do, you have to handle + * <> yourself. ***/ /** @@ -545,7 +571,7 @@ char *cf_modify_item(struct cf_item *item, enum cf_operation op, int number, cha struct fastbuf; /** - * Take everything and write it into @fb. + * Write the current state of all configuration items into @fb. **/ void cf_dump_sections(struct fastbuf *fb);