Implement pom_conf_next_key, pom_conf_next_unread_key

1 files changed, 16 insertions, 17 deletions

diff --git a/pom.h b/pom.h
index 75fefd1..7af38c8 100644
--- a/pom.h
+++ b/pom.h
@@ -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`.