For functions which have reasonable replacement, let's encourage usage
of g_hash_table_ alternatives.
Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx>
---
src/util/virhash.c | 31 ++++++++++++++++++++++++++++++-
1 file changed, 30 insertions(+), 1 deletion(-)
diff --git a/src/util/virhash.c b/src/util/virhash.c
index a7d119f8bc..5d5b6389b5 100644
--- a/src/util/virhash.c
+++ b/src/util/virhash.c
@@ -78,7 +78,7 @@ virHashTableStringKey(const void *vkey)
* virHashNew:
* @dataFree: callback to free data
*
- * Create a new GHashTable *.
+ * Create a new GHashTable * for use with string-based keys.
*
* Returns the newly created object.
*/
@@ -125,6 +125,8 @@ virHashAtomicDispose(void *obj)
*
* Free the hash @table and its contents. The userdata is
* deallocated with function provided at creation time.
+ *
+ * Deprecated: consider using g_hash_table_unref instead
*/
void
virHashFree(GHashTable *table)
@@ -145,6 +147,10 @@ virHashFree(GHashTable *table)
* Add the @userdata to the hash @table. This can later be retrieved
* by using @name. Duplicate entries generate errors.
*
+ * Deprecated: Consider using g_hash_table_insert insert. Note that
+ * g_hash_table_instead doesn't fail if entry exists. Also note that
+ * g_hash_table_insert doesn't copy the key.
+ *
* Returns 0 the addition succeeded and -1 in case of error.
*/
int
@@ -174,6 +180,9 @@ virHashAddEntry(GHashTable *table, const char *name, void *userdata)
* by using @name. Existing entry for this tuple
* will be removed and freed with @f if found.
*
+ * Deprecated: consider using g_hash_table_insert insert. Note that
+ * g_hash_table_insert doesn't copy the key.
+ *
* Returns 0 the addition succeeded and -1 in case of error.
*/
int
@@ -210,6 +219,8 @@ virHashAtomicUpdate(virHashAtomicPtr table,
*
* Find the userdata specified by @name
*
+ * Deprecated: consider using g_hash_table_lookup instead
+ *
* Returns a pointer to the userdata
*/
void *
@@ -230,6 +241,8 @@ virHashLookup(GHashTable *table,
*
* Find whether entry specified by @name exists.
*
+ * Deprecated: consider using g_hash_table_contains instead
+ *
* Returns true if the entry exists and false otherwise
*/
bool
@@ -251,6 +264,9 @@ virHashHasEntry(GHashTable *table,
* Find the userdata specified by @name
* and remove it from the hash without freeing it.
*
+ * Deprecated: consider using g_hash_table_steal_extended once we upgrade to
+ * glib 2.58
+ *
* Returns a pointer to the userdata
*/
void *virHashSteal(GHashTable *table, const char *name)
@@ -290,6 +306,8 @@ virHashAtomicSteal(virHashAtomicPtr table,
*
* Query the number of elements installed in the hash @table.
*
+ * Deprecated: consider using g_hash_table_size instead
+ *
* Returns the number of elements in the hash table or
* -1 in case of error
*/
@@ -312,6 +330,8 @@ virHashSize(GHashTable *table)
* it from the hash @table. Existing userdata for this tuple will be removed
* and freed with @f.
*
+ * Deprecated: consider using g_hash_table_remove
+ *
* Returns 0 if the removal succeeded and -1 in case of error or not found.
*/
int
@@ -353,6 +373,9 @@ virHashRemoveEntry(GHashTable *table,
* If @iter fails and returns a negative value, the evaluation is stopped and -1
* is returned.
*
+ * Deprecated: Consider using g_hash_table_foreach as replacement for
+ * virHashForEach, rewrite your code if it would require virHashForEachSafe.
+ *
* Returns 0 on success or -1 on failure.
*/
int
@@ -445,6 +468,8 @@ virHashSearcherWrapFunc(gpointer key,
* will be removed from the hash table & its payload passed to the
* data freer callback registered at creation.
*
+ * Deprecated: consider using g_hash_table_foreach_remove instead
+ *
* Returns number of items removed on success, -1 on failure
*/
ssize_t
@@ -466,6 +491,8 @@ virHashRemoveSet(GHashTable *table,
*
* Free the hash @table's contents. The userdata is
* deallocated with the function provided at creation time.
+ *
+ * Deprecated: consider using g_hash_table_remove_all instead
*/
void
virHashRemoveAll(GHashTable *table)
@@ -488,6 +515,8 @@ virHashRemoveAll(GHashTable *table)
* returns non-zero will be returned by this function.
* The elements are processed in a undefined order. Caller is
* responsible for freeing the @name.
+ *
+ * Deprecated: consider using g_hash_table_find instead
*/
void *virHashSearch(GHashTable *table,
virHashSearcher iter,
--
2.26.2
