Conf: Decoupled cf_stack_done() from committing

[libucw.git] / ucw / conf.h

diff --git a/ucw/conf.h b/ucw/conf.h
index bef4553e155a5477cb1abb664d27c1da62785be1..4254f05c6426549402367e7fda2b9aab4beeac91 100644 (file)
--- 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.
  *
  * 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.
  ***/
  * 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().
  **/
  * 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
 
 /**
  * Make the given configuration context current and return the previously


@@ -57,14 +57,54 @@ struct cf_context *cf_switch_context(struct cf_context *cc);
  * These functions can be used to to safely load or reload configuration.
  */
 
  * These functions can be used to to safely load or reload configuration.
  */
 

-int cf_reload(const char *file);       /** Reload configuration from @file, replace the old one. **/
-int cf_load(const char *file);         /** Load configuration from @file. If @file is NULL, reload all loaded configuration files. **/
+/**
+ * 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 <<config:,configuration file>>.
 /**
  * Parse some part of configuration passed in @string.
  * The syntax is the same as in the <<config:,configuration file>>.

+ * 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);
 
  **/
 int cf_set(const char *string);
 

+/**
+ * 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.
+ **/
+void cf_revert(void);
+

 /*** === Data types [[conf_types]] ***/
 
 enum cf_class {                                /** Class of the configuration item. **/
 /*** === Data types [[conf_types]] ***/
 
 enum cf_class {                                /** Class of the configuration item. **/


@@ -368,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.
  * 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. **/
  ***/
 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. **/


@@ -380,16 +423,21 @@ char *cf_printf(const char *fmt, ...) FORMAT_CHECK(printf,1,2); /** printf() int
  * Undo journal
  * ~~~~~~~~~~~~
  *
  * 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);
 /**
  **/
 void cf_set_journalling(int enable);
 /**


@@ -400,7 +448,7 @@ void cf_set_journalling(int enable);
  * before them.
  **/
 void cf_journal_block(void *ptr, uns len);
  * 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. **/
 /**
 
 struct cf_journal_item;                /** Opaque identifier of the journal state. **/
 /**


@@ -472,7 +520,8 @@ char *cf_parse_ip(const char *p, u32 *varp);                /** Parser for IP addresses. **/
  * ~~~~~~~~~~~~~
  *
  * Direct access to configuration items.
  * ~~~~~~~~~~~~~
  *
  * 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.

  ***/
 
 /**
  ***/
 
 /**


@@ -513,7 +562,7 @@ char *cf_modify_item(struct cf_item *item, enum cf_operation op, int number, cha
 
 struct fastbuf;
 /**
 
 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);
 
  **/
 void cf_dump_sections(struct fastbuf *fb);