198 lines
7.8 KiB
Text
198 lines
7.8 KiB
Text
=pod
|
|
|
|
=head1 NAME
|
|
|
|
lh_new, lh_free, lh_insert, lh_delete, lh_retrieve, lh_doall,
|
|
lh_doall_arg, lh_error - dynamic hash table
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
#include <openssl/lhash.h>
|
|
|
|
LHASH *lh_new(LHASH_HASH_FN_TYPE hash, LHASH_COMP_FN_TYPE compare);
|
|
void lh_free(LHASH *table);
|
|
|
|
void *lh_insert(LHASH *table, void *data);
|
|
void *lh_delete(LHASH *table, void *data);
|
|
void *lh_retrieve(LHASH *table, void *data);
|
|
|
|
void lh_doall(LHASH *table, LHASH_DOALL_FN_TYPE func);
|
|
void lh_doall_arg(LHASH *table, LHASH_DOALL_ARG_FN_TYPE func,
|
|
void *arg);
|
|
|
|
int lh_error(LHASH *table);
|
|
|
|
typedef int (*LHASH_COMP_FN_TYPE)(void *, void *);
|
|
typedef unsigned long (*LHASH_HASH_FN_TYPE)(void *);
|
|
typedef void (*LHASH_DOALL_FN_TYPE)(void *);
|
|
typedef void (*LHASH_DOALL_ARG_FN_TYPE)(void *, void *);
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
This library implements dynamic hash tables. The hash table entries
|
|
can be arbitrary structures. Usually they consist of key and value
|
|
fields.
|
|
|
|
lh_new() creates a new B<LHASH> structure. B<hash> takes a pointer to
|
|
the structure and returns an unsigned long hash value of its key
|
|
field. The hash value is normally truncated to a power of 2, so make
|
|
sure that your hash function returns well mixed low order
|
|
bits. B<compare> takes two arguments, and returns 0 if their keys are
|
|
equal, non-zero otherwise. If your hash table will contain items of
|
|
some uniform type, and similarly the B<hash> and B<compare> callbacks
|
|
hash or compare the same type, then the B<DECLARE_LHASH_HASH_FN> and
|
|
B<IMPLEMENT_LHASH_COMP_FN> macros can be used to create callback
|
|
wrappers of the prototypes required in lh_new(). These provide
|
|
per-variable casts before calling the type-specific callbacks written
|
|
by the application author. These macros are defined as;
|
|
|
|
#define DECLARE_LHASH_HASH_FN(f_name,o_type) \
|
|
unsigned long f_name##_LHASH_HASH(void *);
|
|
#define IMPLEMENT_LHASH_HASH_FN(f_name,o_type) \
|
|
unsigned long f_name##_LHASH_HASH(void *arg) { \
|
|
o_type a = (o_type)arg; \
|
|
return f_name(a); }
|
|
#define LHASH_HASH_FN(f_name) f_name##_LHASH_HASH
|
|
|
|
#define DECLARE_LHASH_COMP_FN(f_name,o_type) \
|
|
int f_name##_LHASH_COMP(void *, void *);
|
|
#define IMPLEMENT_LHASH_COMP_FN(f_name,o_type) \
|
|
int f_name##_LHASH_COMP(void *arg1, void *arg2) { \
|
|
o_type a = (o_type)arg1; \
|
|
o_type b = (o_type)arg2; \
|
|
return f_name(a,b); }
|
|
#define LHASH_COMP_FN(f_name) f_name##_LHASH_COMP
|
|
|
|
An example of a hash table storing (pointers to) a structure type 'foo'
|
|
could be defined as follows;
|
|
|
|
unsigned long foo_hash(foo *tohash);
|
|
int foo_compare(foo *arg1, foo *arg2);
|
|
static IMPLEMENT_LHASH_HASH_FN(foo_hash, foo *)
|
|
static IMPLEMENT_LHASH_COMP_FN(foo_compare, foo *);
|
|
/* ... */
|
|
int main(int argc, char *argv[]) {
|
|
LHASH *hashtable = lh_new(LHASH_HASH_FN(foo_hash),
|
|
LHASH_COMP_FN(foo_compare));
|
|
/* ... */
|
|
}
|
|
|
|
lh_free() frees the B<LHASH> structure B<table>. Allocated hash table
|
|
entries will not be freed; consider using lh_doall() to deallocate any
|
|
remaining entries in the hash table.
|
|
|
|
lh_insert() inserts the structure pointed to by B<data> into B<table>.
|
|
If there already is an entry with the same key, the old value is
|
|
replaced. Note that lh_insert() stores pointers, the data are not
|
|
copied.
|
|
|
|
lh_delete() deletes an entry from B<table>.
|
|
|
|
lh_retrieve() looks up an entry in B<table>. Normally, B<data> is
|
|
a structure with the key field(s) set; the function will return a
|
|
pointer to a fully populated structure.
|
|
|
|
lh_doall() will, for every entry in the hash table, call B<func> with
|
|
the data item as parameters.
|
|
This function can be quite useful when used as follows:
|
|
void cleanup(STUFF *a)
|
|
{ STUFF_free(a); }
|
|
lh_doall(hash,(LHASH_DOALL_FN_TYPE)cleanup);
|
|
lh_free(hash);
|
|
This can be used to free all the entries. lh_free() then cleans up the
|
|
'buckets' that point to nothing. When doing this, be careful if you
|
|
delete entries from the hash table in B<func>: the table may decrease
|
|
in size, moving item that you are currently on down lower in the hash
|
|
table. This could cause some entries to be skipped. The best
|
|
solution to this problem is to set hash-E<gt>down_load=0 before you
|
|
start. This will stop the hash table ever being decreased in size.
|
|
|
|
lh_doall_arg() is the same as lh_doall() except that B<func> will
|
|
be called with B<arg> as the second argument and B<func> should be
|
|
of type B<LHASH_DOALL_ARG_FN_TYPE> (a callback prototype that is
|
|
passed an extra argument).
|
|
|
|
lh_error() can be used to determine if an error occurred in the last
|
|
operation. lh_error() is a macro.
|
|
|
|
=head1 RETURN VALUES
|
|
|
|
lh_new() returns B<NULL> on error, otherwise a pointer to the new
|
|
B<LHASH> structure.
|
|
|
|
When a hash table entry is replaced, lh_insert() returns the value
|
|
being replaced. B<NULL> is returned on normal operation and on error.
|
|
|
|
lh_delete() returns the entry being deleted. B<NULL> is returned if
|
|
there is no such value in the hash table.
|
|
|
|
lh_retrieve() returns the hash table entry if it has been found,
|
|
B<NULL> otherwise.
|
|
|
|
lh_error() returns 1 if an error occurred in the last operation, 0
|
|
otherwise.
|
|
|
|
lh_free(), lh_doall() and lh_doall_arg() return no values.
|
|
|
|
=head1 BUGS
|
|
|
|
lh_insert() returns B<NULL> both for success and error.
|
|
|
|
=head1 INTERNALS
|
|
|
|
The following description is based on the SSLeay documentation:
|
|
|
|
The B<lhash> library implements a hash table described in the
|
|
I<Communications of the ACM> in 1991. What makes this hash table
|
|
different is that as the table fills, the hash table is increased (or
|
|
decreased) in size via OPENSSL_realloc(). When a 'resize' is done, instead of
|
|
all hashes being redistributed over twice as many 'buckets', one
|
|
bucket is split. So when an 'expand' is done, there is only a minimal
|
|
cost to redistribute some values. Subsequent inserts will cause more
|
|
single 'bucket' redistributions but there will never be a sudden large
|
|
cost due to redistributing all the 'buckets'.
|
|
|
|
The state for a particular hash table is kept in the B<LHASH> structure.
|
|
The decision to increase or decrease the hash table size is made
|
|
depending on the 'load' of the hash table. The load is the number of
|
|
items in the hash table divided by the size of the hash table. The
|
|
default values are as follows. If (hash->up_load E<lt> load) =E<gt>
|
|
expand. if (hash-E<gt>down_load E<gt> load) =E<gt> contract. The
|
|
B<up_load> has a default value of 1 and B<down_load> has a default value
|
|
of 2. These numbers can be modified by the application by just
|
|
playing with the B<up_load> and B<down_load> variables. The 'load' is
|
|
kept in a form which is multiplied by 256. So
|
|
hash-E<gt>up_load=8*256; will cause a load of 8 to be set.
|
|
|
|
If you are interested in performance the field to watch is
|
|
num_comp_calls. The hash library keeps track of the 'hash' value for
|
|
each item so when a lookup is done, the 'hashes' are compared, if
|
|
there is a match, then a full compare is done, and
|
|
hash-E<gt>num_comp_calls is incremented. If num_comp_calls is not equal
|
|
to num_delete plus num_retrieve it means that your hash function is
|
|
generating hashes that are the same for different values. It is
|
|
probably worth changing your hash function if this is the case because
|
|
even if your hash table has 10 items in a 'bucket', it can be searched
|
|
with 10 B<unsigned long> compares and 10 linked list traverses. This
|
|
will be much less expensive that 10 calls to you compare function.
|
|
|
|
lh_strhash() is a demo string hashing function:
|
|
|
|
unsigned long lh_strhash(const char *c);
|
|
|
|
Since the B<LHASH> routines would normally be passed structures, this
|
|
routine would not normally be passed to lh_new(), rather it would be
|
|
used in the function passed to lh_new().
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<lh_stats(3)|lh_stats(3)>
|
|
|
|
=head1 HISTORY
|
|
|
|
The B<lhash> library is available in all versions of SSLeay and OpenSSL.
|
|
lh_error() was added in SSLeay 0.9.1b.
|
|
|
|
This manpage is derived from the SSLeay documentation.
|
|
|
|
=cut
|