1 /* Licensed to the Apache Software Foundation (ASF) under one or more
2 * contributor license agreements. See the NOTICE file distributed with
3 * this work for additional information regarding copyright ownership.
4 * The ASF licenses this file to You under the Apache License, Version 2.0
5 * (the "License"); you may not use this file except in compliance with
6 * the License. You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
17 #include "apr_private.h"
19 #include "apr_general.h"
20 #include "apr_pools.h"
32 #if APR_POOL_DEBUG && APR_HAVE_STDIO_H
37 * The internal form of a hash table.
39 * The table is an array indexed by the hash of the key; collisions
40 * are resolved by hanging a linked list of hash entries off each
41 * element of the array. Although this is a really simple design it
42 * isn't too bad given that pools have a low allocation overhead.
45 typedef struct apr_hash_entry_t apr_hash_entry_t;
47 struct apr_hash_entry_t {
48 apr_hash_entry_t *next;
56 * Data structure for iterating through a hash table.
58 * We keep a pointer to the next hash entry here to allow the current
59 * hash entry to be freed or otherwise mangled between calls to
62 struct apr_hash_index_t {
64 apr_hash_entry_t *this, *next;
69 * The size of the array is always a power of two. We use the maximum
70 * index rather than the size so that we can use bitwise-AND for
72 * The count of hash entries may be greater depending on the chosen
77 apr_hash_entry_t **array;
78 apr_hash_index_t iterator; /* For apr_hash_first(NULL, ...) */
79 unsigned int count, max, seed;
80 apr_hashfunc_t hash_func;
81 apr_hash_entry_t *free; /* List of recycled entries */
84 #define INITIAL_MAX 15 /* tunable == 2^n - 1 */
88 * Hash creation functions.
91 static apr_hash_entry_t **alloc_array(apr_hash_t *ht, unsigned int max)
93 return apr_pcalloc(ht->pool, sizeof(*ht->array) * (max + 1));
96 APR_DECLARE(apr_hash_t *) apr_hash_make(apr_pool_t *pool)
99 apr_time_t now = apr_time_now();
101 ht = apr_palloc(pool, sizeof(apr_hash_t));
105 ht->max = INITIAL_MAX;
106 ht->seed = (unsigned int)((now >> 32) ^ now ^ (apr_uintptr_t)pool ^
107 (apr_uintptr_t)ht ^ (apr_uintptr_t)&now) - 1;
108 ht->array = alloc_array(ht, ht->max);
109 ht->hash_func = NULL;
114 APR_DECLARE(apr_hash_t *) apr_hash_make_custom(apr_pool_t *pool,
115 apr_hashfunc_t hash_func)
117 apr_hash_t *ht = apr_hash_make(pool);
118 ht->hash_func = hash_func;
124 * Hash iteration functions.
127 APR_DECLARE(apr_hash_index_t *) apr_hash_next(apr_hash_index_t *hi)
131 if (hi->index > hi->ht->max)
134 hi->this = hi->ht->array[hi->index++];
136 hi->next = hi->this->next;
140 APR_DECLARE(apr_hash_index_t *) apr_hash_first(apr_pool_t *p, apr_hash_t *ht)
142 apr_hash_index_t *hi;
144 hi = apr_palloc(p, sizeof(*hi));
152 return apr_hash_next(hi);
155 APR_DECLARE(void) apr_hash_this(apr_hash_index_t *hi,
160 if (key) *key = hi->this->key;
161 if (klen) *klen = hi->this->klen;
162 if (val) *val = (void *)hi->this->val;
167 * Expanding a hash table
170 static void expand_array(apr_hash_t *ht)
172 apr_hash_index_t *hi;
173 apr_hash_entry_t **new_array;
174 unsigned int new_max;
176 new_max = ht->max * 2 + 1;
177 new_array = alloc_array(ht, new_max);
178 for (hi = apr_hash_first(NULL, ht); hi; hi = apr_hash_next(hi)) {
179 unsigned int i = hi->this->hash & new_max;
180 hi->this->next = new_array[i];
181 new_array[i] = hi->this;
183 ht->array = new_array;
187 static unsigned int hashfunc_default(const char *char_key, apr_ssize_t *klen,
190 const unsigned char *key = (const unsigned char *)char_key;
191 const unsigned char *p;
195 * This is the popular `times 33' hash algorithm which is used by
196 * perl and also appears in Berkeley DB. This is one of the best
197 * known hash functions for strings because it is both computed
198 * very fast and distributes very well.
200 * The originator may be Dan Bernstein but the code in Berkeley DB
201 * cites Chris Torek as the source. The best citation I have found
202 * is "Chris Torek, Hash function for text in C, Usenet message
203 * <27038@mimsy.umd.edu> in comp.lang.c , October, 1990." in Rich
204 * Salz's USENIX 1992 paper about INN which can be found at
205 * <http://citeseer.nj.nec.com/salz92internetnews.html>.
207 * The magic of number 33, i.e. why it works better than many other
208 * constants, prime or not, has never been adequately explained by
209 * anyone. So I try an explanation: if one experimentally tests all
210 * multipliers between 1 and 256 (as I did while writing a low-level
211 * data structure library some time ago) one detects that even
212 * numbers are not useable at all. The remaining 128 odd numbers
213 * (except for the number 1) work more or less all equally well.
214 * They all distribute in an acceptable way and this way fill a hash
215 * table with an average percent of approx. 86%.
217 * If one compares the chi^2 values of the variants (see
218 * Bob Jenkins ``Hashing Frequently Asked Questions'' at
219 * http://burtleburtle.net/bob/hash/hashfaq.html for a description
220 * of chi^2), the number 33 not even has the best value. But the
221 * number 33 and a few other equally good numbers like 17, 31, 63,
222 * 127 and 129 have nevertheless a great advantage to the remaining
223 * numbers in the large set of possible multipliers: their multiply
224 * operation can be replaced by a faster operation based on just one
225 * shift plus either a single addition or subtraction operation. And
226 * because a hash function has to both distribute good _and_ has to
227 * be very fast to compute, those few numbers should be preferred.
229 * -- Ralf S. Engelschall <rse@engelschall.com>
232 if (*klen == APR_HASH_KEY_STRING) {
233 for (p = key; *p; p++) {
234 hash = hash * 33 + *p;
239 for (p = key, i = *klen; i; i--, p++) {
240 hash = hash * 33 + *p;
247 APR_DECLARE_NONSTD(unsigned int) apr_hashfunc_default(const char *char_key,
250 return hashfunc_default(char_key, klen, 0);
254 * This is where we keep the details of the hash function and control
255 * the maximum collision rate.
257 * If val is non-NULL it creates and initializes a new hash entry if
258 * there isn't already one there; it returns an updatable pointer so
259 * that hash entries can be removed.
262 static apr_hash_entry_t **find_entry(apr_hash_t *ht,
267 apr_hash_entry_t **hep, *he;
271 hash = ht->hash_func(key, &klen);
273 hash = hashfunc_default(key, &klen, ht->seed);
275 /* scan linked list */
276 for (hep = &ht->array[hash & ht->max], he = *hep;
277 he; hep = &he->next, he = *hep) {
280 && memcmp(he->key, key, klen) == 0)
286 /* add a new entry for non-NULL values */
287 if ((he = ht->free) != NULL)
290 he = apr_palloc(ht->pool, sizeof(*he));
301 APR_DECLARE(apr_hash_t *) apr_hash_copy(apr_pool_t *pool,
302 const apr_hash_t *orig)
305 apr_hash_entry_t *new_vals;
308 ht = apr_palloc(pool, sizeof(apr_hash_t) +
309 sizeof(*ht->array) * (orig->max + 1) +
310 sizeof(apr_hash_entry_t) * orig->count);
313 ht->count = orig->count;
315 ht->seed = orig->seed;
316 ht->hash_func = orig->hash_func;
317 ht->array = (apr_hash_entry_t **)((char *)ht + sizeof(apr_hash_t));
319 new_vals = (apr_hash_entry_t *)((char *)(ht) + sizeof(apr_hash_t) +
320 sizeof(*ht->array) * (orig->max + 1));
322 for (i = 0; i <= ht->max; i++) {
323 apr_hash_entry_t **new_entry = &(ht->array[i]);
324 apr_hash_entry_t *orig_entry = orig->array[i];
326 *new_entry = &new_vals[j++];
327 (*new_entry)->hash = orig_entry->hash;
328 (*new_entry)->key = orig_entry->key;
329 (*new_entry)->klen = orig_entry->klen;
330 (*new_entry)->val = orig_entry->val;
331 new_entry = &((*new_entry)->next);
332 orig_entry = orig_entry->next;
339 APR_DECLARE(void *) apr_hash_get(apr_hash_t *ht,
343 apr_hash_entry_t *he;
344 he = *find_entry(ht, key, klen, NULL);
346 return (void *)he->val;
351 APR_DECLARE(void) apr_hash_set(apr_hash_t *ht,
356 apr_hash_entry_t **hep;
357 hep = find_entry(ht, key, klen, val);
361 apr_hash_entry_t *old = *hep;
363 old->next = ht->free;
370 /* check that the collision rate isn't too high */
371 if (ht->count > ht->max) {
376 /* else key not present and val==NULL */
379 APR_DECLARE(unsigned int) apr_hash_count(apr_hash_t *ht)
384 APR_DECLARE(void) apr_hash_clear(apr_hash_t *ht)
386 apr_hash_index_t *hi;
387 for (hi = apr_hash_first(NULL, ht); hi; hi = apr_hash_next(hi))
388 apr_hash_set(ht, hi->this->key, hi->this->klen, NULL);
391 APR_DECLARE(apr_hash_t*) apr_hash_overlay(apr_pool_t *p,
392 const apr_hash_t *overlay,
393 const apr_hash_t *base)
395 return apr_hash_merge(p, overlay, base, NULL, NULL);
398 APR_DECLARE(apr_hash_t *) apr_hash_merge(apr_pool_t *p,
399 const apr_hash_t *overlay,
400 const apr_hash_t *base,
401 void * (*merger)(apr_pool_t *p,
410 apr_hash_entry_t *new_vals = NULL;
411 apr_hash_entry_t *iter;
412 apr_hash_entry_t *ent;
413 unsigned int i, j, k, hash;
416 /* we don't copy keys and values, so it's necessary that
417 * overlay->a.pool and base->a.pool have a life span at least
420 if (!apr_pool_is_ancestor(overlay->pool, p)) {
422 "apr_hash_merge: overlay's pool is not an ancestor of p\n");
425 if (!apr_pool_is_ancestor(base->pool, p)) {
427 "apr_hash_merge: base's pool is not an ancestor of p\n");
432 res = apr_palloc(p, sizeof(apr_hash_t));
435 res->hash_func = base->hash_func;
436 res->count = base->count;
437 res->max = (overlay->max > base->max) ? overlay->max : base->max;
438 if (base->count + overlay->count > res->max) {
439 res->max = res->max * 2 + 1;
441 res->seed = base->seed;
442 res->array = alloc_array(res, res->max);
443 if (base->count + overlay->count) {
444 new_vals = apr_palloc(p, sizeof(apr_hash_entry_t) *
445 (base->count + overlay->count));
448 for (k = 0; k <= base->max; k++) {
449 for (iter = base->array[k]; iter; iter = iter->next) {
450 i = iter->hash & res->max;
451 new_vals[j].klen = iter->klen;
452 new_vals[j].key = iter->key;
453 new_vals[j].val = iter->val;
454 new_vals[j].hash = iter->hash;
455 new_vals[j].next = res->array[i];
456 res->array[i] = &new_vals[j];
461 for (k = 0; k <= overlay->max; k++) {
462 for (iter = overlay->array[k]; iter; iter = iter->next) {
464 hash = res->hash_func(iter->key, &iter->klen);
466 hash = hashfunc_default(iter->key, &iter->klen, res->seed);
468 for (ent = res->array[i]; ent; ent = ent->next) {
469 if ((ent->klen == iter->klen) &&
470 (memcmp(ent->key, iter->key, iter->klen) == 0)) {
472 ent->val = (*merger)(p, iter->key, iter->klen,
473 iter->val, ent->val, data);
476 ent->val = iter->val;
482 new_vals[j].klen = iter->klen;
483 new_vals[j].key = iter->key;
484 new_vals[j].val = iter->val;
485 new_vals[j].hash = hash;
486 new_vals[j].next = res->array[i];
487 res->array[i] = &new_vals[j];
496 /* This is basically the following...
497 * for every element in hash table {
498 * comp elemeny.key, element.value
501 * Like with apr_table_do, the comp callback is called for each and every
502 * element of the hash table.
504 APR_DECLARE(int) apr_hash_do(apr_hash_do_callback_fn_t *comp,
505 void *rec, const apr_hash_t *ht)
507 apr_hash_index_t hix;
508 apr_hash_index_t *hi;
511 hix.ht = (apr_hash_t *)ht;
516 if ((hi = apr_hash_next(&hix))) {
517 /* Scan the entire table */
519 rv = (*comp)(rec, hi->this->key, hi->this->klen, hi->this->val);
520 } while (rv && (hi = apr_hash_next(hi)));
529 APR_POOL_IMPLEMENT_ACCESSOR(hash)