Index: hurd.texi
===================================================================
RCS file: /sources/hurd/hurd/doc/hurd.texi,v
retrieving revision 1.27
diff -u -r1.27 hurd.texi
--- hurd.texi	22 Jan 2005 17:34:01 -0000	1.27
+++ hurd.texi	14 Apr 2006 22:13:51 -0000
@@ -1221,57 +1221,111 @@
 
 The following functions are declared in @code{<hurd/ihash.h>}:
 
-@deftypefun error_t ihash_create (@w{ihash_t *@var{ht}})
-Create an integer hash table and return it in @var{ht}.  If a memory
-allocation error occurs, @code{ENOMEM} is returned, otherwise zero.
+@deftypefn {Typedef} typedef void (*hurd_ihash_cleanup_t) (@w{hurd_ihash_value_t @var{value}}, @w{void *@var{arg}})
+The type of the cleanup function, which is called for every value
+removed from the hash table.
+@end deftypefn
+
+@deftypefun hurd_ihash_init (@w{hurd_ihash_t @var{ht}}, @w{intptr_t @var{locp_offs}})
+Initialize the hash table at address @var{ht}.  If @var{locp_offset} is not
+@code{HURD_IHASH_NO_LOCP}, then this is an offset (in bytes) from 
+address of a hash value where a location pointer can be found. The
+location pointer must be of type @code{hurd_ihash_locp_t} and can be used
+for fast removal with @code{hurd_ihash_locp_remove}.
 @end deftypefun
 
-@deftypefun void ihash_free (@w{ihash_t @var{ht}})
-Free @var{ht} and all resources it consumes.
+@deftypefun hurd_ihash_destroy (@w{hurd_ihash_t @var{ht}})
+Destroy the hash table at address @var{ht}.  This first removes all
+elements which are still in the hash table, and calling the cleanup
+function for them (if any).  
 @end deftypefun
 
-@deftypefun void ihash_set_cleanup (@w{ihash_t @var{ht}}, @w{void (*@var{cleanup}) (void *@var{value}, void *@var{arg})}, @w{void *@var{arg}})
-Sets @var{ht}'s element cleanup function to @var{cleanup}, and its
-second argument to @var{arg}.  @var{cleanup} will be called on every
-element @var{value} to be subsequently overwritten or deleted, with
-@var{arg} as the second argument.
+@deftypefun error_t hurd_ihash_create (@w{hurd_ihash_t @var{ht}}, @w{intptr_t @var{locp_offs}})
+Create a hash table, initialize it and return it in @var{ht}.  If
+@var{locp_offset} is not @code{HURD_IHASH_NO_LOCP}, then this is an offset (in
+bytes) from the address of a hash value where a location pointer
+can be found.  The location pointer must be of type
+@code{hurd_ihash_locp_t} and can be used for fast removal with
+@code{hurd_ihash_locp_remove}.  If a memory allocation error occurs,
+@code{ENOMEM} is returned, otherwise zero.
+@end deftypefun
+
+@deftypefun void hurd_ihash_free (@w{hurd_ihash_t @var{ht}})
+Destroy the hash table @var{ht} and release the memory allocated for it
+by @code{hurd_ihash_create}.
+@end deftypefun
+
+@deftypefun void hurd_ihash_set_cleanup (@w{hurd_ihash_t @var{ht}}, @w{hurd_ihash_cleanup_t @var{cleanup}}, @w{void *@var{cleanup_data}})
+Set the cleanup function for the hash table @var{ht} to @var{cleanup}.  The
+second argument to @var{cleanup} will be @var{cleanup_data} on every
+invocation.
+@end deftypefun
+
+@deftypefun void hurd_ihash_set_max_load (@w{hurd_ihash_t @var{ht}}, @w{unsigned int @var{max_load}})
+Set the maximum load factor in percent to @var{max_load}, which should be
+between 50 and 100.  The default is @code{HURD_IHASH_MAX_LOAD_DEFAULT}.
+New elements are only added to the hash table while the number of
+hashed elements is that much percent of the total size of the hash
+table.  If more elements are added, the hash table is first
+expanded and reorganized.  A @var{max_load} of 100 will always fill the
+whole table before enlarging it, but note that this will increase
+the cost of operations significantly when the table is almost full.
+
+If the value is set to a smaller value than the current load
+factor, the next reorganization will happen when a new item is
+added to the hash table.
 @end deftypefun
 
