lib/igt_map.c

   1 /*
   2  * Copyright © 2009, 2021 Intel Corporation
   3  * Copyright © 1988-2004 Keith Packard and Bart Massey.
   4  *
   5  * Permission is hereby granted, free of charge, to any person obtaining a
   6  * copy of this software and associated documentation files (the "Software"),
   7  * to deal in the Software without restriction, including without limitation
   8  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
   9  * and/or sell copies of the Software, and to permit persons to whom the
  10  * Software is furnished to do so, subject to the following conditions:
  11  *
  12  * The above copyright notice and this permission notice (including the next
  13  * paragraph) shall be included in all copies or substantial portions of the
  14  * Software.
  15  *
  16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  19  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  21  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
  22  * IN THE SOFTWARE.
  23  *
  24  * Except as contained in this notice, the names of the authors
  25  * or their institutions shall not be used in advertising or
  26  * otherwise to promote the sale, use or other dealings in this
  27  * Software without prior written authorization from the
  28  * authors.
  29  *
  30  * Authors:
  31  *    Eric Anholt <eric@anholt.net>
  32  *    Keith Packard <keithp@keithp.com>
  33  */
  34
  35 #include <assert.h>
  36 #include <stdlib.h>
  37
  38 #include "igt_map.h"
  39
  40 #define ARRAY_SIZE(array) (sizeof(array) / sizeof(array[0]))
  41
  42 /*
  43  * From Knuth -- a good choice for hash/rehash values is p, p-2 where
  44  * p and p-2 are both prime.  These tables are sized to have an extra 10%
  45  * free to avoid exponential performance degradation as the hash table fills
  46  */
  47
  48 static const uint32_t deleted_key_value;
  49 static const void *deleted_key = &deleted_key_value;
  50
  51 static const struct {
  52         uint32_t max_entries, size, rehash;
  53 } hash_sizes[] = {
  54         { 2,            5,              3         },
  55         { 4,            7,              5         },
  56         { 8,            13,             11        },
  57         { 16,           19,             17        },
  58         { 32,           43,             41        },
  59         { 64,           73,             71        },
  60         { 128,          151,            149       },
  61         { 256,          283,            281       },
  62         { 512,          571,            569       },
  63         { 1024,         1153,           1151      },
  64         { 2048,         2269,           2267      },
  65         { 4096,         4519,           4517      },
  66         { 8192,         9013,           9011      },
  67         { 16384,        18043,          18041     },
  68         { 32768,        36109,          36107     },
  69         { 65536,        72091,          72089     },
  70         { 131072,       144409,         144407    },
  71         { 262144,       288361,         288359    },
  72         { 524288,       576883,         576881    },
  73         { 1048576,      1153459,        1153457   },
  74         { 2097152,      2307163,        2307161   },
  75         { 4194304,      4613893,        4613891   },
  76         { 8388608,      9227641,        9227639   },
  77         { 16777216,     18455029,       18455027  },
  78         { 33554432,     36911011,       36911009  },
  79         { 67108864,     73819861,       73819859  },
  80         { 134217728,    147639589,      147639587 },
  81         { 268435456,    295279081,      295279079 },
  82         { 536870912,    590559793,      590559791 },
  83         { 1073741824,   1181116273,     1181116271},
  84         { 2147483648ul, 2362232233ul,   2362232231ul}
  85 };
  86
  87 static int
  88 entry_is_free(const struct igt_map_entry *entry)
  89 {
  90         return entry->key == NULL;
  91 }
  92
  93 static int
  94 entry_is_deleted(const struct igt_map_entry *entry)
  95 {
  96         return entry->key == deleted_key;
  97 }
  98
  99 static int
 100 entry_is_present(const struct igt_map_entry *entry)
 101 {
 102         return entry->key != NULL && entry->key != deleted_key;
 103 }
 104
 105 /**
 106  * igt_map_create:
 107  * @hash_function: function that maps key to 32b hash
 108  * @key_equals_function: function that compares given hashes
 109  *
 110  * Function creates a map and initializes it with given @hash_function and
 111  * @key_equals_function.
 112  *
 113  * Returns: pointer to just created map
 114  */
 115 struct igt_map *
 116 igt_map_create(uint32_t (*hash_function)(const void *key),
 117                int (*key_equals_function)(const void *a, const void *b))
 118 {
 119         struct igt_map *map;
 120
 121         map = malloc(sizeof(*map));
 122         if (map == NULL)
 123                 return NULL;
 124
 125         map->size_index = 0;
 126         map->size = hash_sizes[map->size_index].size;
 127         map->rehash = hash_sizes[map->size_index].rehash;
 128         map->max_entries = hash_sizes[map->size_index].max_entries;
 129         map->hash_function = hash_function;
 130         map->key_equals_function = key_equals_function;
 131         map->table = calloc(map->size, sizeof(*map->table));
 132         map->entries = 0;
 133         map->deleted_entries = 0;
 134
 135         if (map->table == NULL) {
 136                 free(map);
 137                 return NULL;
 138         }
 139
 140         return map;
 141 }
 142
 143 /**
 144  * igt_map_destroy:
 145  * @map: igt_map pointer
 146  * @delete_function: function that frees data in igt_map_entry
 147  *
 148  * Frees the given hash table. If @delete_function is passed, it gets called
 149  * on each entry present before freeing.
 150  */
 151 void
 152 igt_map_destroy(struct igt_map *map,
 153                 void (*delete_function)(struct igt_map_entry *entry))
 154 {
 155         if (!map)
 156                 return;
 157
 158         if (delete_function) {
 159                 struct igt_map_entry *entry;
 160
 161                 igt_map_foreach(map, entry) {
 162                         delete_function(entry);
 163                 }
 164         }
 165         free(map->table);
 166         free(map);
 167 }
 168
 169 /**
 170  * igt_map_search:
 171  * @map: igt_map pointer
 172  * @key: pointer to searched key
 173  *
 174  * Finds a map entry's data with the given @key.
 175  *
 176  * Returns: data pointer if the entry was found, %NULL otherwise.
 177  * Note that it may be modified by the user.
 178  */
 179 void *
 180 igt_map_search(struct igt_map *map, const void *key)
 181 {
 182         uint32_t hash = map->hash_function(key);
 183         struct igt_map_entry *entry;
 184
 185         entry = igt_map_search_pre_hashed(map, hash, key);
 186         return entry ? entry->data : NULL;
 187 }
 188
 189 /**
 190  * igt_map_search_entry:
 191  * @map: igt_map pointer
 192  * @key: pointer to searched key
 193  *
 194  * Finds a map entry with the given @key.
 195  *
 196  * Returns: map entry or %NULL if no entry is found.
 197  * Note that the data pointer may be modified by the user.
 198  */
 199
 200 struct igt_map_entry *
 201 igt_map_search_entry(struct igt_map *map, const void *key)
 202 {
 203         uint32_t hash = map->hash_function(key);
 204
 205         return igt_map_search_pre_hashed(map, hash, key);
 206 }
 207
 208 /**
 209  * igt_map_search_pre_hashed:
 210  * @map: igt_map pointer
 211  * @hash: hash of @key
 212  * @key: pointer to searched key
 213  *
 214  * Finds a map entry with the given @key and @hash of that key.
 215  *
 216  * Returns: map entry or %NULL if no entry is found.
 217  * Note that the data pointer may be modified by the user.
 218  */
 219 struct igt_map_entry *
 220 igt_map_search_pre_hashed(struct igt_map *map, uint32_t hash,
 221                           const void *key)
 222 {
 223         uint32_t start_hash_address = hash % map->size;
 224         uint32_t hash_address = start_hash_address;
 225
 226         do {
 227                 uint32_t double_hash;
 228
 229                 struct igt_map_entry *entry = map->table + hash_address;
 230
 231                 if (entry_is_free(entry)) {
 232                         return NULL;
 233                 } else if (entry_is_present(entry) && entry->hash == hash) {
 234                         if (map->key_equals_function(key, entry->key)) {
 235                                 return entry;
 236                         }
 237                 }
 238
 239                 double_hash = 1 + hash % map->rehash;
 240
 241                 hash_address = (hash_address + double_hash) % map->size;
 242         } while (hash_address != start_hash_address);
 243
 244         return NULL;
 245 }
 246
 247 static void
 248 igt_map_rehash(struct igt_map *map, int new_size_index)
 249 {
 250         struct igt_map old_map;
 251         struct igt_map_entry *table, *entry;
 252
 253         if (new_size_index >= ARRAY_SIZE(hash_sizes))
 254                 return;
 255
 256         table = calloc(hash_sizes[new_size_index].size, sizeof(*map->table));
 257         if (table == NULL)
 258                 return;
 259
 260         old_map = *map;
 261
 262         map->table = table;
 263         map->size_index = new_size_index;
 264         map->size = hash_sizes[map->size_index].size;
 265         map->rehash = hash_sizes[map->size_index].rehash;
 266         map->max_entries = hash_sizes[map->size_index].max_entries;
 267         map->entries = 0;
 268         map->deleted_entries = 0;
 269
 270         igt_map_foreach(&old_map, entry) {
 271                 igt_map_insert_pre_hashed(map, entry->hash,
 272                                              entry->key, entry->data);
 273         }
 274
 275         free(old_map.table);
 276 }
 277
 278 /**
 279  * igt_map_insert:
 280  * @map: igt_map pointer
 281  * @data: data to be store
 282  * @key: pointer to searched key
 283  *
 284  * Inserts the @data indexed by given @key into the map. If the @map already
 285  * contains an entry with the @key, it will be replaced. To avoid memory leaks,
 286  * perform a search before inserting.
 287  *
 288  * Note that insertion may rearrange the table on a resize or rehash,
 289  * so previously found hash entries are no longer valid after this function.
 290  *
 291  * Returns: pointer to just inserted entry
 292  */
 293 struct igt_map_entry *
 294 igt_map_insert(struct igt_map *map, const void *key, void *data)
 295 {
 296         uint32_t hash = map->hash_function(key);
 297
 298         /* Make sure nobody tries to add one of the magic values as a
 299          * key. If you need to do so, either do so in a wrapper, or
 300          * store keys with the magic values separately in the struct
 301          * igt_map.
 302          */
 303         assert(key != NULL);
 304
 305         return igt_map_insert_pre_hashed(map, hash, key, data);
 306 }
 307
 308 /**
 309  * igt_map_insert_pre_hashed:
 310  * @map: igt_map pointer
 311  * @hash: hash of @key
 312  * @data: data to be store
 313  * @key: pointer to searched key
 314  *
 315  * Inserts the @data indexed by given @key and @hash of that @key into the map.
 316  * If the @map already contains an entry with the @key, it will be replaced.
 317  * To avoid memory leaks, perform a search before inserting.
 318  *
 319  * Note that insertion may rearrange the table on a resize or rehash,
 320  * so previously found hash entries are no longer valid after this function.
 321  *
 322  * Returns: pointer to just inserted entry
 323  */
 324 struct igt_map_entry *
 325 igt_map_insert_pre_hashed(struct igt_map *map, uint32_t hash,
 326                           const void *key, void *data)
 327 {
 328         uint32_t start_hash_address, hash_address;
 329         struct igt_map_entry *available_entry = NULL;
 330
 331         if (map->entries >= map->max_entries) {
 332                 igt_map_rehash(map, map->size_index + 1);
 333         } else if (map->deleted_entries + map->entries >= map->max_entries) {
 334                 igt_map_rehash(map, map->size_index);
 335         }
 336
 337         start_hash_address = hash % map->size;
 338         hash_address = start_hash_address;
 339         do {
 340                 struct igt_map_entry *entry = map->table + hash_address;
 341                 uint32_t double_hash;
 342
 343                 if (!entry_is_present(entry)) {
 344                         /* Stash the first available entry we find */
 345                         if (available_entry == NULL)
 346                                 available_entry = entry;
 347                         if (entry_is_free(entry))
 348                                 break;
 349                 }
 350
 351                 /* Implement replacement when another insert happens
 352                  * with a matching key.  This is a relatively common
 353                  * feature of hash tables, with the alternative
 354                  * generally being "insert the new value as well, and
 355                  * return it first when the key is searched for".
 356                  *
 357                  * Note that the hash table doesn't have a delete
 358                  * callback.  If freeing of old data pointers is
 359                  * required to avoid memory leaks, perform a search
 360                  * before inserting.
 361                  */
 362                 if (!entry_is_deleted(entry) &&
 363                     entry->hash == hash &&
 364                     map->key_equals_function(key, entry->key)) {
 365                         entry->key = key;
 366                         entry->data = data;
 367                         return entry;
 368                 }
 369
 370
 371                 double_hash = 1 + hash % map->rehash;
 372
 373                 hash_address = (hash_address + double_hash) % map->size;
 374         } while (hash_address != start_hash_address);
 375
 376         if (available_entry) {
 377                 if (entry_is_deleted(available_entry))
 378                         map->deleted_entries--;
 379                 available_entry->hash = hash;
 380                 available_entry->key = key;
 381                 available_entry->data = data;
 382                 map->entries++;
 383                 return available_entry;
 384         }
 385
 386         /* We could hit here if a required resize failed. An unchecked-malloc
 387          * application could ignore this result.
 388          */
 389         return NULL;
 390 }
 391
 392 /**
 393  * igt_map_remove:
 394  * @map: igt_map pointer
 395  * @key: pointer to searched key
 396  * @delete_function: function that frees data in igt_map_entry
 397  *
 398  * Function searches for an entry with a given @key, and removes it from
 399  * the map. If @delete_function is passed, it will be called on removed entry.
 400  *
 401  * If the caller has previously found a struct igt_map_entry pointer,
 402  * (from calling igt_map_search() or remembering it from igt_map_insert()),
 403  * then igt_map_remove_entry() can be called instead to avoid an extra search.
 404  */
 405 void
 406 igt_map_remove(struct igt_map *map, const void *key,
 407                 void (*delete_function)(struct igt_map_entry *entry))
 408 {
 409         struct igt_map_entry *entry;
 410
 411         entry = igt_map_search_entry(map, key);
 412         if (delete_function)
 413                 delete_function(entry);
 414
 415         igt_map_remove_entry(map, entry);
 416 }
 417
 418 /**
 419  * igt_map_remove_entry:
 420  * @map: igt_map pointer
 421  * @entry: pointer to map entry
 422  *
 423  * Function deletes the given hash entry.
 424  *
 425  * Note that deletion doesn't otherwise modify the table, so an iteration over
 426  * the map deleting entries is safe.
 427  */
 428 void
 429 igt_map_remove_entry(struct igt_map *map, struct igt_map_entry *entry)
 430 {
 431         if (!entry)
 432                 return;
 433
 434         entry->key = deleted_key;
 435         map->entries--;
 436         map->deleted_entries++;
 437 }
 438
 439 /**
 440  * igt_map_next_entry:
 441  * @map: igt_map pointer
 442  * @entry: pointer to map entry, %NULL for the first map entry
 443  *
 444  * This function is an iterator over the hash table.
 445  * Note that an iteration over the table is O(table_size) not O(entries).
 446  *
 447  * Returns: pointer to the next entry
 448  */
 449 struct igt_map_entry *
 450 igt_map_next_entry(struct igt_map *map, struct igt_map_entry *entry)
 451 {
 452         if (entry == NULL)
 453                 entry = map->table;
 454         else
 455                 entry = entry + 1;
 456
 457         for (; entry != map->table + map->size; entry++) {
 458                 if (entry_is_present(entry)) {
 459                         return entry;
 460                 }
 461         }
 462
 463         return NULL;
 464 }
 465
 466 /**
 467  * igt_map_random_entry:
 468  * @map: igt_map pointer
 469  * @predicate: filtering entries function
 470  *
 471  * Functions returns random entry from the map. This may be useful in
 472  * implementing random replacement (as opposed to just removing everything)
 473  * in caches based on this hash table implementation. @predicate may be used to
 474  * filter entries, or may be set to %NULL for no filtering.
 475  *
 476  * Returns: pointer to the randomly chosen map entry
 477  */
 478 struct igt_map_entry *
 479 igt_map_random_entry(struct igt_map *map,
 480                      int (*predicate)(struct igt_map_entry *entry))
 481 {
 482         struct igt_map_entry *entry;
 483         uint32_t i = random() % map->size;
 484
 485         if (map->entries == 0)
 486                 return NULL;
 487
 488         for (entry = map->table + i; entry != map->table + map->size; entry++) {
 489                 if (entry_is_present(entry) &&
 490                     (!predicate || predicate(entry))) {
 491                         return entry;
 492                 }
 493         }
 494
 495         for (entry = map->table; entry != map->table + i; entry++) {
 496                 if (entry_is_present(entry) &&
 497                     (!predicate || predicate(entry))) {
 498                         return entry;
 499                 }
 500         }
 501
 502         return NULL;
 503 }
 504
 505 #define GOLDEN_RATIO_PRIME_32 0x9e370001UL
 506 /**
 507  * igt_map_hash_32:
 508  * @key: pointer to 32-bit key
 509  *
 510  * Function is hashing function for 32-bit keys. Key is pointer to 32-bit
 511  * value so it must be dereferenced.
 512  */
 513 uint32_t igt_map_hash_32(const void *key)
 514 {
 515         uint32_t hash = *(uint32_t *)key;
 516
 517         hash = hash * GOLDEN_RATIO_PRIME_32;
 518         return hash;
 519 }
 520
 521 /**
 522  * igt_map_equal_32:
 523  * @key1: pointer to first 32-bit key
 524  * @key2: pointer to second 32-bit key
 525  *
 526  * Function compares 32-bit keys.
 527  */
 528 int igt_map_equal_32(const void *key1, const void *key2)
 529 {
 530         return *(uint32_t *)key1 == *(uint32_t *)key2;
 531 }
 532
 533 /*  2^63 + 2^61 - 2^57 + 2^54 - 2^51 - 2^18 + 1 */
 534 #define GOLDEN_RATIO_PRIME_64 0x9e37fffffffc0001ULL
 535 /**
 536  * igt_map_hash_64:
 537  * @key: pointer to 64-bit key
 538  *
 539  * Function is hashing function for 64-bit keys. Key is pointer to 64-bit
 540  * value so it must be dereferenced.
 541  */
 542 uint32_t igt_map_hash_64(const void *key)
 543 {
 544         uint64_t hash = *(uint64_t *)key;
 545
 546         hash = hash * GOLDEN_RATIO_PRIME_64;
 547         /* High bits are more random, so use them. */
 548         return hash >> 32;
 549 }
 550
 551 /**
 552  * igt_map_equal_64:
 553  * @key1: pointer to first 64-bit key
 554  * @key2: pointer to second 64-bit key
 555  *
 556  * Function compares 64-bit keys.
 557  */
 558 int igt_map_equal_64(const void *key1, const void *key2)
 559 {
 560         return *(uint64_t *)key1 == *(uint64_t *)key2;
 561 }