undef/git-commit-vandalism
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

hashmap: add usage documentation explaining hashmap_free[_entries]()

Browse Source 
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@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Elijah Newren 2020-10-13 00:40:41 +00:00 committed by Junio C Hamano
parent d4a392452e
commit 6474b86939
1 changed files with 29 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
hashmap.h
View File

@ -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));