doc/crypto/lhash.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 lh_new, lh_free, lh_insert, lh_delete, lh_retrieve, lh_doall,
   6 lh_doall_arg, lh_error - dynamic hash table
   7
   8 =head1 SYNOPSIS
   9
  10  #include <openssl/lhash.h>
  11
  12  LHASH *lh_new(unsigned long (*hash)(/*void *a*/),
  13           int (*compare)(/*void *a,void *b*/));
  14  void lh_free(LHASH *table);
  15
  16  void *lh_insert(LHASH *table, void *data);
  17  void *lh_delete(LHASH *table, void *data);
  18  void *lh_retrieve(LHASH *table, void *data);
  19
  20  void lh_doall(LHASH *table, void (*func)(/*void *b*/));
  21  void lh_doall_arg(LHASH *table, void (*func)(/*void *a,void *b*/),
  22           void *arg);
  23
  24  int lh_error(LHASH *table);
  25
  26 =head1 DESCRIPTION
  27
  28 This library implements dynamic hash tables. The hash table entries
  29 can be arbitrary structures. Usually they consist of key and value
  30 fields.
  31
  32 lh_new() creates a new B<LHASH> structure. B<hash> takes a pointer to
  33 the structure and returns an unsigned long hash value of its key
  34 field. The hash value is normally truncated to a power of 2, so make
  35 sure that your hash function returns well mixed low order
  36 bits. B<compare> takes two arguments, and returns 0 if their keys are
  37 equal, non-zero otherwise.
  38
  39 lh_free() frees the B<LHASH> structure B<table>. Allocated hash table
  40 entries will not be freed; consider using lh_doall() to deallocate any
  41 remaining entries in the hash table.
  42
  43 lh_insert() inserts the structure pointed to by B<data> into B<table>.
  44 If there already is an entry with the same key, the old value is
  45 replaced. Note that lh_insert() stores pointers, the data are not
  46 copied.
  47
  48 lh_delete() deletes an entry from B<table>.
  49
  50 lh_retrieve() looks up an entry in B<table>. Normally, B<data> is
  51 a structure with the key field(s) set; the function will return a
  52 pointer to a fully populated structure.
  53
  54 lh_doall() will, for every entry in the hash table, call B<func> with
  55 the data item as parameters.
  56 This function can be quite useful when used as follows:
  57  void cleanup(STUFF *a)
  58   { STUFF_free(a); }
  59  lh_doall(hash,cleanup);
  60  lh_free(hash);
  61 This can be used to free all the entries. lh_free() then cleans up the
  62 'buckets' that point to nothing. When doing this, be careful if you
  63 delete entries from the hash table in B<func>: the table may decrease
  64 in size, moving item that you are currently on down lower in the hash
  65 table.  This could cause some entries to be skipped.  The best
  66 solution to this problem is to set hash-E<gt>down_load=0 before you
  67 start.  This will stop the hash table ever being decreased in size.
  68
  69 lh_doall_arg() is the same as lh_doall() except that B<func> will
  70 be called with B<arg> as the second argument.
  71
  72 lh_error() can be used to determine if an error occurred in the last
  73 operation. lh_error() is a macro.
  74
  75 =head1 RETURN VALUES
  76
  77 lh_new() returns B<NULL> on error, otherwise a pointer to the new
  78 B<LHASH> structure.
  79
  80 When a hash table entry is replaced, lh_insert() returns the value
  81 being replaced. B<NULL> is returned on normal operation and on error.
  82
  83 lh_delete() returns the entry being deleted.  B<NULL> is returned if
  84 there is no such value in the hash table.
  85
  86 lh_retrieve() returns the hash table entry if it has been found,
  87 B<NULL> otherwise.
  88
  89 lh_error() returns 1 if an error occurred in the last operation, 0
  90 otherwise.
  91
  92 lh_free(), lh_doall() and lh_doall_arg() return no values.
  93
  94 =head1 BUGS
  95
  96 lh_insert() returns B<NULL> both for success and error.
  97
  98 =head1 INTERNALS
  99
 100 The following description is based on the SSLeay documentation:
 101
 102 The B<lhash> library implements a hash table described in the
 103 I<Communications of the ACM> in 1991.  What makes this hash table
 104 different is that as the table fills, the hash table is increased (or
 105 decreased) in size via Realloc().  When a 'resize' is done, instead of
 106 all hashes being redistributed over twice as many 'buckets', one
 107 bucket is split.  So when an 'expand' is done, there is only a minimal
 108 cost to redistribute some values.  Subsequent inserts will cause more
 109 single 'bucket' redistributions but there will never be a sudden large
 110 cost due to redistributing all the 'buckets'.
 111
 112 The state for a particular hash table is kept in the B<LHASH> structure.
 113 The decision to increase or decrease the hash table size is made
 114 depending on the 'load' of the hash table.  The load is the number of
 115 items in the hash table divided by the size of the hash table.  The
 116 default values are as follows.  If (hash->up_load E<lt> load) =E<gt>
 117 expand.  if (hash-E<gt>down_load E<gt> load) =E<gt> contract.  The
 118 B<up_load> has a default value of 1 and B<down_load> has a default value
 119 of 2.  These numbers can be modified by the application by just
 120 playing with the B<up_load> and B<down_load> variables.  The 'load' is
 121 kept in a form which is multiplied by 256.  So
 122 hash-E<gt>up_load=8*256; will cause a load of 8 to be set.
 123
 124 If you are interested in performance the field to watch is
 125 num_comp_calls.  The hash library keeps track of the 'hash' value for
 126 each item so when a lookup is done, the 'hashes' are compared, if
 127 there is a match, then a full compare is done, and
 128 hash-E<gt>num_comp_calls is incremented.  If num_comp_calls is not equal
 129 to num_delete plus num_retrieve it means that your hash function is
 130 generating hashes that are the same for different values.  It is
 131 probably worth changing your hash function if this is the case because
 132 even if your hash table has 10 items in a 'bucket', it can be searched
 133 with 10 B<unsigned long> compares and 10 linked list traverses.  This
 134 will be much less expensive that 10 calls to you compare function.
 135
 136 lh_strhash() is a demo string hashing function:
 137
 138  unsigned long lh_strhash(const char *c);
 139
 140 Since the B<LHASH> routines would normally be passed structures, this
 141 routine would not normally be passed to lh_new(), rather it would be
 142 used in the function passed to lh_new().
 143
 144 =head1 SEE ALSO
 145
 146 L<lh_stats(3)|lh_stats(3)>
 147
 148 =head1 HISTORY
 149
 150 The B<lhash> library is available in all versions of SSLeay and OpenSSL.
 151 lh_error() was added in SSLeay 0.9.1b.
 152
 153 This manpage is derived from the SSLeay documentation.
 154
 155 =cut