2002-11-23 Havoc Pennington <hp@pobox.com>

[platform/upstream/dbus.git] / dbus / dbus-hash.c

diff --git a/dbus/dbus-hash.c b/dbus/dbus-hash.c
index 1527251..48e96ca 100644 (file)
--- a/dbus/dbus-hash.c
+++ b/dbus/dbus-hash.c
@@ -1,5 +1,5 @@
 /* -*- mode: C; c-file-style: "gnu" -*- */
-/* dbus-hash.c  Generic hash table utility (internal to D-BUS implementation)
+/* dbus-hash.c Generic hash table utility (internal to D-BUS implementation)
  * 
  * Copyright (C) 2002  Red Hat, Inc.
  * Copyright (c) 1991-1993 The Regents of the University of California.
@@ -92,6 +92,13 @@
  *
  * The guts of DBusHashTable.
  *
+ * @todo rebuild_table() should be modified to also shrink the hash bucket
+ * array when appropriate; otherwise if a hash table has been
+ * very large but is now small, iteration becomes inefficient.
+ * We should still only shrink when adding hash entries though, not
+ * when removing them, so that you can still iterate over the hash
+ * removing entries. So if you added 5000, removed 4000, the
+ * shrinking would happen next time an entry was added.
  * @{
  */
 
@@ -123,6 +130,8 @@
 typedef struct DBusHashEntry DBusHashEntry;
 
 /**
+ * @brief Internal representation of a hash entry.
+ * 
  * A single entry (key-value pair) in the hash table.
  * Internal to hash table implementation.
  */
@@ -145,7 +154,10 @@ typedef DBusHashEntry* (* DBusFindEntryFunction) (DBusHashTable   *table,
                                                   DBusHashEntry ***bucket);
 
 /**
- * Hash table internal members.
+ * @brief Internals of DBusHashTable.
+ * 
+ * Hash table internals. Hash tables are opaque objects, they must be
+ * used via accessor functions.
  */
 struct DBusHashTable {
   int refcount;                       /**< Reference count */
@@ -183,8 +195,8 @@ struct DBusHashTable {
   DBusFreeFunction free_value_function; /**< Function to free values */
 };
 
-/**
- * Internals of DBusHashIter.
+/** 
+ * @brief Internals of DBusHashIter.
  */
 typedef struct
 {
@@ -216,7 +228,7 @@ static void           remove_entry         (DBusHashTable   *table,
 static void           free_entry           (DBusHashTable   *table,
                                             DBusHashEntry   *entry);
 
-/** }@ */
+/** @} */
 
 /**
  * @addtogroup DBusHashTable
@@ -924,8 +936,9 @@ _dbus_hash_table_lookup_int (DBusHashTable *table,
  *
  * @param table the hash table.
  * @param key the hash key.
+ * @returns #TRUE if the entry existed
  */
-void
+dbus_bool_t
 _dbus_hash_table_remove_string (DBusHashTable *table,
                                 const char    *key)
 {
@@ -937,7 +950,12 @@ _dbus_hash_table_remove_string (DBusHashTable *table,
   entry = (* table->find_function) (table, (char*) key, FALSE, &bucket);
 
   if (entry)
-    remove_entry (table, bucket, entry);
+    {
+      remove_entry (table, bucket, entry);
+      return TRUE;
+    }
+  else
+    return FALSE;
 }
 
 /**
@@ -946,8 +964,9 @@ _dbus_hash_table_remove_string (DBusHashTable *table,
  *
  * @param table the hash table.
  * @param key the hash key.
+ * @returns #TRUE if the entry existed
  */
-void
+dbus_bool_t
 _dbus_hash_table_remove_int (DBusHashTable *table,
                              int            key)
 {
@@ -959,7 +978,12 @@ _dbus_hash_table_remove_int (DBusHashTable *table,
   entry = (* table->find_function) (table, _DBUS_INT_TO_POINTER (key), FALSE, &bucket);
   
   if (entry)
-    remove_entry (table, bucket, entry);
+    {
+      remove_entry (table, bucket, entry);
+      return TRUE;
+    }
+  else
+    return FALSE;
 }
 
 /**
@@ -1056,7 +1080,7 @@ _dbus_hash_table_get_n_entries (DBusHashTable *table)
   return table->n_entries;
 }
 
-/** }@ */
+/** @} */
 
 #ifdef DBUS_BUILD_TESTS
 #include "dbus-test.h"