From: Elijah Newren <newren@xxxxxxxxx>
The existence of hashmap_free() and hashmap_free_entries() confused me,
and the docs weren't clear enough. We are dealing with a map table,
entries in that table, and possibly also things each of those entries
point to. I had to consult other source code examples and the
implementation. Add a brief note to clarify the differences. This will
become even more important once we introduce a new
hashmap_partial_clear() function which will add the question of whether
the table itself has been freed.
Signed-off-by: Elijah Newren <newren@xxxxxxxxx>
---
hashmap.h | 31 +++++++++++++++++++++++++++++--
1 file changed, 29 insertions(+), 2 deletions(-)
diff --git a/hashmap.h b/hashmap.h
index b011b394fe..2994dc7a9c 100644
--- a/hashmap.h
+++ b/hashmap.h
@@ -236,13 +236,40 @@ void hashmap_init(struct hashmap *map,
void hashmap_free_(struct hashmap *map, ssize_t offset);
/*
- * Frees a hashmap structure and allocated memory, leaves entries undisturbed
+ * Frees a hashmap structure and allocated memory for the table, but does not
+ * free the entries nor anything they point to.
+ *
+ * Usage note:
+ *
+ * Many callers will need to iterate over all entries and free the data each
+ * entry points to; in such a case, they can free the entry itself while at it.
+ * Thus, you might see:
+ *
+ * hashmap_for_each_entry(map, hashmap_iter, e, hashmap_entry_name) {
+ * free(e->somefield);
+ * free(e);
+ * }
+ * hashmap_free(map);
+ *
+ * instead of
+ *
+ * hashmap_for_each_entry(map, hashmap_iter, e, hashmap_entry_name) {
+ * free(e->somefield);
+ * }
+ * hashmap_free_entries(map, struct my_entry_struct, hashmap_entry_name);
+ *
+ * to avoid the implicit extra loop over the entries. However, if there are
+ * no special fields in your entry that need to be freed beyond the entry
+ * itself, it is probably simpler to avoid the explicit loop and just call
+ * hashmap_free_entries().
*/
#define hashmap_free(map) hashmap_free_(map, -1)
/*
* Frees @map and all entries. @type is the struct type of the entry
- * where @member is the hashmap_entry struct used to associate with @map
+ * where @member is the hashmap_entry struct used to associate with @map.
+ *
+ * See usage note above hashmap_free().
*/
#define hashmap_free_entries(map, type, member) \
hashmap_free_(map, offsetof(type, member));
--
gitgitgadget
