X-Git-Url: http://mj.ucw.cz/gitweb/?a=blobdiff_plain;f=ucw%2Fconf.h;h=4254f05c6426549402367e7fda2b9aab4beeac91;hb=6efdc514c193f18c9ef840096750c37e78a01bf6;hp=a15d0da28c2eca376bb904e4eb552273efd8371b;hpb=b541de765129b6bf28c5601bb355779652001150;p=libucw.git diff --git a/ucw/conf.h b/ucw/conf.h index a15d0da2..4254f05c 100644 --- a/ucw/conf.h +++ b/ucw/conf.h @@ -21,10 +21,10 @@ struct mempool; * ~~~~~~~~~~~~~~~~~~~~~~ * * The state of the configuration parser is stored within a configuration context. - * If you do not create contexts explicitly, the library will create one for you - * and you need not care, as long as you use a single configuration file. + * 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 whole 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. ***/ @@ -34,14 +34,14 @@ struct cf_context *cf_new_context(void); /** * Free a configuration context. The context must not be set as current - * for any thread. + * for any thread, nor can it be the default context. * * All configuration settings made within the context are rolled back * (except when journalling is turned off). All memory allocated on behalf * 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 @@ -49,11 +49,61 @@ void cf_free_context(struct cf_context *cc); **/ struct cf_context *cf_switch_context(struct cf_context *cc); +/*** + * [[conf_load]] + * Safe configuration loading + * ~~~~~~~~~~~~~~~~~~~~~~~~~~ + * + * These functions can be used to to safely load or reload configuration. + */ + +/** + * Load configuration from @file. + * Returns a non-zero value upon error. In that case, all changes to the + * 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 + * bits of configuration passed to cf_set(). + * Returns a non-zero value upon error. In that case, all configuration + * 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 <>. + * Returns a non-zero value upon error. In that case, all changes to the + * configuration specified by the already executed parts of the string + * are undone. + **/ +int cf_set(const char *string); + /** - * Return a pointer to the current context, or create the default context - * if there is no context active. + * Sometimes, the configuration is split to multiple files and when only + * some of the are loaded, the settings are not consistent -- for example, + * they might have been rejected by a commit hook, because a mandatory setting + * is missing. + * + * This function opens a configuration group, in which multiple files can be + * loaded and all commit hooks are deferred until the group is closed. + **/ +void cf_open_group(void); + +/** + * Close a group opened by cf_open_group(). Returns a non-zero value upon error, + * which usually means that a commit hook has failed. + **/ +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. **/ -struct cf_context *cf_obtain_context(void); +void cf_revert(void); /*** === Data types [[conf_types]] ***/ @@ -358,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. **/ @@ -370,9 +423,23 @@ char *cf_printf(const char *fmt, ...) FORMAT_CHECK(printf,1,2); /** printf() int * Undo journal * ~~~~~~~~~~~~ * - * For error recovery when <>. + * 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. + * + * 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. ***/ -extern uns cf_need_journal; /** Is the journal needed? If you do not reload configuration, you set this to 0 and gain a little more performance and free 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); /** * When a block of memory is about to be changed, put the old value * into journal with this function. You need to call it from a <> @@ -381,7 +448,32 @@ extern uns cf_need_journal; /** Is the journal needed? If you do not reload conf * 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. **/ +/** + * Starts a new transaction. It returns the current state so you can + * get back to it. The @new_pool parameter tells if a new memory pool + * should be created and used from now. + **/ +struct cf_journal_item *cf_journal_new_transaction(uns new_pool); +/** + * Marks current state as a complete transaction. The @new_pool + * parameter tells if the transaction was created with new memory pool + * (the parameter must be the same as the one with + * @cf_journal_new_transaction() was called with). The @oldj parameter + * is the journal state returned from last + * @cf_journal_new_transaction() call. + **/ +void cf_journal_commit_transaction(uns new_pool, struct cf_journal_item *oldj); +/** + * Returns to an old journal state, reverting anything the current + * transaction did. The @new_pool parameter must be the same as the + * one you used when you created the transaction. The @oldj parameter + * is the journal state you got from @cf_journal_new_transaction() -- + * it is the state to return to. + **/ +void cf_journal_rollback_transaction(uns new_pool, struct cf_journal_item *oldj); /*** * [[declare]] @@ -422,5 +514,56 @@ char *cf_parse_u64(const char *str, u64 *ptr); /** Parser for 64 unsigned integ char *cf_parse_double(const char *str, double *ptr); /** Parser for doubles. **/ char *cf_parse_ip(const char *p, u32 *varp); /** Parser for IP addresses. **/ -#endif +/*** + * [[conf_direct]] + * Direct access + * ~~~~~~~~~~~~~ + * + * Direct access to configuration items. + * You probably should not need this, but in your do, you have to handle + * <> yourself. + ***/ + +/** + * List of operations used on items. + * This macro is used to generate internal source code, + * but you may be interested in the list of operations it creates. + * + * Each operation corresponds to the same-named operation + * described in <>. + **/ +#define CF_OPERATIONS T(CLOSE) T(SET) T(CLEAR) T(ALL) \ + T(APPEND) T(PREPEND) T(REMOVE) T(EDIT) T(AFTER) T(BEFORE) T(COPY) T(RESET) + /* Closing brace finishes previous block. + * Basic attributes (static, dynamic, parsed) can be used with SET. + * Dynamic arrays can be used with SET, APPEND, PREPEND. + * Sections can be used with SET. + * Lists can be used with everything. */ +#define T(x) OP_##x, +enum cf_operation { CF_OPERATIONS }; /** Allowed operations on items. See <> for list (they have an `OP_` prefix -- it means you use `OP_SET` instead of just `SET`). **/ +#undef T +/** + * Searches for a configuration item called @name. + * If it is found, it is copied into @item and NULL is returned. + * Otherwise, an error is returned and @item is zeroed. + **/ +char *cf_find_item(const char *name, struct cf_item *item); +/** + * Performs a single operation on a given item. + **/ +char *cf_modify_item(struct cf_item *item, enum cf_operation op, int number, char **pars); + +/*** + * [[conf_dump]] + * Debug dumping + * ~~~~~~~~~~~~~ + ***/ + +struct fastbuf; +/** + * Write the current state of all configuration items into @fb. + **/ +void cf_dump_sections(struct fastbuf *fb); + +#endif