src/common/container.h

   1 /* Copyright (c) 2003-2004, Roger Dingledine
   2  * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
   3  * Copyright (c) 2007-2008, The Tor Project, Inc. */
   4 /* See LICENSE for licensing information */
   5 /* $Id$ */
   6
   7 #ifndef __CONTAINER_H
   8 #define __CONTAINER_H
   9 #define CONTAINER_H_ID \
  10   "$Id$"
  11
  12 #include "util.h"
  13
  14 /** A resizeable list of pointers, with associated helpful functionality.
  15  *
  16  * The members of this struct are exposed only so that macros and inlines can
  17  * use them; all access to smartlist internals should go throuch the functions
  18  * and macros defined here.
  19  **/
  20 typedef struct smartlist_t {
  21   /** <b>list</b> has enough capacity to store exactly <b>capacity</b> elements
  22    * before it needs to be resized.  Only the first <b>num_used</b> (\<=
  23    * capacity) elements point to valid data.
  24    */
  25   void **list;
  26   int num_used;
  27   int capacity;
  28 } smartlist_t;
  29
  30 smartlist_t *smartlist_create(void);
  31 void smartlist_free(smartlist_t *sl);
  32 void smartlist_clear(smartlist_t *sl);
  33 void smartlist_add(smartlist_t *sl, void *element);
  34 void smartlist_add_all(smartlist_t *sl, const smartlist_t *s2);
  35 void smartlist_remove(smartlist_t *sl, const void *element);
  36 void *smartlist_pop_last(smartlist_t *sl);
  37 void smartlist_reverse(smartlist_t *sl);
  38 void smartlist_string_remove(smartlist_t *sl, const char *element);
  39 int smartlist_isin(const smartlist_t *sl, const void *element) ATTR_PURE;
  40 int smartlist_string_isin(const smartlist_t *sl, const char *element)
  41   ATTR_PURE;
  42 int smartlist_string_pos(const smartlist_t *, const char *elt) ATTR_PURE;
  43 int smartlist_string_isin_case(const smartlist_t *sl, const char *element)
  44   ATTR_PURE;
  45 int smartlist_string_num_isin(const smartlist_t *sl, int num) ATTR_PURE;
  46 int smartlist_digest_isin(const smartlist_t *sl, const char *element)
  47   ATTR_PURE;
  48 int smartlist_overlap(const smartlist_t *sl1, const smartlist_t *sl2)
  49   ATTR_PURE;
  50 void smartlist_intersect(smartlist_t *sl1, const smartlist_t *sl2);
  51 void smartlist_subtract(smartlist_t *sl1, const smartlist_t *sl2);
  52
  53 /* smartlist_choose() is defined in crypto.[ch] */
  54 #ifdef DEBUG_SMARTLIST
  55 /** Return the number of items in sl.
  56  */
  57 static INLINE int smartlist_len(const smartlist_t *sl) ATTR_PURE;
  58 static INLINE int smartlist_len(const smartlist_t *sl) {
  59   tor_assert(sl);
  60   return (sl)->num_used;
  61 }
  62 /** Return the <b>idx</b>th element of sl.
  63  */
  64 static INLINE void *smartlist_get(const smartlist_t *sl, int idx) ATTR_PURE;
  65 static INLINE void *smartlist_get(const smartlist_t *sl, int idx) {
  66   tor_assert(sl);
  67   tor_assert(idx>=0);
  68   tor_assert(sl->num_used > idx);
  69   return sl->list[idx];
  70 }
  71 static INLINE void smartlist_set(smartlist_t *sl, int idx, void *val) {
  72   tor_assert(sl);
  73   tor_assert(idx>=0);
  74   tor_assert(sl->num_used > idx);
  75   sl->list[idx] = val;
  76 }
  77 #else
  78 #define smartlist_len(sl) ((sl)->num_used)
  79 #define smartlist_get(sl, idx) ((sl)->list[idx])
  80 #define smartlist_set(sl, idx, val) ((sl)->list[idx] = (val))
  81 #endif
  82
  83 /** Exchange the elements at indices <b>idx1</b> and <b>idx2</b> of the
  84  * smartlist <b>sl</b>. */
  85 static INLINE void smartlist_swap(smartlist_t *sl, int idx1, int idx2)
  86 {
  87   if (idx1 != idx2) {
  88     void *elt = smartlist_get(sl, idx1);
  89     smartlist_set(sl, idx1, smartlist_get(sl, idx2));
  90     smartlist_set(sl, idx2, elt);
  91   }
  92 }
  93
  94 void smartlist_del(smartlist_t *sl, int idx);
  95 void smartlist_del_keeporder(smartlist_t *sl, int idx);
  96 void smartlist_insert(smartlist_t *sl, int idx, void *val);
  97 void smartlist_sort(smartlist_t *sl,
  98                     int (*compare)(const void **a, const void **b));
  99 void smartlist_uniq(smartlist_t *sl,
 100                     int (*compare)(const void **a, const void **b),
 101                     void (*free_fn)(void *elt));
 102 void smartlist_sort_strings(smartlist_t *sl);
 103 void smartlist_sort_digests(smartlist_t *sl);
 104 void smartlist_uniq_strings(smartlist_t *sl);
 105 void smartlist_uniq_digests(smartlist_t *sl);
 106 void *smartlist_bsearch(smartlist_t *sl, const void *key,
 107                         int (*compare)(const void *key, const void **member))
 108  ATTR_PURE;
 109 int smartlist_bsearch_idx(const smartlist_t *sl, const void *key,
 110                           int (*compare)(const void *key, const void **member),
 111                           int *found_out)
 112  ATTR_PURE;
 113
 114 void smartlist_pqueue_add(smartlist_t *sl,
 115                           int (*compare)(const void *a, const void *b),
 116                           void *item);
 117 void *smartlist_pqueue_pop(smartlist_t *sl,
 118                            int (*compare)(const void *a, const void *b));
 119 void smartlist_pqueue_assert_ok(smartlist_t *sl,
 120                                 int (*compare)(const void *a, const void *b));
 121
 122 #define SPLIT_SKIP_SPACE   0x01
 123 #define SPLIT_IGNORE_BLANK 0x02
 124 int smartlist_split_string(smartlist_t *sl, const char *str, const char *sep,
 125                            int flags, int max);
 126 char *smartlist_join_strings(smartlist_t *sl, const char *join, int terminate,
 127                              size_t *len_out) ATTR_MALLOC;
 128 char *smartlist_join_strings2(smartlist_t *sl, const char *join,
 129                               size_t join_len, int terminate, size_t *len_out)
 130   ATTR_MALLOC;
 131
 132 /** Iterate over the items in a smartlist <b>sl</b>, in order.  For each item,
 133  * assign it to a new local variable of type <b>type</b> named <b>var</b>, and
 134  * execute the statement <b>cmd</b>.  Inside the loop, the loop index can
 135  * be accessed as <b>var</b>_sl_idx and the length of the list can be accessed
 136  * as <b>var</b>_sl_len.
 137  *
 138  * NOTE: Do not change the length of the list while the loop is in progress,
 139  * unless you adjust the _sl_len variable correspondingly.  See second example
 140  * below.
 141  *
 142  * Example use:
 143  * <pre>
 144  *   smartlist_t *list = smartlist_split("A:B:C", ":", 0, 0);
 145  *   SMARTLIST_FOREACH(list, char *, cp,
 146  *   {
 147  *     printf("%d: %s\n", cp_sl_idx, cp);
 148  *     tor_free(cp);
 149  *   });
 150  *   smartlist_free(list);
 151  * </pre>
 152  *
 153  * Example use (advanced):
 154  * <pre>
 155  *   SMARTLIST_FOREACH(list, char *, cp,
 156  *   {
 157  *     if (!strcmp(cp, "junk")) {
 158  *       smartlist_del(list, cp_sl_idx);
 159  *       tor_free(cp);
 160  *       --cp_sl_len; // decrement length of list so we don't run off the end
 161  *       --cp_sl_idx; // decrement idx so we consider the item that moved here
 162  *     }
 163  *   });
 164  * </pre>
 165  */
 166 #define SMARTLIST_FOREACH(sl, type, var, cmd)                   \
 167   STMT_BEGIN                                                    \
 168     int var ## _sl_idx, var ## _sl_len=(sl)->num_used;          \
 169     type var;                                                   \
 170     for (var ## _sl_idx = 0; var ## _sl_idx < var ## _sl_len;   \
 171          ++var ## _sl_idx) {                                    \
 172       var = (sl)->list[var ## _sl_idx];                         \
 173       cmd;                                                      \
 174     } STMT_END
 175
 176 /** Helper: While in a SMARTLIST_FOREACH loop over the list <b>sl</b> indexed
 177  * with the variable <b>var</b>, remove the current element in a way that
 178  * won't confuse the loop. */
 179 #define SMARTLIST_DEL_CURRENT(sl, var)          \
 180   STMT_BEGIN                                    \
 181     smartlist_del(sl, var ## _sl_idx);          \
 182     --var ## _sl_idx;                           \
 183     --var ## _sl_len;                           \
 184   STMT_END
 185
 186 #define DECLARE_MAP_FNS(maptype, keytype, prefix)                       \
 187   typedef struct maptype maptype;                                       \
 188   typedef struct prefix##entry_t *prefix##iter_t;                       \
 189   maptype* prefix##new(void);                                           \
 190   void* prefix##set(maptype *map, keytype key, void *val);              \
 191   void* prefix##get(const maptype *map, keytype key);                   \
 192   void* prefix##remove(maptype *map, keytype key);                      \
 193   void prefix##free(maptype *map, void (*free_val)(void*));             \
 194   int prefix##isempty(const maptype *map);                              \
 195   int prefix##size(const maptype *map);                                 \
 196   prefix##iter_t *prefix##iter_init(maptype *map);                      \
 197   prefix##iter_t *prefix##iter_next(maptype *map, prefix##iter_t *iter); \
 198   prefix##iter_t *prefix##iter_next_rmv(maptype *map, prefix##iter_t *iter); \
 199   void prefix##iter_get(prefix##iter_t *iter, keytype *keyp, void **valp); \
 200   int prefix##iter_done(prefix##iter_t *iter);                          \
 201   void prefix##assert_ok(const maptype *map)
 202
 203 /* Map from const char * to void *. Implemented with a hash table. */
 204 DECLARE_MAP_FNS(strmap_t, const char *, strmap_);
 205 /* Map from const char[DIGEST_LEN] to void *. Implemented with a hash table. */
 206 DECLARE_MAP_FNS(digestmap_t, const char *, digestmap_);
 207
 208 #undef DECLARE_MAP_FNS
 209
 210 /** Iterates over the key-value pairs in a map <b>map</b> in order.
 211  * <b>prefix</b> is as for DECLARE_MAP_FNS (i.e., strmap_ or digestmap_).
 212  * The map's keys and values are of type keytype and valtype respectively;
 213  * each iteration assigns them to keyvar and valvar.
 214  *
 215  * Example use:
 216  *   MAP_FOREACH(digestmap_, m, const char *, k, routerinfo_t *, r) {
 217  *     // use k and r
 218  *   } MAP_FOREACH_END.
 219  */
 220 #define MAP_FOREACH(prefix, map, keytype, keyvar, valtype, valvar)      \
 221   STMT_BEGIN                                                            \
 222     prefix##iter_t *keyvar##_iter;                                      \
 223     for (keyvar##_iter = prefix##iter_init(map);                        \
 224          !prefix##iter_done(keyvar##_iter);                             \
 225          keyvar##_iter = prefix##iter_next(map, keyvar##_iter)) {       \
 226       keytype keyvar;                                                   \
 227       void *valvar##_voidp;                                             \
 228       valtype valvar;                                                   \
 229       prefix##iter_get(keyvar##_iter, &keyvar, &valvar##_voidp);        \
 230       valvar = valvar##_voidp;
 231
 232 /** As MAP_FOREACH, except allows members to be removed from the map
 233  * during the iteration via MAP_DEL_CURRENT.  Example use:
 234  *
 235  * Example use:
 236  *   MAP_FOREACH(digestmap_, m, const char *, k, routerinfo_t *, r) {
 237  *      if (is_very_old(r))
 238  *       MAP_DEL_CURRENT(k);
 239  *   } MAP_FOREACH_END.
 240  **/
 241 #define MAP_FOREACH_MODIFY(prefix, map, keytype, keyvar, valtype, valvar) \
 242   STMT_BEGIN                                                            \
 243     prefix##iter_t *keyvar##_iter;                                      \
 244     int keyvar##_del=0;                                                 \
 245     for (keyvar##_iter = prefix##iter_init(map);                        \
 246          !prefix##iter_done(keyvar##_iter);                             \
 247          keyvar##_iter = keyvar##_del ?                                 \
 248            prefix##iter_next_rmv(map, keyvar##_iter) :                  \
 249            prefix##iter_next(map, keyvar##_iter)) {                     \
 250       keytype keyvar;                                                   \
 251       void *valvar##_voidp;                                             \
 252       valtype valvar;                                                   \
 253       keyvar##_del=0;                                                   \
 254       prefix##iter_get(keyvar##_iter, &keyvar, &valvar##_voidp);        \
 255       valvar = valvar##_voidp;
 256
 257 /** Used with MAP_FOREACH_MODIFY to remove the currently-iterated-upon
 258  * member of the map.  */
 259 #define MAP_DEL_CURRENT(keyvar)                   \
 260   STMT_BEGIN                                      \
 261     keyvar##_del = 1;                             \
 262   STMT_END
 263
 264 /** Used to end a MAP_FOREACH() block. */
 265 #define MAP_FOREACH_END } STMT_END ;
 266
 267 /** As MAP_FOREACH, but does not require declaration of prefix or keytype.
 268  * Example use:
 269  *   DIGESTMAP_FOREACH(m, k, routerinfo_t *, r) {
 270  *     // use k and r
 271  *   } DIGESTMAP_FOREACH_END.
 272  */
 273 #define DIGESTMAP_FOREACH(map, keyvar, valtype, valvar)                 \
 274   MAP_FOREACH(digestmap_, map, const char *, keyvar, valtype, valvar)
 275
 276 /** As MAP_FOREACH_MODIFY, but does not require declaration of prefix or
 277  * keytype.
 278  * Example use:
 279  *   DIGESTMAP_FOREACH_MODIFY(m, k, routerinfo_t *, r) {
 280  *      if (is_very_old(r))
 281  *       MAP_DEL_CURRENT(k);
 282  *   } DIGESTMAP_FOREACH_END.
 283  */
 284 #define DIGESTMAP_FOREACH_MODIFY(map, keyvar, valtype, valvar)          \
 285   MAP_FOREACH_MODIFY(digestmap_, map, const char *, keyvar, valtype, valvar)
 286 /** Used to end a DIGESTMAP_FOREACH() block. */
 287 #define DIGESTMAP_FOREACH_END MAP_FOREACH_END
 288
 289 #define STRMAP_FOREACH(map, keyvar, valtype, valvar)                 \
 290   MAP_FOREACH(strmap_, map, const char *, keyvar, valtype, valvar)
 291 #define STRMAP_FOREACH_MODIFY(map, keyvar, valtype, valvar)          \
 292   MAP_FOREACH_MODIFY(strmap_, map, const char *, keyvar, valtype, valvar)
 293 #define STRMAP_FOREACH_END MAP_FOREACH_END
 294
 295 void* strmap_set_lc(strmap_t *map, const char *key, void *val);
 296 void* strmap_get_lc(const strmap_t *map, const char *key);
 297 void* strmap_remove_lc(strmap_t *map, const char *key);
 298
 299 #define DECLARE_TYPED_DIGESTMAP_FNS(prefix, maptype, valtype)           \
 300   typedef struct maptype maptype;                                       \
 301   typedef struct prefix##iter_t prefix##iter_t;                         \
 302   static INLINE maptype* prefix##new(void)                              \
 303   {                                                                     \
 304     return (maptype*)digestmap_new();                                   \
 305   }                                                                     \
 306   static INLINE digestmap_t* prefix##to_digestmap(maptype *map)         \
 307   {                                                                     \
 308     return (digestmap_t*)map;                                           \
 309   }                                                                     \
 310   static INLINE valtype* prefix##get(maptype *map, const char *key)     \
 311   {                                                                     \
 312     return (valtype*)digestmap_get((digestmap_t*)map, key);             \
 313   }                                                                     \
 314   static INLINE valtype* prefix##set(maptype *map, const char *key,     \
 315                                      valtype *val)                      \
 316   {                                                                     \
 317     return (valtype*)digestmap_set((digestmap_t*)map, key, val);        \
 318   }                                                                     \
 319   static INLINE valtype* prefix##remove(maptype *map, const char *key)  \
 320   {                                                                     \
 321     return (valtype*)digestmap_remove((digestmap_t*)map, key);          \
 322   }                                                                     \
 323   static INLINE void prefix##free(maptype *map, void (*free_val)(void*)) \
 324   {                                                                     \
 325     digestmap_free((digestmap_t*)map, free_val);                        \
 326   }                                                                     \
 327   static INLINE int prefix##isempty(maptype *map)                       \
 328   {                                                                     \
 329     return digestmap_isempty((digestmap_t*)map);                        \
 330   }                                                                     \
 331   static INLINE int prefix##size(maptype *map)                          \
 332   {                                                                     \
 333     return digestmap_size((digestmap_t*)map);                           \
 334   }                                                                     \
 335   static INLINE prefix##iter_t *prefix##iter_init(maptype *map)         \
 336   {                                                                     \
 337     return (prefix##iter_t*) digestmap_iter_init((digestmap_t*)map);    \
 338   }                                                                     \
 339   static INLINE prefix##iter_t *prefix##iter_next(maptype *map,         \
 340                                                   prefix##iter_t *iter) \
 341   {                                                                     \
 342     return (prefix##iter_t*) digestmap_iter_next(                       \
 343                        (digestmap_t*)map, (digestmap_iter_t*)iter);     \
 344   }                                                                     \
 345   static INLINE prefix##iter_t *prefix##iter_next_rmv(maptype *map,     \
 346                                                   prefix##iter_t *iter) \
 347   {                                                                     \
 348     return (prefix##iter_t*) digestmap_iter_next_rmv(                   \
 349                        (digestmap_t*)map, (digestmap_iter_t*)iter);     \
 350   }                                                                     \
 351   static INLINE void prefix##iter_get(prefix##iter_t *iter,             \
 352                                       const char **keyp,                \
 353                                       valtype **valp)                   \
 354   {                                                                     \
 355     void *v;                                                            \
 356     digestmap_iter_get((digestmap_iter_t*) iter, keyp, &v);             \
 357     *valp = v;                                                          \
 358   }                                                                     \
 359   static INLINE int prefix##iter_done(prefix##iter_t *iter)             \
 360   {                                                                     \
 361     return digestmap_iter_done((digestmap_iter_t*)iter);                \
 362   }
 363
 364 #if SIZEOF_INT == 4
 365 #define BITARRAY_SHIFT 5
 366 #elif SIZEOF_INT == 8
 367 #define BITARRAY_SHIFT 6
 368 #else
 369 #error "int is neither 4 nor 8 bytes. I can't deal with that."
 370 #endif
 371 #define BITARRAY_MASK ((1u<<BITARRAY_SHIFT)-1)
 372
 373 /** A random-access array of one-bit-wide elements. */
 374 typedef unsigned int bitarray_t;
 375 /** Create a new bit array that can hold <b>n_bits</b> bits. */
 376 static INLINE bitarray_t *
 377 bitarray_init_zero(unsigned int n_bits)
 378 {
 379   /* round up to the next int. */
 380   size_t sz = (n_bits+BITARRAY_MASK) >> BITARRAY_SHIFT;
 381   return tor_malloc_zero(sz*sizeof(unsigned int));
 382 }
 383 /** Expand <b>ba</b> from holding <b>n_bits_old</b> to <b>n_bits_new</b>,
 384  * clearing all new bits.  Returns a possibly changed pointer to the
 385  * bitarray. */
 386 static INLINE bitarray_t *
 387 bitarray_expand(bitarray_t *ba,
 388                 unsigned int n_bits_old, unsigned int n_bits_new)
 389 {
 390   size_t sz_old = (n_bits_old+BITARRAY_MASK) >> BITARRAY_SHIFT;
 391   size_t sz_new = (n_bits_new+BITARRAY_MASK) >> BITARRAY_SHIFT;
 392   char *ptr;
 393   if (sz_new <= sz_old)
 394     return ba;
 395   ptr = tor_realloc(ba, sz_new*sizeof(unsigned int));
 396   /* This memset does nothing to the older excess bytes.  But they were
 397    * already set to 0 by bitarry_init_zero. */
 398   memset(ptr+sz_old*sizeof(unsigned int), 0,
 399          (sz_new-sz_old)*sizeof(unsigned int));
 400   return (bitarray_t*) ptr;
 401 }
 402 /** Free the bit array <b>ba</b>. */
 403 static INLINE void
 404 bitarray_free(bitarray_t *ba)
 405 {
 406   tor_free(ba);
 407 }
 408 /** Set the <b>bit</b>th bit in <b>b</b> to 1. */
 409 static INLINE void
 410 bitarray_set(bitarray_t *b, int bit)
 411 {
 412   b[bit >> BITARRAY_SHIFT] |= (1u << (bit & BITARRAY_MASK));
 413 }
 414 /** Set the <b>bit</b>th bit in <b>b</b> to 0. */
 415 static INLINE void
 416 bitarray_clear(bitarray_t *b, int bit)
 417 {
 418   b[bit >> BITARRAY_SHIFT] &= ~ (1u << (bit & BITARRAY_MASK));
 419 }
 420 /** Return true iff <b>bit</b>th bit in <b>b</b> is nonzero.  NOTE: does
 421  * not necessarily return 1 on true. */
 422 static INLINE unsigned int
 423 bitarray_is_set(bitarray_t *b, int bit)
 424 {
 425   return b[bit >> BITARRAY_SHIFT] & (1u << (bit & BITARRAY_MASK));
 426 }
 427
 428 /* These functions, given an <b>array</b> of <b>n_elements</b>, return the
 429  * <b>nth</b> lowest element. <b>nth</b>=0 gives the lowest element;
 430  * <b>n_elements</b>-1 gives the highest; and (<b>n_elements</b>-1) / 2 gives
 431  * the median.  As a side effect, the elements of <b>array</b> are sorted. */
 432 int find_nth_int(int *array, int n_elements, int nth);
 433 time_t find_nth_time(time_t *array, int n_elements, int nth);
 434 double find_nth_double(double *array, int n_elements, int nth);
 435 uint32_t find_nth_uint32(uint32_t *array, int n_elements, int nth);
 436 long find_nth_long(long *array, int n_elements, int nth);
 437 static INLINE int
 438 median_int(int *array, int n_elements)
 439 {
 440   return find_nth_int(array, n_elements, (n_elements-1)/2);
 441 }
 442 static INLINE time_t
 443 median_time(time_t *array, int n_elements)
 444 {
 445   return find_nth_time(array, n_elements, (n_elements-1)/2);
 446 }
 447 static INLINE double
 448 median_double(double *array, int n_elements)
 449 {
 450   return find_nth_double(array, n_elements, (n_elements-1)/2);
 451 }
 452 static INLINE uint32_t
 453 median_uint32(uint32_t *array, int n_elements)
 454 {
 455   return find_nth_uint32(array, n_elements, (n_elements-1)/2);
 456 }
 457 static INLINE long
 458 median_long(long *array, int n_elements)
 459 {
 460   return find_nth_long(array, n_elements, (n_elements-1)/2);
 461 }
 462
 463 #endif
 464