4e87aee8242257f364861be8061b18c41749ab1c
[openssl.git] / 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 OPENSSL_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