diff options
Diffstat (limited to 'pom.h')
| -rw-r--r-- | pom.h | 33 |
1 files changed, 16 insertions, 17 deletions
@@ -4,8 +4,7 @@ /// ## Thread-safety /// /// Of course, you should not free or \ref pom_conf_merge into -/// a configuration while another thread is using it (even through a section -/// obtained via \ref pom_conf_section). +/// a configuration while another thread is using it. /// /// Other than that, all these functions are fully thread-safe /// provided that C11 atomics are available @@ -14,9 +13,11 @@ /// (ensure there is synchronization so that all threads /// have certainly read their keys before calling it). /// -/// If C11 atomics are not available, you should not use -/// the same configuration across multiple threads (even for -/// seemingly "read-only" operations), but you can still use +/// If C11 atomics are not available, you can almost certainly still get away +/// with sharing configurations across threads. +/// (Essentially, libpom may end up writing the same value to the same address +/// from separate threads, which will likely never be an issue on any real machine.) +/// Even if you are extremely paranoid, you can still use /// distinct configurations in different threads without worry. /// \mainpage libpom doxygen documentation @@ -333,7 +334,7 @@ char ** pom_conf_get_list(const pom_conf *conf, const char *key) POM__MUST_USE_R; -/// Extract section out of POM configuration. Invalidated if \ref pom_conf_merge is called. +/// Extract section out of POM configuration. /// /// Specifically, this returns the configuration consisting of all keys /// prefixed by `section.`, with that prefix removed, and their corresponding @@ -359,8 +360,6 @@ pom_conf_section(const pom_conf *conf, const char *section); /// you should still call this function repeatedly until you get `NULL`; /// otherwise memory associated with the iterator may be leaked. /// -/// The iterator is invalidated if \ref pom_conf_merge is called. -/// /// The correct usage for this function is: /// /// ```C @@ -388,8 +387,6 @@ pom_conf_next_key(const pom_conf *conf, pom_key_iter **iter); /// you should still call this function repeatedly until you get `NULL`; /// otherwise memory associated with the iterator may be leaked. /// -/// The iterator is invalidated if \ref pom_conf_merge is called. -/// /// The returned pointer is only valid until the next call to \ref pom_conf_next_item. /// /// The correct usage for this function is: @@ -417,11 +414,15 @@ pom_conf * pom_conf_copy(const pom_conf *conf) POM__MUST_USE_R; -/// Merge keys from `other` into `conf`, preferring keys in `other`. This invalidates -/// all sections made with \ref pom_conf_section. +/// Merge keys from `other` into `conf`, preferring keys in `other`. /// -/// It also invalidates any iterators from \ref pom_conf_next_item, \ref pom_conf_next_unread_key, -/// \ref pom_conf_next_key. +/// Sections obtained from \ref pom_conf_section and iterators +/// (\ref pom_conf_next_unread_key, \ref pom_conf_next_item, \ref pom_conf_next_key) +/// will still point to the old configuration. +/// For this reason, the old configuration is kept in memory until \ref pom_conf_free +/// is called, so if you are repeatedly calling this function (unlikely, but who knows), +/// you should make a copy of `conf` after each call (with \ref pom_conf_copy), +/// then free the old value of `conf`. void pom_conf_merge(pom_conf *conf, const pom_conf *other); @@ -440,8 +441,6 @@ pom_conf_merge(pom_conf *conf, const pom_conf *other); /// you should still call this function repeatedly until you get `NULL`; /// otherwise memory associated with the iterator may be leaked. /// -/// The iterator is invalidated if \ref pom_conf_merge is called. -/// /// The correct usage for this function is: /// /// ```C @@ -452,7 +451,7 @@ pom_conf_merge(pom_conf *conf, const pom_conf *other); /// } /// ``` const char * -pom_conf_next_unread_key(pom_conf *conf, pom_unread_key_iter **iter); +pom_conf_next_unread_key(const pom_conf *conf, pom_unread_key_iter **iter); #ifndef POM_NO_STDIO /// Print `key: value` for each `key` in `conf` to `stdout`. |