Merged silc_1_0_branch to trunk.

[silc.git] / lib / silcutil / silchashtable.h

diff --git a/lib/silcutil/silchashtable.h b/lib/silcutil/silchashtable.h
index 9c4c823cc035a24eaff48574eafe69ed3d6695b6..478ea184a6a23128f8d710c899bb26a4de2a151b 100644 (file)
--- a/lib/silcutil/silchashtable.h
+++ b/lib/silcutil/silchashtable.h
@@ -17,7 +17,7 @@
 
 */
 
-/****h* silcutil/SilcHashTableAPI
+/****h* silcutil/SILC Hash Table Interface
  *
  * DESCRIPTION
  *
@@ -33,7 +33,7 @@
  * an extended interface where caller can specify its own hash and comparison
  * functions.
  *
- * There are two ways tro traverse the entire hash table if this feature
+ * There are two ways to traverse the entire hash table if this feature
  * is needed. There exists a foreach function that calls a foreach
  * callback for each entry in the hash table. Other way is to use
  * SilcHashTableList structure and traverse the hash table inside while()
@@ -89,8 +89,8 @@ typedef struct SilcHashTableListStruct SilcHashTableList;
 struct SilcHashTableListStruct {
   SilcHashTable ht;
   void *entry;
-  uint32 index;
-  bool auto_rehash;
+  unsigned int index        : 31;
+  unsigned int auto_rehash  : 1;
 };
 /***/
 