-@deftypefun error_t ihash_add (@w{ihash_t @var{ht}}, @w{int @var{id}}, @w{void *@var{item}}, @w{void ***@var{locp}})
-Add @var{item} to the hash table @var{ht} under the integer key
-@var{id}.  @var{locp} is the address of a pointer located in @var{item};
-If non-null, @var{locp} should point to a variable of type @code{void
-**}, and will be filled with a pointer that may be used as an argument
-to @code{ihash_locp_remove}.  The variable pointed to by @var{locp} may
-be overwritten sometime between this call and when the element is
-deleted, so you cannot stash its value elsewhere and hope to use the
-stashed value with @code{ihash_locp_remove}.  If a memory allocation
-error occurs, @code{ENOMEM} is returned, otherwise zero.
+@deftypefun error_t hurd_ihash_add (@w{hurd_ihash_t @var{ht}}, @w{hurd_ihash_key_t @var{key}}, @w{hurd_ihash_value_t @var{item}})
+Add @var{item} to the hash table @var{ht} under the key @var{key}.  If there already
+is an item under this key, call the cleanup function (if any) for
+it before overriding the value.  If a memory allocation error
+occurs, @code{ENOMEM} is returned, otherwise zero.
 @end deftypefun
 
-@deftypefun {void *} ihash_find (@w{ihash_t @var{ht}}, @w{int @var{id}})
-Find and return the item in hash table @var{ht} with key @var{id}.
-Returns null if the specified item doesn't exist.
+@deftypefun hurd_ihash_value_t hurd_ihash_find (@w{hurd_ihash_t @var{ht}}, @w{hurd_ihash_key_t @var{key}})
+Find and return the item in the hash table @var{ht} with key @var{key}, or null
+if it doesn't exist.
 @end deftypefun
 
-@deftypefun error_t ihash_iterate (@w{ihash_t @var{ht}}, @w{error_t (*@var{fun}) (void *@var{value})})
-Call function @var{fun} on every element of @var{ht}.  @var{fun}'s only
-arg, @var{value}, is a pointer to the value stored in the hash table.  If
-@var{fun} ever returns nonzero, then iteration stops and
-@code{ihash_iterate} returns that value, otherwise it (eventually)
-returns 0.
+@deftypefun HURD_IHASH_ITERATE (@w{@var{ht}}, @w{@var{val}})
+Iterate over all elements in the hash table.  You use this macro
+with a block, for example like this:
+
+@example
+error_t err;
+HURD_IHASH_ITERATE (ht, value)
+  @{
+   err = foo (value);
+   if (err)
+     break;
+  @}
+if (err)
+  cleanup_and_return ();
+@end example
+
+Or even like this:
+
+@example
+HURD_IHASH_ITERATE (ht, value)
+  foo (value);
+@end example
+
+The block will be run for every element in the hash table @var{ht}.  The
+value of the current element is available in the variable @var{value}
+(which is declared for you and local to the block).
 @end deftypefun
 
-@deftypefun int ihash_remove (@w{ihash_t @var{ht}}, @w{int @var{id}})
-Remove the entry with a key of @var{id} from @var{ht}.  If there was no
-such element, then return zero, otherwise nonzero.
+@deftypefun int hurd_ihash_remove (@w{hurd_ihash_t @var{ht}}, @w{hurd_ihash_key_t @var{key}})
+Remove the entry with the key @var{key} from the hash table @var{ht}.  If such
+an entry was found and removed, 1 is returned, otherwise 0.
 @end deftypefun
 
-@deftypefun void ihash_locp_remove (@w{ihash_t @var{ht}}, @w{void **@var{ht_locp}})
-Remove the entry at @var{locp} from the hashtable @var{ht}.  @var{locp}
-is as returned from an earlier call to @code{ihash_add}.  This call
-should be faster than @code{ihash_remove}.  @var{ht} can be null, in
-which case the call still succeeds, but no cleanup is done.
+@deftypefun void hurd_ihash_locp_remove (@w{hurd_ihash_t @var{ht}}, @w{hurd_ihash_locp_t @var{locp}})
+Remove the entry pointed to by the location pointer @var{locp} from the
+hash table @var{ht}.  @var{locp} is the location pointer of which the address
+was provided to @code{hurd_ihash_add}.  This call is faster than
+@code{hurd_ihash_remove}.
 @end deftypefun
 
 
