util: hash: Add deprecation notices for functions which have g_hash_table replacements

For functions which have reasonable replacement, let's encourage usage
of g_hash_table_ alternatives.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Daniel Henrique Barboza <danielhb413@gmail.com>
Reviewed-by: Matt Coleman <matt@datto.com>

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,