@@ -98,7 +98,7 @@ struct SilcHashTableListStruct {
  *
  * SYNOPSIS
  *
- *    typedef uint32 (*SilcHashFunction)(void *key, void *user_context);
+ *    typedef SilcUInt32 (*SilcHashFunction)(void *key, void *user_context);
  *
  * DESCRIPTION
  *
@@ -108,7 +108,7 @@ struct SilcHashTableListStruct {
  *    to the callback.
  *
  ***/
-typedef uint32 (*SilcHashFunction)(void *key, void *user_context);
+typedef SilcUInt32 (*SilcHashFunction)(void *key, void *user_context);
 
 /****f* silcutil/SilcHashTableAPI/SilcHashCompare
  *
@@ -138,7 +138,7 @@ typedef bool (*SilcHashCompare)(void *key1, void *key2, void *user_context);
  * DESCRIPTION
  *
  *    A destructor callback that the library will call to destroy the 
- *    `key' and `context'.  The appliation provides the function when
+ *    `key' and `context'.  The application provides the function when
  *    allocating a new hash table. The `user_context' is application
  *    specific context and is delivered to the callback.
  *
@@ -168,7 +168,7 @@ typedef void (*SilcHashForeach)(void *key, void *context, void *user_context);
  *
  * SYNOPSIS
  *
- *    SilcHashTable silc_hash_table_alloc(uint32 table_size, 
+ *    SilcHashTable silc_hash_table_alloc(SilcUInt32 table_size, 
  *                                        SilcHashFunction hash,
  *                                        void *hash_user_context,
  *                                        SilcHashCompare compare,
@@ -188,7 +188,7 @@ typedef void (*SilcHashForeach)(void *key, void *context, void *user_context);
  *    are optional.
  *
  ***/
-SilcHashTable silc_hash_table_alloc(uint32 table_size, 
+SilcHashTable silc_hash_table_alloc(SilcUInt32 table_size, 
                                    SilcHashFunction hash,
                                    void *hash_user_context,
                                    SilcHashCompare compare,
@@ -215,7 +215,7 @@ void silc_hash_table_free(SilcHashTable ht);
  *
  * SYNOPSIS
  *
- *    uint32 silc_hash_table_size(SilcHashTable ht);
+ *    SilcUInt32 silc_hash_table_size(SilcHashTable ht);
  *
  * DESCRIPTION
  *
@@ -223,13 +223,13 @@ void silc_hash_table_free(SilcHashTable ht);
  *    hash table.
  *
  ***/
-uint32 silc_hash_table_size(SilcHashTable ht);
+SilcUInt32 silc_hash_table_size(SilcHashTable ht);
 
 /****f* silcutil/SilcHashTableAPI/silc_hash_table_count
  *
  * SYNOPSIS
  *
- *    uint32 silc_hash_table_count(SilcHashTable ht);
+ *    SilcUInt32 silc_hash_table_count(SilcHashTable ht);
  *
  * DESCRIPTION
  *
@@ -238,7 +238,7 @@ uint32 silc_hash_table_size(SilcHashTable ht);
  *    silc_hash_table_rehash is recommended.
  *
  ***/
-uint32 silc_hash_table_count(SilcHashTable ht);
+SilcUInt32 silc_hash_table_count(SilcHashTable ht);
 
 /****f* silcutil/SilcHashTableAPI/silc_hash_table_add
  *
@@ -324,6 +324,27 @@ bool silc_hash_table_del_by_context(SilcHashTable ht, void *key,
 bool silc_hash_table_find(SilcHashTable ht, void *key,
                          void **ret_key, void **ret_context);
 
+/****f* silcutil/SilcHashTableAPI/silc_hash_table_find_by_context
+ *
+ * SYNOPSIS
+ *
+ *    bool silc_hash_table_find_by_context(SilcHashTable ht, void *key,
+ *                                         void *context, void **ret_key);
+ *
+ * DESCRIPTION
+ *
+ *    Finds the entry in the hash table by the provided `key' and
+ *    `context' as fast as possible.  This is handy function when there
+ *    can be multiple same keys in the hash table.  By using this function
+ *    the specific key with specific context can be found.  Return
+ *    TRUE if the entry with the key and context was found and FALSE
+ *    otherwise.  The function returns only the key to `ret_key' since
+ *    the caller already knows the context.
+ *
+ ***/
+bool silc_hash_table_find_by_context(SilcHashTable ht, void *key,
+                                    void *context, void **ret_key);
+
 /****f* silcutil/SilcHashTableAPI/silc_hash_table_find_foreach
  *
  * SYNOPSIS
@@ -337,7 +358,9 @@ bool silc_hash_table_find(SilcHashTable ht, void *key,
  *    As the hash table is collision resistant it is possible to save duplicate
  *    keys to the hash table. This function can be used to find all keys
  *    and contexts from the hash table that are found using the `key'. The
- *    `foreach' is called for every found key.
+ *    `foreach' is called for every found key. If no entries can be found
+ *    the `foreach' will be called once with the context set NULL and
+ *    `key' and `user_context' sent to the function.
  *
  * NOTES
  *
@@ -375,7 +398,7 @@ void silc_hash_table_foreach(SilcHashTable ht, SilcHashForeach foreach,
  *
  * SYNOPSIS
  *
- *    void silc_hash_table_rehash(SilcHashTable ht, uint32 new_size);
+ *    void silc_hash_table_rehash(SilcHashTable ht, SilcUInt32 new_size);
  *
  * DESCRIPTION
  *
@@ -385,7 +408,7 @@ void silc_hash_table_foreach(SilcHashTable ht, SilcHashForeach foreach,
  *    very slow.
  *
  ***/
-void silc_hash_table_rehash(SilcHashTable ht, uint32 new_size);
+void silc_hash_table_rehash(SilcHashTable ht, SilcUInt32 new_size);
 
 /****f* silcutil/SilcHashTableAPI/silc_hash_table_list
  *
@@ -609,7 +632,9 @@ bool silc_hash_table_find_ext(SilcHashTable ht, void *key,
  *    As the hash table is collision resistant it is possible to save duplicate
  *    keys to the hash table. This function can be used to find all keys
  *    and contexts from the hash table that are found using the `key'. The
- *    `foreach' is called for every found key.
+ *    `foreach' is called for every found key. If no entries can be found
+ *    the `foreach' will be called once with the context set NULL and
+ *    `key' and `user_context' sent to the function.
  *
  *    The `hash' and `hash_user_context' are application specified hash
  *    function. If not provided the hash table's default is used.
@@ -635,7 +660,7 @@ void silc_hash_table_find_foreach_ext(SilcHashTable ht, void *key,
  *
  * SYNOPSIS
  *
- *    void silc_hash_table_rehash_ext(SilcHashTable ht, uint32 new_size,
+ *    void silc_hash_table_rehash_ext(SilcHashTable ht, SilcUInt32 new_size,
  *                                    SilcHashFunction hash, 
  *                                    void *hash_user_context);
  *
@@ -650,7 +675,7 @@ void silc_hash_table_find_foreach_ext(SilcHashTable ht, void *key,
  *    function. If not provided the hash table's default is used.
  *
  ***/
-void silc_hash_table_rehash_ext(SilcHashTable ht, uint32 new_size,
+void silc_hash_table_rehash_ext(SilcHashTable ht, SilcUInt32 new_size,
                                SilcHashFunction hash, 
                                void *hash_user_context);