tor: ht.h Source File

00001 /* Copyright (c) 2002, Christopher Clark.
00002  * Copyright (c) 2005-2006, Nick Mathewson.
00003  * Copyright (c) 2007-2010, The Tor Project, Inc. */
00004 /* See license at end. */
00005 
00006 /* Based on ideas by Christopher Clark and interfaces from Niels Provos. */
00007 
00008 #ifndef _TOR_HT_H
00009 #define _TOR_HT_H
00010 
00011 #define HT_HEAD(name, type)                                             \
00012   struct name {                                                         \
00013     /* The hash table itself. */                                        \
00014     struct type **hth_table;                                            \
00015     /* How long is the hash table? */                                   \
00016     unsigned hth_table_length;                                          \
00017     /* How many elements does the table contain? */                     \
00018     unsigned hth_n_entries;                                             \
00019     /* How many elements will we allow in the table before resizing it? */ \
00020     unsigned hth_load_limit;                                            \
00021     /* Position of hth_table_length in the primes table. */             \
00022     int hth_prime_idx;                                                  \
00023   }
00024 
00025 #define HT_INITIALIZER()                        \
00026   { NULL, 0, 0, 0, -1 }
00027 
00028 #define HT_ENTRY(type)                          \
00029   struct {                                      \
00030     struct type *hte_next;                      \
00031     unsigned hte_hash;                          \
00032   }
00033 
00034 #define HT_EMPTY(head)                          \
00035   ((head)->hth_n_entries == 0)
00036 
00037 /* Helper: alias for the bucket containing 'elm'. */
00038 #define _HT_BUCKET(head, field, elm)                                    \
00039   ((head)->hth_table[elm->field.hte_hash % head->hth_table_length])
00040 
00041 /* How many elements in 'head'? */
00042 #define HT_SIZE(head)                           \
00043   ((head)->hth_n_entries)
00044 
00045 /* Return memory usage for a hashtable (not counting the entries themselves) */
00046 #define HT_MEM_USAGE(head)                         \
00047   (sizeof(*head) + (head)->hth_table_length * sizeof(void*))
00048 
00049 #define HT_FIND(name, head, elm)     name##_HT_FIND((head), (elm))
00050 #define HT_INSERT(name, head, elm)   name##_HT_INSERT((head), (elm))
00051 #define HT_REPLACE(name, head, elm)  name##_HT_REPLACE((head), (elm))
00052 #define HT_REMOVE(name, head, elm)   name##_HT_REMOVE((head), (elm))
00053 #define HT_START(name, head)         name##_HT_START(head)
00054 #define HT_NEXT(name, head, elm)     name##_HT_NEXT((head), (elm))
00055 #define HT_NEXT_RMV(name, head, elm) name##_HT_NEXT_RMV((head), (elm))
00056 #define HT_CLEAR(name, head)         name##_HT_CLEAR(head)
00057 #define HT_INIT(name, head)          name##_HT_INIT(head)
00058 /* Helper: */
00059 static INLINE unsigned
00060 ht_improve_hash(unsigned h)
00061 {
00062   /* Aim to protect against poor hash functions by adding logic here
00063    * - logic taken from java 1.4 hashtable source */
00064   h += ~(h << 9);
00065   h ^=  ((h >> 14) | (h << 18)); /* >>> */
00066   h +=  (h << 4);
00067   h ^=  ((h >> 10) | (h << 22)); /* >>> */
00068   return h;
00069 }
00070 
00071 #if 0
00072 
00073 static INLINE unsigned
00074 ht_string_hash(const char *s)
00075 {
00076   unsigned h = 0;
00077   int m = 1;
00078   while (*s) {
00079     h += ((signed char)*s++)*m;
00080     m = (m<<5)-1; /* m *= 31 */
00081   }
00082   return h;
00083 }
00084 #endif
00085 
00087 static INLINE unsigned
00088 ht_string_hash(const char *s)
00089 {
00090   unsigned h;
00091   const unsigned char *cp = (const unsigned char *)s;
00092   h = *cp << 7;
00093   while (*cp) {
00094     h = (1000003*h) ^ *cp++;
00095   }
00096   /* This conversion truncates the length of the string, but that's ok. */
00097   h ^= (unsigned)(cp-(const unsigned char*)s);
00098   return h;
00099 }
00100 
00101 #define _HT_SET_HASH(elm, field, hashfn)        \
00102     (elm)->field.hte_hash = hashfn(elm)
00103 
00104 #define HT_FOREACH(x, name, head)                 \
00105   for ((x) = HT_START(name, head);                \
00106        (x) != NULL;                               \
00107        (x) = HT_NEXT(name, head, x))
00108 
00109 #define HT_PROTOTYPE(name, type, field, hashfn, eqfn)                   \
00110   int name##_HT_GROW(struct name *ht, unsigned min_capacity);           \
00111   void name##_HT_CLEAR(struct name *ht);                                \
00112   int _##name##_HT_REP_IS_BAD(const struct name *ht);                   \
00113   static INLINE void                                                    \
00114   name##_HT_INIT(struct name *head) {                                   \
00115     head->hth_table_length = 0;                                         \
00116     head->hth_table = NULL;                                             \
00117     head->hth_n_entries = 0;                                            \
00118     head->hth_load_limit = 0;                                           \
00119     head->hth_prime_idx = -1;                                           \
00120   }                                                                     \
00121   /* Helper: returns a pointer to the right location in the table       \
00122    * 'head' to find or insert the element 'elm'. */                     \
00123   static INLINE struct type **                                          \
00124   _##name##_HT_FIND_P(struct name *head, struct type *elm)              \
00125   {                                                                     \
00126     struct type **p;                                                    \
00127     if (!head->hth_table)                                               \
00128       return NULL;                                                      \
00129     p = &_HT_BUCKET(head, field, elm);                                  \
00130     while (*p) {                                                        \
00131       if (eqfn(*p, elm))                                                \
00132         return p;                                                       \
00133       p = &(*p)->field.hte_next;                                        \
00134     }                                                                   \
00135     return p;                                                           \
00136   }                                                                     \
00137   /* Return a pointer to the element in the table 'head' matching 'elm', \
00138    * or NULL if no such element exists */                               \
00139   static INLINE struct type *                                           \
00140   name##_HT_FIND(const struct name *head, struct type *elm)             \
00141   {                                                                     \
00142     struct type **p;                                                    \
00143     struct name *h = (struct name *) head;                              \
00144     _HT_SET_HASH(elm, field, hashfn);                                   \
00145     p = _##name##_HT_FIND_P(h, elm);                                    \
00146     return p ? *p : NULL;                                               \
00147   }                                                                     \
00148   /* Insert the element 'elm' into the table 'head'.  Do not call this  \
00149    * function if the table might already contain a matching element. */ \
00150   static INLINE void                                                    \
00151   name##_HT_INSERT(struct name *head, struct type *elm)                 \
00152   {                                                                     \
00153     struct type **p;                                                    \
00154     if (!head->hth_table || head->hth_n_entries >= head->hth_load_limit) \
00155       name##_HT_GROW(head, head->hth_n_entries+1);                      \
00156     ++head->hth_n_entries;                                              \
00157     _HT_SET_HASH(elm, field, hashfn);                                   \
00158     p = &_HT_BUCKET(head, field, elm);                                  \
00159     elm->field.hte_next = *p;                                           \
00160     *p = elm;                                                           \
00161   }                                                                     \
00162   /* Insert the element 'elm' into the table 'head'. If there already   \
00163    * a matching element in the table, replace that element and return   \
00164    * it. */                                                             \
00165   static INLINE struct type *                                           \
00166   name##_HT_REPLACE(struct name *head, struct type *elm)                \
00167   {                                                                     \
00168     struct type **p, *r;                                                \
00169     if (!head->hth_table || head->hth_n_entries >= head->hth_load_limit) \
00170       name##_HT_GROW(head, head->hth_n_entries+1);                      \
00171     _HT_SET_HASH(elm, field, hashfn);                                   \
00172     p = _##name##_HT_FIND_P(head, elm);                                 \
00173     r = *p;                                                             \
00174     *p = elm;                                                           \
00175     if (r && (r!=elm)) {                                                \
00176       elm->field.hte_next = r->field.hte_next;                          \
00177       r->field.hte_next = NULL;                                         \
00178       return r;                                                         \
00179     } else {                                                            \
00180       ++head->hth_n_entries;                                            \
00181       return NULL;                                                      \
00182     }                                                                   \
00183   }                                                                     \
00184   /* Remove any element matching 'elm' from the table 'head'.  If such  \
00185    * an element is found, return it; otherwise return NULL. */          \
00186   static INLINE struct type *                                           \
00187   name##_HT_REMOVE(struct name *head, struct type *elm)                 \
00188   {                                                                     \
00189     struct type **p, *r;                                                \
00190     _HT_SET_HASH(elm, field, hashfn);                                   \
00191     p = _##name##_HT_FIND_P(head,elm);                                  \
00192     if (!p || !*p)                                                      \
00193       return NULL;                                                      \
00194     r = *p;                                                             \
00195     *p = r->field.hte_next;                                             \
00196     r->field.hte_next = NULL;                                           \
00197     --head->hth_n_entries;                                              \
00198     return r;                                                           \
00199   }                                                                     \
00200   /* Invoke the function 'fn' on every element of the table 'head',     \
00201    * using 'data' as its second argument.  If the function returns      \
00202    * nonzero, remove the most recently examined element before invoking \
00203    * the function again. */                                             \
00204   static INLINE void                                                    \
00205   name##_HT_FOREACH_FN(struct name *head,                               \
00206                        int (*fn)(struct type *, void *),                \
00207                        void *data)                                      \
00208   {                                                                     \
00209     unsigned idx;                                                       \
00210     int remove;                                                         \
00211     struct type **p, **nextp, *next;                                    \
00212     if (!head->hth_table)                                               \
00213       return;                                                           \
00214     for (idx=0; idx < head->hth_table_length; ++idx) {                  \
00215       p = &head->hth_table[idx];                                        \
00216       while (*p) {                                                      \
00217         nextp = &(*p)->field.hte_next;                                  \
00218         next = *nextp;                                                  \
00219         remove = fn(*p, data);                                          \
00220         if (remove) {                                                   \
00221           --head->hth_n_entries;                                        \
00222           *p = next;                                                    \
00223         } else {                                                        \
00224           p = nextp;                                                    \
00225         }                                                               \
00226       }                                                                 \
00227     }                                                                   \
00228   }                                                                     \
00229   /* Return a pointer to the first element in the table 'head', under   \
00230    * an arbitrary order.  This order is stable under remove operations, \
00231    * but not under others. If the table is empty, return NULL. */       \
00232   static INLINE struct type **                                          \
00233   name##_HT_START(struct name *head)                                    \
00234   {                                                                     \
00235     unsigned b = 0;                                                     \
00236     while (b < head->hth_table_length) {                                \
00237       if (head->hth_table[b])                                           \
00238         return &head->hth_table[b];                                     \
00239       ++b;                                                              \
00240     }                                                                   \
00241     return NULL;                                                        \
00242   }                                                                     \
00243   /* Return the next element in 'head' after 'elm', under the arbitrary \
00244    * order used by HT_START.  If there are no more elements, return     \
00245    * NULL.  If 'elm' is to be removed from the table, you must call     \
00246    * this function for the next value before you remove it.             \
00247    */                                                                   \
00248   static INLINE struct type **                                          \
00249   name##_HT_NEXT(struct name *head, struct type **elm)                  \
00250   {                                                                     \
00251     if ((*elm)->field.hte_next) {                                       \
00252       return &(*elm)->field.hte_next;                                   \
00253     } else {                                                            \
00254       unsigned b = ((*elm)->field.hte_hash % head->hth_table_length)+1; \
00255       while (b < head->hth_table_length) {                              \
00256         if (head->hth_table[b])                                         \
00257           return &head->hth_table[b];                                   \
00258         ++b;                                                            \
00259       }                                                                 \
00260       return NULL;                                                      \
00261     }                                                                   \
00262   }                                                                     \
00263   static INLINE struct type **                                          \
00264   name##_HT_NEXT_RMV(struct name *head, struct type **elm)              \
00265   {                                                                     \
00266     unsigned h = (*elm)->field.hte_hash;                                \
00267     *elm = (*elm)->field.hte_next;                                      \
00268     --head->hth_n_entries;                                              \
00269     if (*elm) {                                                         \
00270       return elm;                                                       \
00271     } else {                                                            \
00272       unsigned b = (h % head->hth_table_length)+1;                      \
00273       while (b < head->hth_table_length) {                              \
00274         if (head->hth_table[b])                                         \
00275           return &head->hth_table[b];                                   \
00276         ++b;                                                            \
00277       }                                                                 \
00278       return NULL;                                                      \
00279     }                                                                   \
00280   }
00281 
00282 #define HT_GENERATE(name, type, field, hashfn, eqfn, load, mallocfn,    \
00283                     reallocfn, freefn)                                  \
00284   static unsigned name##_PRIMES[] = {                                   \
00285     53, 97, 193, 389,                                                   \
00286     769, 1543, 3079, 6151,                                              \
00287     12289, 24593, 49157, 98317,                                         \
00288     196613, 393241, 786433, 1572869,                                    \
00289     3145739, 6291469, 12582917, 25165843,                               \
00290     50331653, 100663319, 201326611, 402653189,                          \
00291     805306457, 1610612741                                               \
00292   };                                                                    \
00293   static unsigned name##_N_PRIMES =                                     \
00294     (unsigned)(sizeof(name##_PRIMES)/sizeof(name##_PRIMES[0]));         \
00295   /* Expand the internal table of 'head' until it is large enough to    \
00296    * hold 'size' elements.  Return 0 on success, -1 on allocation       \
00297    * failure. */                                                        \
00298   int                                                                   \
00299   name##_HT_GROW(struct name *head, unsigned size)                      \
00300   {                                                                     \
00301     unsigned new_len, new_load_limit;                                   \
00302     int prime_idx;                                                      \
00303     struct type **new_table;                                            \
00304     if (head->hth_prime_idx == (int)name##_N_PRIMES - 1)                \
00305       return 0;                                                         \
00306     if (head->hth_load_limit > size)                                    \
00307       return 0;                                                         \
00308     prime_idx = head->hth_prime_idx;                                    \
00309     do {                                                                \
00310       new_len = name##_PRIMES[++prime_idx];                             \
00311       new_load_limit = (unsigned)(load*new_len);                        \
00312     } while (new_load_limit <= size &&                                  \
00313              prime_idx < (int)name##_N_PRIMES);                         \
00314     if ((new_table = mallocfn(new_len*sizeof(struct type*)))) {         \
00315       unsigned b;                                                       \
00316       memset(new_table, 0, new_len*sizeof(struct type*));               \
00317       for (b = 0; b < head->hth_table_length; ++b) {                    \
00318         struct type *elm, *next;                                        \
00319         unsigned b2;                                                    \
00320         elm = head->hth_table[b];                                       \
00321         while (elm) {                                                   \
00322           next = elm->field.hte_next;                                   \
00323           b2 = elm->field.hte_hash % new_len;                           \
00324           elm->field.hte_next = new_table[b2];                          \
00325           new_table[b2] = elm;                                          \
00326           elm = next;                                                   \
00327         }                                                               \
00328       }                                                                 \
00329       if (head->hth_table)                                              \
00330         freefn(head->hth_table);                                        \
00331       head->hth_table = new_table;                                      \
00332     } else {                                                            \
00333       unsigned b, b2;                                                   \
00334       new_table = reallocfn(head->hth_table, new_len*sizeof(struct type*)); \
00335       if (!new_table) return -1;                                        \
00336       memset(new_table + head->hth_table_length, 0,                     \
00337              (new_len - head->hth_table_length)*sizeof(struct type*));  \
00338       for (b=0; b < head->hth_table_length; ++b) {                      \
00339         struct type *e, **pE;                                           \
00340         for (pE = &new_table[b], e = *pE; e != NULL; e = *pE) {         \
00341           b2 = e->field.hte_hash % new_len;                             \
00342           if (b2 == b) {                                                \
00343             pE = &e->field.hte_next;                                    \
00344           } else {                                                      \
00345             *pE = e->field.hte_next;                                    \
00346             e->field.hte_next = new_table[b2];                          \
00347             new_table[b2] = e;                                          \
00348           }                                                             \
00349         }                                                               \
00350       }                                                                 \
00351       head->hth_table = new_table;                                      \
00352     }                                                                   \
00353     head->hth_table_length = new_len;                                   \
00354     head->hth_prime_idx = prime_idx;                                    \
00355     head->hth_load_limit = new_load_limit;                              \
00356     return 0;                                                           \
00357   }                                                                     \
00358   /* Free all storage held by 'head'.  Does not free 'head' itself, or  \
00359    * individual elements. */                                            \
00360   void                                                                  \
00361   name##_HT_CLEAR(struct name *head)                                    \
00362   {                                                                     \
00363     if (head->hth_table)                                                \
00364       freefn(head->hth_table);                                          \
00365     head->hth_table_length = 0;                                         \
00366     name##_HT_INIT(head);                                               \
00367   }                                                                     \
00368   /* Debugging helper: return false iff the representation of 'head' is \
00369    * internally consistent. */                                          \
00370   int                                                                   \
00371   _##name##_HT_REP_IS_BAD(const struct name *head)                      \
00372   {                                                                     \
00373     unsigned n, i;                                                      \
00374     struct type *elm;                                                   \
00375     if (!head->hth_table_length) {                                      \
00376       if (!head->hth_table && !head->hth_n_entries &&                   \
00377           !head->hth_load_limit && head->hth_prime_idx == -1)           \
00378         return 0;                                                       \
00379       else                                                              \
00380         return 1;                                                       \
00381     }                                                                   \
00382     if (!head->hth_table || head->hth_prime_idx < 0 ||                  \
00383         !head->hth_load_limit)                                          \
00384       return 2;                                                         \
00385     if (head->hth_n_entries > head->hth_load_limit)                     \
00386       return 3;                                                         \
00387     if (head->hth_table_length != name##_PRIMES[head->hth_prime_idx])   \
00388       return 4;                                                         \
00389     if (head->hth_load_limit != (unsigned)(load*head->hth_table_length)) \
00390       return 5;                                                         \
00391     for (n = i = 0; i < head->hth_table_length; ++i) {                  \
00392       for (elm = head->hth_table[i]; elm; elm = elm->field.hte_next) {  \
00393         if (elm->field.hte_hash != hashfn(elm))                         \
00394           return 1000 + i;                                              \
00395         if ((elm->field.hte_hash % head->hth_table_length) != i)        \
00396           return 10000 + i;                                             \
00397         ++n;                                                            \
00398       }                                                                 \
00399     }                                                                   \
00400     if (n != head->hth_n_entries)                                       \
00401       return 6;                                                         \
00402     return 0;                                                           \
00403   }
00404 
00408 #define _HT_FIND_OR_INSERT(name, field, hashfn, head, eltype, elm, var, y, n) \
00409   {                                                                     \
00410     struct name *_##var##_head = head;                                  \
00411     eltype **var;                                                       \
00412     if (!_##var##_head->hth_table ||                                    \
00413         _##var##_head->hth_n_entries >= _##var##_head->hth_load_limit)  \
00414       name##_HT_GROW(_##var##_head, _##var##_head->hth_n_entries+1);     \
00415     _HT_SET_HASH((elm), field, hashfn);                                \
00416     var = _##name##_HT_FIND_P(_##var##_head, (elm));                    \
00417     if (*var) {                                                         \
00418       y;                                                                \
00419     } else {                                                            \
00420       n;                                                                \
00421     }                                                                   \
00422   }
00423 #define _HT_FOI_INSERT(field, head, elm, newent, var)       \
00424   {                                                         \
00425     newent->field.hte_hash = (elm)->field.hte_hash;         \
00426     newent->field.hte_next = NULL;                          \
00427     *var = newent;                                          \
00428     ++((head)->hth_n_entries);                              \
00429   }
00430 
00431 /*
00432  * Copyright 2005, Nick Mathewson.  Implementation logic is adapted from code
00433  * by Christopher Clark, retrofit to allow drop-in memory management, and to
00434  * use the same interface as Niels Provos's HT_H.  I'm not sure whether this
00435  * is a derived work any more, but whether it is or not, the license below
00436  * applies.
00437  *
00438  * Copyright (c) 2002, Christopher Clark
00439  * All rights reserved.
00440  *
00441  * Redistribution and use in source and binary forms, with or without
00442  * modification, are permitted provided that the following conditions
00443  * are met:
00444  *
00445  * * Redistributions of source code must retain the above copyright
00446  * notice, this list of conditions and the following disclaimer.
00447  *
00448  * * Redistributions in binary form must reproduce the above copyright
00449  * notice, this list of conditions and the following disclaimer in the
00450  * documentation and/or other materials provided with the distribution.
00451  *
00452  * * Neither the name of the original author; nor the names of any contributors
00453  * may be used to endorse or promote products derived from this software
00454  * without specific prior written permission.
00455  *
00456  *
00457  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
00458  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
00459  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
00460  * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER
00461  * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
00462  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
00463  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
00464  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
00465  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
00466  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00467  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00468 */
00469 
00470 #endif
00471