maps: use uniform lifecycle management functions

Currently, the lifecycle functions for maps (allocation, deallocation, resize)
are not named in a uniform way and do not have a uniform function signature.
Rename the functions to fix that, and stick to libgit2's naming scheme of saying
`git_foo_new`. This results in the following new interface for allocation:

- `int git_<t>map_new(git_<t>map **out)` to allocate a new map, returning an
  error code if we ran out of memory

- `void git_<t>map_free(git_<t>map *map)` to free a map

- `void git_<t>map_clear(git<t>map *map)` to remove all entries from a map

This commit also fixes all existing callers.

src/apply.c

@@ -577,7 +577,7 @@ static int apply_deltas(
 	size_t i;
 	int error = 0;
 
-	if (git_strmap_alloc(&removed_paths) < 0)
+	if (git_strmap_new(&removed_paths) < 0)
 		return -1;
 
 	for (i = 0; i < git_diff_num_deltas(diff); i++) {

src/attr.c

@@ -215,7 +215,7 @@ int git_attr_foreach(
 		return -1;
 
 	if ((error = collect_attr_files(repo, NULL, flags, pathname, &files)) < 0 ||
-		(error = git_strmap_alloc(&seen)) < 0)
+	    (error = git_strmap_new(&seen)) < 0)
 		goto cleanup;
 
 	git_vector_foreach(&files, i, file) {

src/attrcache.c

@@ -400,8 +400,8 @@ int git_attr_cache__init(git_repository *repo)
 	/* allocate hashtable for attribute and ignore file contents,
 	 * hashtable for attribute macros, and string pool
 	 */
-	if ((ret = git_strmap_alloc(&cache->files)) < 0 ||
-		(ret = git_strmap_alloc(&cache->macros)) < 0)
+	if ((ret = git_strmap_new(&cache->files)) < 0 ||
+	    (ret = git_strmap_new(&cache->macros)) < 0)
 		goto cancel;
 
 	git_pool_init(&cache->pool, 1);

src/cache.c

@@ -65,12 +65,15 @@ void git_cache_dump_stats(git_cache *cache)
 int git_cache_init(git_cache *cache)
 {
 	memset(cache, 0, sizeof(*cache));
-	cache->map = git_oidmap_alloc();
-	GIT_ERROR_CHECK_ALLOC(cache->map);
+
+	if ((git_oidmap_new(&cache->map)) < 0)
+		return -1;
+
 	if (git_rwlock_init(&cache->lock)) {
 		git_error_set(GIT_ERROR_OS, "failed to initialize cache rwlock");
 		return -1;
 	}
+
 	return 0;
 }
 

src/checkout.c

@@ -2522,7 +2522,7 @@ static int checkout_data_init(
 	    (error = git_vector_init(&data->update_conflicts, 0, NULL)) < 0 ||
 	    (error = git_buf_puts(&data->target_path, data->opts.target_directory)) < 0 ||
 	    (error = git_path_to_dir(&data->target_path)) < 0 ||
-		(error = git_strmap_alloc(&data->mkdir_map)) < 0)
+	    (error = git_strmap_new(&data->mkdir_map)) < 0)
 		goto cleanup;
 
 	data->target_len = git_buf_len(&data->target_path);

src/config_entries.c

@@ -59,7 +59,7 @@ int git_config_entries_new(git_config_entries **out)
 	GIT_ERROR_CHECK_ALLOC(entries);
 	GIT_REFCOUNT_INC(entries);
 
-	if ((error = git_strmap_alloc(&entries->map)) < 0)
+	if ((error = git_strmap_new(&entries->map)) < 0)
 		git__free(entries);
 	else
 		*out = entries;

src/describe.c

@@ -681,8 +681,8 @@ int git_describe_commit(
 		"git_describe_options");
 	data.opts = &normalized;
 
-	data.names = git_oidmap_alloc();
-	GIT_ERROR_CHECK_ALLOC(data.names);
+	if ((error = git_oidmap_new(&data.names)) < 0)
+		return error;
 
 	/** TODO: contains to be implemented */
 

src/diff_driver.c

@@ -63,7 +63,7 @@ git_diff_driver_registry *git_diff_driver_registry_new(void)
 	if (!reg)
 		return NULL;
 
-	if (git_strmap_alloc(&reg->drivers) < 0) {
+	if (git_strmap_new(&reg->drivers) < 0) {
 		git_diff_driver_registry_free(reg);
 		return NULL;
 	}

src/idxmap.c

@@ -32,26 +32,42 @@ static kh_inline khint_t idxentry_hash(const git_index_entry *e)
 __KHASH_IMPL(idx, static kh_inline, const git_index_entry *, git_index_entry *, 1, idxentry_hash, idxentry_equal)
 __KHASH_IMPL(idxicase, static kh_inline, const git_index_entry *, git_index_entry *, 1, idxentry_hash, idxentry_icase_equal)
 
-int git_idxmap_alloc(git_idxmap **map)
+int git_idxmap_new(git_idxmap **out)
 {
-	if ((*map = kh_init(idx)) == NULL) {
-		git_error_set_oom();
-		return -1;
-	}
+	*out = kh_init(idx);
+	GIT_ERROR_CHECK_ALLOC(*out);
 
 	return 0;
 }
 
-int git_idxmap_icase_alloc(git_idxmap_icase **map)
+int git_idxmap_icase_new(git_idxmap_icase **out)
 {
-	if ((*map = kh_init(idxicase)) == NULL) {
-		git_error_set_oom();
-		return -1;
-	}
+	*out = kh_init(idxicase);
+	GIT_ERROR_CHECK_ALLOC(*out);
 
 	return 0;
 }
 
+void git_idxmap_free(git_idxmap *map)
+{
+	kh_destroy(idx, map);
+}
+
+void git_idxmap_icase_free(git_idxmap_icase *map)
+{
+	kh_destroy(idxicase, map);
+}
+
+void git_idxmap_clear(git_idxmap *map)
+{
+	kh_clear(idx, map);
+}
+
+void git_idxmap_icase_clear(git_idxmap_icase *map)
+{
+	kh_clear(idxicase, map);
+}
+
 void git_idxmap_insert(git_idxmap *map, const git_index_entry *key, void *value, int *rval)
 {
 	khiter_t idx = kh_put(idx, map, key, rval);
@@ -109,26 +125,6 @@ void git_idxmap_icase_resize(git_idxmap_icase *map, size_t size)
 	kh_resize(idxicase, map, size);
 }
 
-void git_idxmap_free(git_idxmap *map)
-{
-	kh_destroy(idx, map);
-}
-
-void git_idxmap_icase_free(git_idxmap_icase *map)
-{
-	kh_destroy(idxicase, map);
-}
-
-void git_idxmap_clear(git_idxmap *map)
-{
-	kh_clear(idx, map);
-}
-
-void git_idxmap_icase_clear(git_idxmap_icase *map)
-{
-	kh_clear(idxicase, map);
-}
-
 void git_idxmap_delete_at(git_idxmap *map, size_t idx)
 {
 	kh_del(idx, map, idx);

src/idxmap.h

@@ -11,11 +11,71 @@
 
 #include "git2/index.h"
 
+/** A map with `git_index_entry`s as key. */
 typedef struct kh_idx_s git_idxmap;
+/** A map with case-insensitive `git_index_entry`s as key */
 typedef struct kh_idxicase_s git_idxmap_icase;
 
-int git_idxmap_alloc(git_idxmap **map);
-int git_idxmap_icase_alloc(git_idxmap_icase **map);
+/**
+ * Allocate a new index entry map.
+ *
+ * @param out Pointer to the map that shall be allocated.
+ * @return 0 on success, an error code if allocation has failed.
+ */
+int git_idxmap_new(git_idxmap **out);
+
+/**
+ * Allocate a new case-insensitive index entry map.
+ *
+ * @param out Pointer to the map that shall be allocated.
+ * @return 0 on success, an error code if allocation has failed.
+ */
+int git_idxmap_icase_new(git_idxmap_icase **out);
+
+/**
+ * Free memory associated with the map.
+ *
+ * Note that this function will _not_ free values added to this
+ * map.
+ *
+ * @param map Pointer to the map that is to be free'd. May be
+ *            `NULL`.
+ */
+void git_idxmap_free(git_idxmap *map);
+
+/**
+ * Free memory associated with the map.
+ *
+ * Note that this function will _not_ free values added to this
+ * map.
+ *
+ * @param map Pointer to the map that is to be free'd. May be
+ *            `NULL`.
+ */
+void git_idxmap_icase_free(git_idxmap_icase *map);
+
+/**
+ * Clear all entries from the map.
+ *
+ * This function will remove all entries from the associated map.
+ * Memory associated with it will not be released, though.
+ *
+ * @param map Pointer to the map that shall be cleared. May be
+ *            `NULL`.
+ */
+void git_idxmap_clear(git_idxmap *map);
+
+/**
+ * Clear all entries from the map.
+ *
+ * This function will remove all entries from the associated map.
+ * Memory associated with it will not be released, though.
+ *
+ * @param map Pointer to the map that shall be cleared. May be
+ *            `NULL`.
+ */
+void git_idxmap_icase_clear(git_idxmap_icase *map);
+
 void git_idxmap_insert(git_idxmap *map, const git_index_entry *key, void *value, int *rval);
 void git_idxmap_icase_insert(git_idxmap_icase *map, const git_index_entry *key, void *value, int *rval);
 
@@ -27,10 +87,6 @@ int git_idxmap_has_data(git_idxmap *map, size_t idx);
 
 void git_idxmap_resize(git_idxmap *map, size_t size);
 void git_idxmap_icase_resize(git_idxmap_icase *map, size_t size);
-void git_idxmap_free(git_idxmap *map);
-void git_idxmap_icase_free(git_idxmap_icase *map);
-void git_idxmap_clear(git_idxmap *map);
-void git_idxmap_icase_clear(git_idxmap_icase *map);
 
 void git_idxmap_delete_at(git_idxmap *map, size_t idx);
 void git_idxmap_icase_delete_at(git_idxmap_icase *map, size_t idx);

src/index.c

@@ -423,7 +423,7 @@ int git_index_open(git_index **index_out, const char *index_path)
 	}
 
 	if (git_vector_init(&index->entries, 32, git_index_entry_cmp) < 0 ||
-		git_idxmap_alloc(&index->entries_map) < 0 ||
+	    git_idxmap_new(&index->entries_map) < 0 ||
 	    git_vector_init(&index->names, 8, conflict_name_cmp) < 0 ||
 	    git_vector_init(&index->reuc, 8, reuc_cmp) < 0 ||
 	    git_vector_init(&index->deleted, 8, git_index_entry_cmp) < 0)
@@ -3106,7 +3106,7 @@ int git_index_read_tree(git_index *index, const git_tree *tree)
 	size_t i;
 	git_index_entry *e;
 
-	if (git_idxmap_alloc(&entries_map) < 0)
+	if (git_idxmap_new(&entries_map) < 0)
 		return -1;
 
 	git_vector_set_cmp(&entries, index->entries._cmp); /* match sort */
@@ -3181,7 +3181,7 @@ static int git_index_read_iterator(
 
 	if ((error = git_vector_init(&new_entries, new_length_hint, index->entries._cmp)) < 0 ||
 	    (error = git_vector_init(&remove_entries, index->entries.length, NULL)) < 0 ||
-		(error = git_idxmap_alloc(&new_entries_map)) < 0)
+	    (error = git_idxmap_new(&new_entries_map)) < 0)
 		goto done;
 
 	if (index->ignore_case && new_length_hint)

src/indexer.c

@@ -147,8 +147,9 @@ int git_indexer_new(
 	git_hash_ctx_init(&idx->hash_ctx);
 	git_hash_ctx_init(&idx->trailer);
 	git_buf_init(&idx->entry_data, 0);
-	idx->expected_oids = git_oidmap_alloc();
-	GIT_ERROR_CHECK_ALLOC(idx->expected_oids);
+
+	if ((error = git_oidmap_new(&idx->expected_oids)) < 0)
+		goto cleanup;
 
 	idx->do_verify = opts.verify;
 
@@ -781,8 +782,8 @@ int git_indexer_append(git_indexer *idx, const void *data, size_t size, git_tran
 			return -1;
 		}
 
-		idx->pack->idx_cache = git_oidmap_alloc();
-		GIT_ERROR_CHECK_ALLOC(idx->pack->idx_cache);
+		if (git_oidmap_new(&idx->pack->idx_cache) < 0)
+			return -1;
 
 		idx->pack->has_cache = 1;
 		if (git_vector_init(&idx->objects, total_objects, objects_cmp) < 0)

src/merge.c

@@ -1168,8 +1168,8 @@ static int merge_diff_mark_similarity_exact(
 	git_oidmap *ours_deletes_by_oid = NULL, *theirs_deletes_by_oid = NULL;
 	int error = 0;
 
-	if (!(ours_deletes_by_oid = git_oidmap_alloc()) ||
-		!(theirs_deletes_by_oid = git_oidmap_alloc())) {
+	if (git_oidmap_new(&ours_deletes_by_oid) < 0 ||
+	    git_oidmap_new(&theirs_deletes_by_oid) < 0) {
 		error = -1;
 		goto done;
 	}

src/mwindow.c

@@ -44,7 +44,7 @@ int git_mwindow_global_init(void)
 	assert(!git__pack_cache);
 
 	git__on_shutdown(git_mwindow_files_free);
-	return git_strmap_alloc(&git__pack_cache);
+	return git_strmap_new(&git__pack_cache);
 }
 
 int git_mwindow_get_pack(struct git_pack_file **out, const char *path)

src/odb_mempack.c

@@ -171,7 +171,8 @@ int git_mempack_new(git_odb_backend **out)
 	db = git__calloc(1, sizeof(struct memory_packer_db));
 	GIT_ERROR_CHECK_ALLOC(db);
 
-	db->objects = git_oidmap_alloc();
+	if (git_oidmap_new(&db->objects) < 0)
+		return -1;
 
 	db->parent.version = GIT_ODB_BACKEND_VERSION;
 	db->parent.read = &impl__read;

src/offmap.c

@@ -18,9 +18,13 @@ __KHASH_TYPE(off, git_off_t, void *)
 
 __KHASH_IMPL(off, static kh_inline, git_off_t, void *, 1, kh_int64_hash_func, kh_int64_hash_equal)
 
-git_offmap *git_offmap_alloc(void)
+
+int git_offmap_new(git_offmap **out)
 {
-	return kh_init(off);
+	*out = kh_init(off);
+	GIT_ERROR_CHECK_ALLOC(*out);
+
+	return 0;
 }
 
 void git_offmap_free(git_offmap *map)

src/offmap.h

@@ -11,10 +11,37 @@
 
 #include "git2/types.h"
 
+/** A map with `git_off_t`s as key. */
 typedef struct kh_off_s git_offmap;
 
-git_offmap *git_offmap_alloc(void);
+/**
+ * Allocate a new `git_off_t` map.
+ *
+ * @param out Pointer to the map that shall be allocated.
+ * @return 0 on success, an error code if allocation has failed.
+ */
+int git_offmap_new(git_offmap **out);
+
+/**
+ * Free memory associated with the map.
+ *
+ * Note that this function will _not_ free values added to this
+ * map.
+ *
+ * @param map Pointer to the map that is to be free'd. May be
+ *            `NULL`.
+ */
 void git_offmap_free(git_offmap *map);
+
+/**
+ * Clear all entries from the map.
+ *
+ * This function will remove all entries from the associated map.
+ * Memory associated with it will not be released, though.
+ *
+ * @param map Pointer to the map that shall be cleared. May be
+ *            `NULL`.
+ */
 void git_offmap_clear(git_offmap *map);
 
 size_t git_offmap_num_entries(git_offmap *map);

src/oidmap.c

@@ -25,9 +25,12 @@ GIT_INLINE(khint_t) git_oidmap_hash(const git_oid *oid)
 
 __KHASH_IMPL(oid, static kh_inline, const git_oid *, void *, 1, git_oidmap_hash, git_oid_equal)
 
-git_oidmap *git_oidmap_alloc()
+int git_oidmap_new(git_oidmap **out)
 {
-	return kh_init(oid);
+	*out = kh_init(oid);
+	GIT_ERROR_CHECK_ALLOC(*out);
+
+	return 0;
 }
 
 void git_oidmap_free(git_oidmap *map)

src/oidmap.h

@@ -11,10 +11,37 @@
 
 #include "git2/oid.h"
 
+/** A map with `git_oid`s as key. */
 typedef struct kh_oid_s git_oidmap;
 
-git_oidmap *git_oidmap_alloc(void);
+/**
+ * Allocate a new OID map.
+ *
+ * @param out Pointer to the map that shall be allocated.
+ * @return 0 on success, an error code if allocation has failed.
+ */
+int git_oidmap_new(git_oidmap **out);
+
+/**
+ * Free memory associated with the map.
+ *
+ * Note that this function will _not_ free values added to this
+ * map.
+ *
+ * @param map Pointer to the map that is to be free'd. May be
+ *            `NULL`.
+ */
 void git_oidmap_free(git_oidmap *map);
+
+/**
+ * Clear all entries from the map.
+ *
+ * This function will remove all entries from the associated map.
+ * Memory associated with it will not be released, though.
+ *
+ * @param map Pointer to the map that shall be cleared. May be
+ *            `NULL`.
+ */
 void git_oidmap_clear(git_oidmap *map);
 
 size_t git_oidmap_size(git_oidmap *map);

src/pack-objects.c

@@ -141,12 +141,10 @@ int git_packbuilder_new(git_packbuilder **out, git_repository *repo)
 	pb = git__calloc(1, sizeof(*pb));
 	GIT_ERROR_CHECK_ALLOC(pb);
 
-	pb->object_ix = git_oidmap_alloc();
-	if (!pb->object_ix)
+	if (git_oidmap_new(&pb->object_ix) < 0)
 		goto on_error;
 
-	pb->walk_objects = git_oidmap_alloc();
-	if (!pb->walk_objects)
+	if (git_oidmap_new(&pb->walk_objects) < 0)
 		goto on_error;
 
 	git_pool_init(&pb->object_pool, sizeof(struct walk_object));

src/pack.c

@@ -92,8 +92,8 @@ static void cache_free(git_pack_cache *cache)
 
 static int cache_init(git_pack_cache *cache)
 {
-	cache->entries = git_offmap_alloc();
-	GIT_ERROR_CHECK_ALLOC(cache->entries);
+	if (git_offmap_new(&cache->entries) < 0)
+		return -1;
 
 	cache->memory_limit = GIT_PACK_CACHE_MEMORY_LIMIT;
 

src/pack.h

@@ -17,6 +17,7 @@
 #include "map.h"
 #include "mwindow.h"
 #include "odb.h"
+#include "offmap.h"
 #include "oidmap.h"
 #include "array.h"
 
@@ -71,9 +72,6 @@ struct pack_chain_elem {
 
 typedef git_array_t(struct pack_chain_elem) git_dependency_chain;
 
-#include "offmap.h"
-#include "oidmap.h"
-
 #define GIT_PACK_CACHE_MEMORY_LIMIT 16 * 1024 * 1024
 #define GIT_PACK_CACHE_SIZE_LIMIT 1024 * 1024 /* don't bother caching anything over 1MB */
 

src/repository.c

@@ -2916,7 +2916,7 @@ int git_repository_submodule_cache_all(git_repository *repo)
 
 	assert(repo);
 
-	if ((error = git_strmap_alloc(&repo->submodule_cache)))
+	if ((error = git_strmap_new(&repo->submodule_cache)))
 		return error;
 
 	error = git_submodule__map(repo, repo->submodule_cache);

src/revwalk.c

@@ -626,8 +626,8 @@ int git_revwalk_new(git_revwalk **revwalk_out, git_repository *repo)
 	git_revwalk *walk = git__calloc(1, sizeof(git_revwalk));
 	GIT_ERROR_CHECK_ALLOC(walk);
 
-	walk->commits = git_oidmap_alloc();
-	GIT_ERROR_CHECK_ALLOC(walk->commits);
+	if (git_oidmap_new(&walk->commits) < 0)
+		return -1;
 
 	if (git_pqueue_init(&walk->iterator_time, 0, 8, git_commit_list_time_cmp) < 0)
 		return -1;

src/sortedcache.c

@@ -28,7 +28,7 @@ int git_sortedcache_new(
 	git_pool_init(&sc->pool, 1);
 
 	if (git_vector_init(&sc->items, 4, item_cmp) < 0 ||
-		git_strmap_alloc(&sc->map) < 0)
+	    git_strmap_new(&sc->map) < 0)
 		goto fail;
 
 	if (git_rwlock_init(&sc->lock)) {

src/strmap.c

@@ -18,12 +18,10 @@ __KHASH_TYPE(str, const char *, void *)
 
 __KHASH_IMPL(str, static kh_inline, const char *, void *, 1, kh_str_hash_func, kh_str_hash_equal)
 
-int git_strmap_alloc(git_strmap **map)
+int git_strmap_new(git_strmap **out)
 {
-	if ((*map = kh_init(str)) == NULL) {
-		git_error_set_oom();
-		return -1;
-	}
+	*out = kh_init(str);
+	GIT_ERROR_CHECK_ALLOC(*out);
 
 	return 0;
 }

src/strmap.h

@@ -9,10 +9,37 @@
 
 #include "common.h"
 
+/** A map with C strings as key. */
 typedef struct kh_str_s git_strmap;
 
-int git_strmap_alloc(git_strmap **map);
+/**
+ * Allocate a new string map.
+ *
+ * @param out Pointer to the map that shall be allocated.
+ * @return 0 on success, an error code if allocation has failed.
+ */
+int git_strmap_new(git_strmap **out);
+
+/**
+ * Free memory associated with the map.
+ *
+ * Note that this function will _not_ free keys or values added
+ * to this map.
+ *
+ * @param map Pointer to the map that is to be free'd. May be
+ *            `NULL`.
+ */
 void git_strmap_free(git_strmap *map);
+
+/**
+ * Clear all entries from the map.
+ *
+ * This function will remove all entries from the associated map.
+ * Memory associated with it will not be released, though.
+ *
+ * @param map Pointer to the map that shall be cleared. May be
+ *            `NULL`.
+ */
 void git_strmap_clear(git_strmap *map);
 
 size_t git_strmap_num_entries(git_strmap *map);

src/submodule.c

@@ -202,7 +202,7 @@ static int load_submodule_names(git_strmap **out, git_repository *repo, git_conf
 
 	*out = NULL;
 
-	if ((error = git_strmap_alloc(&names)) < 0)
+	if ((error = git_strmap_new(&names)) < 0)
 		goto out;
 
 	if ((error = git_config_iterator_glob_new(&iter, cfg, key)) < 0)
@@ -618,7 +618,7 @@ int git_submodule_foreach(
 		return -1;
 	}
 
-	if ((error = git_strmap_alloc(&submodules)) < 0)
+	if ((error = git_strmap_new(&submodules)) < 0)
 		return error;
 
 	if ((error = git_submodule__map(repo, submodules)) < 0)

src/transaction.c

@@ -84,7 +84,7 @@ int git_transaction_new(git_transaction **out, git_repository *repo)
 		goto on_error;
 	}
 
-	if ((error = git_strmap_alloc(&tx->locks)) < 0) {
+	if ((error = git_strmap_new(&tx->locks)) < 0) {
 		error = -1;
 		goto on_error;
 	}

src/tree.c

@@ -688,7 +688,7 @@ int git_treebuilder_new(
 
 	bld->repo = repo;
 
-	if (git_strmap_alloc(&bld->map) < 0) {
+	if (git_strmap_new(&bld->map) < 0) {
 		git__free(bld);
 		return -1;
 	}

tests/core/oidmap.c

@@ -24,8 +24,7 @@ void test_core_oidmap__basic(void)
 		}
 	}
 
-	map = git_oidmap_alloc();
-	cl_assert(map != NULL);
+	cl_git_pass(git_oidmap_new(&map));
 
 	for (i = 0; i < NITEMS; ++i) {
 		size_t pos;
@@ -78,8 +77,7 @@ void test_core_oidmap__hash_collision(void)
 		items[i].oid.id[11] = (unsigned char)(i >> 24);
 	}
 
-	map = git_oidmap_alloc();
-	cl_assert(map != NULL);
+	cl_git_pass(git_oidmap_new(&map));
 
 	for (i = 0; i < NITEMS; ++i) {
 		size_t pos;

tests/core/strmap.c

@@ -5,7 +5,7 @@ git_strmap *g_table;
 
 void test_core_strmap__initialize(void)
 {
-	cl_git_pass(git_strmap_alloc(&g_table));
+	cl_git_pass(git_strmap_new(&g_table));
 	cl_assert(g_table != NULL);
 }