Documentation/technical/api-hash.txt

   1 hash API
   2 ========
   3
   4 The hash API is a collection of simple hash table functions. Users are expected
   5 to implement their own hashing.
   6
   7 Data Structures
   8 ---------------
   9
  10 `struct hash_table`::
  11
  12         The hash table structure. The `array` member points to the hash table
  13         entries. The `size` member counts the total number of valid and invalid
  14         entries in the table. The `nr` member keeps track of the number of
  15         valid entries.
  16
  17 `struct hash_table_entry`::
  18
  19         An opaque structure representing an entry in the hash table. The `hash`
  20         member is the entry's hash key and the `ptr` member is the entry's
  21         value.
  22
  23 Functions
  24 ---------
  25
  26 `init_hash`::
  27
  28         Initialize the hash table.
  29
  30 `free_hash`::
  31
  32         Release memory associated with the hash table.
  33
  34 `insert_hash`::
  35
  36         Insert a pointer into the hash table. If an entry with that hash
  37         already exists, a pointer to the existing entry's value is returned.
  38         Otherwise NULL is returned.  This allows callers to implement
  39         chaining, etc.
  40
  41 `lookup_hash`::
  42
  43         Lookup an entry in the hash table. If an entry with that hash exists
  44         the entry's value is returned. Otherwise NULL is returned.
  45
  46 `for_each_hash`::
  47
  48         Call a function for each entry in the hash table. The function is
  49         expected to take the entry's value as its only argument and return an
  50         int. If the function returns a negative int the loop is aborted
  51         immediately.  Otherwise, the return value is accumulated and the sum
  52         returned upon completion of the loop.