* 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.
***/
* 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
* 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
* 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 <<config:,configuration file>>.
**/
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. **/
* 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. **/
* 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 <<reload,reloading configuration>>.
+ * In most cases, you need not care about the journal, except when you need
+ * to change some data from a <<hooks,hook>>, 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);
/**
* 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. **/
/**
* 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),
* ~~~~~~~~~~~~~
*
* 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
+ * <<journal,journalling>> yourself.
***/
/**
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);