lib/hash/rte_hash.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2010-2015 Intel Corporation
   3  */
   4
   5 #ifndef _RTE_HASH_H_
   6 #define _RTE_HASH_H_
   7
   8 /**
   9  * @file
  10  *
  11  * RTE Hash Table
  12  */
  13
  14 #include <stdint.h>
  15 #include <stddef.h>
  16
  17 #include <rte_compat.h>
  18 #include <rte_rcu_qsbr.h>
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif
  23
  24 /** Maximum size of hash table that can be created. */
  25 #define RTE_HASH_ENTRIES_MAX                    (1 << 30)
  26
  27 /** Maximum number of characters in hash name.*/
  28 #define RTE_HASH_NAMESIZE                       32
  29
  30 /** Maximum number of keys that can be searched for using rte_hash_lookup_bulk. */
  31 #define RTE_HASH_LOOKUP_BULK_MAX                64
  32 #define RTE_HASH_LOOKUP_MULTI_MAX               RTE_HASH_LOOKUP_BULK_MAX
  33
  34 /** Enable Hardware transactional memory support. */
  35 #define RTE_HASH_EXTRA_FLAGS_TRANS_MEM_SUPPORT  0x01
  36
  37 /** Default behavior of insertion, single writer/multi writer */
  38 #define RTE_HASH_EXTRA_FLAGS_MULTI_WRITER_ADD 0x02
  39
  40 /** Flag to support reader writer concurrency */
  41 #define RTE_HASH_EXTRA_FLAGS_RW_CONCURRENCY 0x04
  42
  43 /** Flag to indicate the extendable bucket table feature should be used */
  44 #define RTE_HASH_EXTRA_FLAGS_EXT_TABLE 0x08
  45
  46 /** Flag to disable freeing of key index on hash delete.
  47  * Refer to rte_hash_del_xxx APIs for more details.
  48  * This is enabled by default when RTE_HASH_EXTRA_FLAGS_RW_CONCURRENCY_LF
  49  * is enabled. However, if internal RCU is enabled, freeing of internal
  50  * memory/index is done on delete
  51  */
  52 #define RTE_HASH_EXTRA_FLAGS_NO_FREE_ON_DEL 0x10
  53
  54 /** Flag to support lock free reader writer concurrency. Both single writer
  55  * and multi writer use cases are supported.
  56  */
  57 #define RTE_HASH_EXTRA_FLAGS_RW_CONCURRENCY_LF 0x20
  58
  59 /**
  60  * The type of hash value of a key.
  61  * It should be a value of at least 32bit with fully random pattern.
  62  */
  63 typedef uint32_t hash_sig_t;
  64
  65 /** Type of function that can be used for calculating the hash value. */
  66 typedef uint32_t (*rte_hash_function)(const void *key, uint32_t key_len,
  67                                       uint32_t init_val);
  68
  69 /** Type of function used to compare the hash key. */
  70 typedef int (*rte_hash_cmp_eq_t)(const void *key1, const void *key2, size_t key_len);
  71
  72 /**
  73  * Type of function used to free data stored in the key.
  74  * Required when using internal RCU to allow application to free key-data once
  75  * the key is returned to the ring of free key-slots.
  76  */
  77 typedef void (*rte_hash_free_key_data)(void *p, void *key_data);
  78
  79 /**
  80  * Parameters used when creating the hash table.
  81  */
  82 struct rte_hash_parameters {
  83         const char *name;               /**< Name of the hash. */
  84         uint32_t entries;               /**< Total hash table entries. */
  85         uint32_t reserved;              /**< Unused field. Should be set to 0 */
  86         uint32_t key_len;               /**< Length of hash key. */
  87         rte_hash_function hash_func;    /**< Primary Hash function used to calculate hash. */
  88         uint32_t hash_func_init_val;    /**< Init value used by hash_func. */
  89         int socket_id;                  /**< NUMA Socket ID for memory. */
  90         uint8_t extra_flag;             /**< Indicate if additional parameters are present. */
  91 };
  92
  93 /** RCU reclamation modes */
  94 enum rte_hash_qsbr_mode {
  95         /** Create defer queue for reclaim. */
  96         RTE_HASH_QSBR_MODE_DQ = 0,
  97         /** Use blocking mode reclaim. No defer queue created. */
  98         RTE_HASH_QSBR_MODE_SYNC
  99 };
 100
 101 /** HASH RCU QSBR configuration structure. */
 102 struct rte_hash_rcu_config {
 103         struct rte_rcu_qsbr *v;         /**< RCU QSBR variable. */
 104         enum rte_hash_qsbr_mode mode;
 105         /**< Mode of RCU QSBR. RTE_HASH_QSBR_MODE_xxx
 106          * '0' for default: create defer queue for reclaim.
 107          */
 108         uint32_t dq_size;
 109         /**< RCU defer queue size.
 110          * default: total hash table entries.
 111          */
 112         uint32_t trigger_reclaim_limit; /**< Threshold to trigger auto reclaim. */
 113         uint32_t max_reclaim_size;
 114         /**< Max entries to reclaim in one go.
 115          * default: RTE_HASH_RCU_DQ_RECLAIM_MAX.
 116          */
 117         void *key_data_ptr;
 118         /**< Pointer passed to the free function. Typically, this is the
 119          * pointer to the data structure to which the resource to free
 120          * (key-data) belongs. This can be NULL.
 121          */
 122         rte_hash_free_key_data free_key_data_func;
 123         /**< Function to call to free the resource (key-data). */
 124 };
 125
 126 /** @internal A hash table structure. */
 127 struct rte_hash;
 128
 129 /**
 130  * Create a new hash table.
 131  *
 132  * @param params
 133  *   Parameters used to create and initialise the hash table.
 134  * @return
 135  *   Pointer to hash table structure that is used in future hash table
 136  *   operations, or NULL on error, with error code set in rte_errno.
 137  *   Possible rte_errno errors include:
 138  *    - E_RTE_NO_CONFIG - function could not get pointer to rte_config structure
 139  *    - E_RTE_SECONDARY - function was called from a secondary process instance
 140  *    - ENOENT - missing entry
 141  *    - EINVAL - invalid parameter passed to function
 142  *    - ENOSPC - the maximum number of memzones has already been allocated
 143  *    - EEXIST - a memzone with the same name already exists
 144  *    - ENOMEM - no appropriate memory area found in which to create memzone
 145  */
 146 struct rte_hash *
 147 rte_hash_create(const struct rte_hash_parameters *params);
 148
 149 /**
 150  * Set a new hash compare function other than the default one.
 151  *
 152  * @note Function pointer does not work with multi-process, so do not use it
 153  * in multi-process mode.
 154  *
 155  * @param h
 156  *   Hash table for which the function is to be changed
 157  * @param func
 158  *   New compare function
 159  */
 160 void rte_hash_set_cmp_func(struct rte_hash *h, rte_hash_cmp_eq_t func);
 161
 162 /**
 163  * Find an existing hash table object and return a pointer to it.
 164  *
 165  * @param name
 166  *   Name of the hash table as passed to rte_hash_create()
 167  * @return
 168  *   Pointer to hash table or NULL if object not found
 169  *   with rte_errno set appropriately. Possible rte_errno values include:
 170  *    - ENOENT - value not available for return
 171  */
 172 struct rte_hash *
 173 rte_hash_find_existing(const char *name);
 174
 175 /**
 176  * De-allocate all memory used by hash table.
 177  * @param h
 178  *   Hash table to free
 179  */
 180 void
 181 rte_hash_free(struct rte_hash *h);
 182
 183 /**
 184  * Reset all hash structure, by zeroing all entries.
 185  * When RTE_HASH_EXTRA_FLAGS_RW_CONCURRENCY_LF is enabled,
 186  * it is application's responsibility to make sure that
 187  * none of the readers are referencing the hash table
 188  * while calling this API.
 189  *
 190  * @param h
 191  *   Hash table to reset
 192  */
 193 void
 194 rte_hash_reset(struct rte_hash *h);
 195
 196 /**
 197  * Return the number of keys in the hash table
 198  * @param h
 199  *  Hash table to query from
 200  * @return
 201  *   - -EINVAL if parameters are invalid
 202  *   - A value indicating how many keys were inserted in the table.
 203  */
 204 int32_t
 205 rte_hash_count(const struct rte_hash *h);
 206
 207 /**
 208  * @warning
 209  * @b EXPERIMENTAL: this API may change without prior notice
 210  *
 211  * Return the maximum key value ID that could possibly be returned by
 212  * rte_hash_add_key function.
 213  *
 214  * @param h
 215  *  Hash table to query from
 216  * @return
 217  *   - -EINVAL if parameters are invalid
 218  *   - A value indicating the max key ID of key slots present in the table.
 219  */
 220 __rte_experimental
 221 int32_t
 222 rte_hash_max_key_id(const struct rte_hash *h);
 223
 224 /**
 225  * Add a key-value pair to an existing hash table.
 226  * This operation is not multi-thread safe
 227  * and should only be called from one thread by default.
 228  * Thread safety can be enabled by setting flag during
 229  * table creation.
 230  * If the key exists already in the table, this API updates its value
 231  * with 'data' passed in this API. It is the responsibility of
 232  * the application to manage any memory associated with the old value.
 233  * The readers might still be using the old value even after this API
 234  * has returned.
 235  *
 236  * @param h
 237  *   Hash table to add the key to.
 238  * @param key
 239  *   Key to add to the hash table.
 240  * @param data
 241  *   Data to add to the hash table.
 242  * @return
 243  *   - 0 if added successfully
 244  *   - -EINVAL if the parameters are invalid.
 245  *   - -ENOSPC if there is no space in the hash for this key.
 246  */
 247 int
 248 rte_hash_add_key_data(const struct rte_hash *h, const void *key, void *data);
 249
 250 /**
 251  * Add a key-value pair with a pre-computed hash value
 252  * to an existing hash table.
 253  * This operation is not multi-thread safe
 254  * and should only be called from one thread by default.
 255  * Thread safety can be enabled by setting flag during
 256  * table creation.
 257  * If the key exists already in the table, this API updates its value
 258  * with 'data' passed in this API. It is the responsibility of
 259  * the application to manage any memory associated with the old value.
 260  * The readers might still be using the old value even after this API
 261  * has returned.
 262  *
 263  * @param h
 264  *   Hash table to add the key to.
 265  * @param key
 266  *   Key to add to the hash table.
 267  * @param sig
 268  *   Precomputed hash value for 'key'
 269  * @param data
 270  *   Data to add to the hash table.
 271  * @return
 272  *   - 0 if added successfully
 273  *   - -EINVAL if the parameters are invalid.
 274  *   - -ENOSPC if there is no space in the hash for this key.
 275  */
 276 int32_t
 277 rte_hash_add_key_with_hash_data(const struct rte_hash *h, const void *key,
 278                                                 hash_sig_t sig, void *data);
 279
 280 /**
 281  * Add a key to an existing hash table. This operation is not multi-thread safe
 282  * and should only be called from one thread by default.
 283  * Thread safety can be enabled by setting flag during
 284  * table creation.
 285  *
 286  * @param h
 287  *   Hash table to add the key to.
 288  * @param key
 289  *   Key to add to the hash table.
 290  * @return
 291  *   - -EINVAL if the parameters are invalid.
 292  *   - -ENOSPC if there is no space in the hash for this key.
 293  *   - A positive value that can be used by the caller as an offset into an
 294  *     array of user data. This value is unique for this key. This
 295  *     unique key id may be larger than the user specified entry count
 296  *     when RTE_HASH_EXTRA_FLAGS_MULTI_WRITER_ADD flag is set.
 297  */
 298 int32_t
 299 rte_hash_add_key(const struct rte_hash *h, const void *key);
 300
 301 /**
 302  * Add a key to an existing hash table.
 303  * This operation is not multi-thread safe
 304  * and should only be called from one thread by default.
 305  * Thread safety can be enabled by setting flag during
 306  * table creation.
 307  *
 308  * @param h
 309  *   Hash table to add the key to.
 310  * @param key
 311  *   Key to add to the hash table.
 312  * @param sig
 313  *   Precomputed hash value for 'key'.
 314  * @return
 315  *   - -EINVAL if the parameters are invalid.
 316  *   - -ENOSPC if there is no space in the hash for this key.
 317  *   - A positive value that can be used by the caller as an offset into an
 318  *     array of user data. This value is unique for this key. This
 319  *     unique key ID may be larger than the user specified entry count
 320  *     when RTE_HASH_EXTRA_FLAGS_MULTI_WRITER_ADD flag is set.
 321  */
 322 int32_t
 323 rte_hash_add_key_with_hash(const struct rte_hash *h, const void *key, hash_sig_t sig);
 324
 325 /**
 326  * Remove a key from an existing hash table.
 327  * This operation is not multi-thread safe
 328  * and should only be called from one thread by default.
 329  * Thread safety can be enabled by setting flag during
 330  * table creation.
 331  * If RTE_HASH_EXTRA_FLAGS_NO_FREE_ON_DEL or
 332  * RTE_HASH_EXTRA_FLAGS_RW_CONCURRENCY_LF is enabled and
 333  * internal RCU is NOT enabled,
 334  * the key index returned by rte_hash_add_key_xxx APIs will not be
 335  * freed by this API. rte_hash_free_key_with_position API must be called
 336  * additionally to free the index associated with the key.
 337  * rte_hash_free_key_with_position API should be called after all
 338  * the readers have stopped referencing the entry corresponding to
 339  * this key. RCU mechanisms could be used to determine such a state.
 340  *
 341  * @param h
 342  *   Hash table to remove the key from.
 343  * @param key
 344  *   Key to remove from the hash table.
 345  * @return
 346  *   - -EINVAL if the parameters are invalid.
 347  *   - -ENOENT if the key is not found.
 348  *   - A positive value that can be used by the caller as an offset into an
 349  *     array of user data. This value is unique for this key, and is the same
 350  *     value that was returned when the key was added.
 351  */
 352 int32_t
 353 rte_hash_del_key(const struct rte_hash *h, const void *key);
 354
 355 /**
 356  * Remove a key from an existing hash table.
 357  * This operation is not multi-thread safe
 358  * and should only be called from one thread by default.
 359  * Thread safety can be enabled by setting flag during
 360  * table creation.
 361  * If RTE_HASH_EXTRA_FLAGS_NO_FREE_ON_DEL or
 362  * RTE_HASH_EXTRA_FLAGS_RW_CONCURRENCY_LF is enabled and
 363  * internal RCU is NOT enabled,
 364  * the key index returned by rte_hash_add_key_xxx APIs will not be
 365  * freed by this API. rte_hash_free_key_with_position API must be called
 366  * additionally to free the index associated with the key.
 367  * rte_hash_free_key_with_position API should be called after all
 368  * the readers have stopped referencing the entry corresponding to
 369  * this key. RCU mechanisms could be used to determine such a state.
 370  *
 371  * @param h
 372  *   Hash table to remove the key from.
 373  * @param key
 374  *   Key to remove from the hash table.
 375  * @param sig
 376  *   Precomputed hash value for 'key'.
 377  * @return
 378  *   - -EINVAL if the parameters are invalid.
 379  *   - -ENOENT if the key is not found.
 380  *   - A positive value that can be used by the caller as an offset into an
 381  *     array of user data. This value is unique for this key, and is the same
 382  *     value that was returned when the key was added.
 383  */
 384 int32_t
 385 rte_hash_del_key_with_hash(const struct rte_hash *h, const void *key, hash_sig_t sig);
 386
 387 /**
 388  * Find a key in the hash table given the position.
 389  * This operation is multi-thread safe with regarding to other lookup threads.
 390  * Read-write concurrency can be enabled by setting flag during
 391  * table creation.
 392  *
 393  * @param h
 394  *   Hash table to get the key from.
 395  * @param position
 396  *   Position returned when the key was inserted.
 397  * @param key
 398  *   Output containing a pointer to the key
 399  * @return
 400  *   - 0 if retrieved successfully
 401  *   - -EINVAL if the parameters are invalid.
 402  *   - -ENOENT if no valid key is found in the given position.
 403  */
 404 int
 405 rte_hash_get_key_with_position(const struct rte_hash *h, const int32_t position,
 406                                void **key);
 407
 408 /**
 409  * @warning
 410  * @b EXPERIMENTAL: this API may change without prior notice
 411  *
 412  * Free a hash key in the hash table given the position
 413  * of the key. This operation is not multi-thread safe and should
 414  * only be called from one thread by default. Thread safety
 415  * can be enabled by setting flag during table creation.
 416  * If RTE_HASH_EXTRA_FLAGS_NO_FREE_ON_DEL or
 417  * RTE_HASH_EXTRA_FLAGS_RW_CONCURRENCY_LF is enabled and
 418  * internal RCU is NOT enabled,
 419  * the key index returned by rte_hash_del_key_xxx APIs must be freed
 420  * using this API. This API should be called after all the readers
 421  * have stopped referencing the entry corresponding to this key.
 422  * RCU mechanisms could be used to determine such a state.
 423  * This API does not validate if the key is already freed.
 424  *
 425  * @param h
 426  *   Hash table to free the key from.
 427  * @param position
 428  *   Position returned when the key was deleted.
 429  * @return
 430  *   - 0 if freed successfully
 431  *   - -EINVAL if the parameters are invalid.
 432  */
 433 __rte_experimental
 434 int
 435 rte_hash_free_key_with_position(const struct rte_hash *h,
 436                                 const int32_t position);
 437
 438 /**
 439  * Find a key-value pair in the hash table.
 440  * This operation is multi-thread safe with regarding to other lookup threads.
 441  * Read-write concurrency can be enabled by setting flag during
 442  * table creation.
 443  *
 444  * @param h
 445  *   Hash table to look in.
 446  * @param key
 447  *   Key to find.
 448  * @param data
 449  *   Output with pointer to data returned from the hash table.
 450  * @return
 451  *   - A positive value that can be used by the caller as an offset into an
 452  *     array of user data. This value is unique for this key, and is the same
 453  *     value that was returned when the key was added.
 454  *   - -EINVAL if the parameters are invalid.
 455  *   - -ENOENT if the key is not found.
 456  */
 457 int
 458 rte_hash_lookup_data(const struct rte_hash *h, const void *key, void **data);
 459
 460 /**
 461  * Find a key-value pair with a pre-computed hash value
 462  * to an existing hash table.
 463  * This operation is multi-thread safe with regarding to other lookup threads.
 464  * Read-write concurrency can be enabled by setting flag during
 465  * table creation.
 466  *
 467  * @param h
 468  *   Hash table to look in.
 469  * @param key
 470  *   Key to find.
 471  * @param sig
 472  *   Precomputed hash value for 'key'
 473  * @param data
 474  *   Output with pointer to data returned from the hash table.
 475  * @return
 476  *   - A positive value that can be used by the caller as an offset into an
 477  *     array of user data. This value is unique for this key, and is the same
 478  *     value that was returned when the key was added.
 479  *   - -EINVAL if the parameters are invalid.
 480  *   - -ENOENT if the key is not found.
 481  */
 482 int
 483 rte_hash_lookup_with_hash_data(const struct rte_hash *h, const void *key,
 484                                         hash_sig_t sig, void **data);
 485
 486 /**
 487  * Find a key in the hash table.
 488  * This operation is multi-thread safe with regarding to other lookup threads.
 489  * Read-write concurrency can be enabled by setting flag during
 490  * table creation.
 491  *
 492  * @param h
 493  *   Hash table to look in.
 494  * @param key
 495  *   Key to find.
 496  * @return
 497  *   - -EINVAL if the parameters are invalid.
 498  *   - -ENOENT if the key is not found.
 499  *   - A positive value that can be used by the caller as an offset into an
 500  *     array of user data. This value is unique for this key, and is the same
 501  *     value that was returned when the key was added.
 502  */
 503 int32_t
 504 rte_hash_lookup(const struct rte_hash *h, const void *key);
 505
 506 /**
 507  * Find a key in the hash table.
 508  * This operation is multi-thread safe with regarding to other lookup threads.
 509  * Read-write concurrency can be enabled by setting flag during
 510  * table creation.
 511  *
 512  * @param h
 513  *   Hash table to look in.
 514  * @param key
 515  *   Key to find.
 516  * @param sig
 517  *   Precomputed hash value for 'key'.
 518  * @return
 519  *   - -EINVAL if the parameters are invalid.
 520  *   - -ENOENT if the key is not found.
 521  *   - A positive value that can be used by the caller as an offset into an
 522  *     array of user data. This value is unique for this key, and is the same
 523  *     value that was returned when the key was added.
 524  */
 525 int32_t
 526 rte_hash_lookup_with_hash(const struct rte_hash *h,
 527                                 const void *key, hash_sig_t sig);
 528
 529 /**
 530  * Calc a hash value by key.
 531  * This operation is not multi-process safe.
 532  *
 533  * @param h
 534  *   Hash table to look in.
 535  * @param key
 536  *   Key to find.
 537  * @return
 538  *   - hash value
 539  */
 540 hash_sig_t
 541 rte_hash_hash(const struct rte_hash *h, const void *key);
 542
 543 /**
 544  * Find multiple keys in the hash table.
 545  * This operation is multi-thread safe with regarding to other lookup threads.
 546  * Read-write concurrency can be enabled by setting flag during
 547  * table creation.
 548  *
 549  * @param h
 550  *   Hash table to look in.
 551  * @param keys
 552  *   A pointer to a list of keys to look for.
 553  * @param num_keys
 554  *   How many keys are in the keys list (less than RTE_HASH_LOOKUP_BULK_MAX).
 555  * @param hit_mask
 556  *   Output containing a bitmask with all successful lookups.
 557  * @param data
 558  *   Output containing array of data returned from all the successful lookups.
 559  * @return
 560  *   -EINVAL if there's an error, otherwise number of successful lookups.
 561  */
 562 int
 563 rte_hash_lookup_bulk_data(const struct rte_hash *h, const void **keys,
 564                       uint32_t num_keys, uint64_t *hit_mask, void *data[]);
 565
 566 /**
 567  * @warning
 568  * @b EXPERIMENTAL: this API may change without prior notice
 569  *
 570  * Find multiple keys in the hash table with precomputed hash value array.
 571  * This operation is multi-thread safe with regarding to other lookup threads.
 572  * Read-write concurrency can be enabled by setting flag during
 573  * table creation.
 574  *
 575  * @param h
 576  *   Hash table to look in.
 577  * @param keys
 578  *   A pointer to a list of keys to look for.
 579  * @param sig
 580  *   A pointer to a list of precomputed hash values for keys.
 581  * @param num_keys
 582  *   How many keys are in the keys list (less than RTE_HASH_LOOKUP_BULK_MAX).
 583  * @param positions
 584  *   Output containing a list of values, corresponding to the list of keys that
 585  *   can be used by the caller as an offset into an array of user data. These
 586  *   values are unique for each key, and are the same values that were returned
 587  *   when each key was added. If a key in the list was not found, then -ENOENT
 588  *   will be the value.
 589  * @return
 590  *   -EINVAL if there's an error, otherwise 0.
 591  */
 592 __rte_experimental
 593 int
 594 rte_hash_lookup_with_hash_bulk(const struct rte_hash *h, const void **keys,
 595                 hash_sig_t *sig, uint32_t num_keys, int32_t *positions);
 596
 597 /**
 598  * @warning
 599  * @b EXPERIMENTAL: this API may change without prior notice
 600  *
 601  * Find multiple keys in the hash table with precomputed hash value array.
 602  * This operation is multi-thread safe with regarding to other lookup threads.
 603  * Read-write concurrency can be enabled by setting flag during
 604  * table creation.
 605  *
 606  * @param h
 607  *   Hash table to look in.
 608  * @param keys
 609  *   A pointer to a list of keys to look for.
 610  * @param sig
 611  *   A pointer to a list of precomputed hash values for keys.
 612  * @param num_keys
 613  *   How many keys are in the keys list (less than RTE_HASH_LOOKUP_BULK_MAX).
 614  * @param hit_mask
 615  *   Output containing a bitmask with all successful lookups.
 616  * @param data
 617  *   Output containing array of data returned from all the successful lookups.
 618  * @return
 619  *   -EINVAL if there's an error, otherwise number of successful lookups.
 620  */
 621 __rte_experimental
 622 int
 623 rte_hash_lookup_with_hash_bulk_data(const struct rte_hash *h,
 624                 const void **keys, hash_sig_t *sig,
 625                 uint32_t num_keys, uint64_t *hit_mask, void *data[]);
 626
 627 /**
 628  * Find multiple keys in the hash table.
 629  * This operation is multi-thread safe with regarding to other lookup threads.
 630  * Read-write concurrency can be enabled by setting flag during
 631  * table creation.
 632  *
 633  * @param h
 634  *   Hash table to look in.
 635  * @param keys
 636  *   A pointer to a list of keys to look for.
 637  * @param num_keys
 638  *   How many keys are in the keys list (less than RTE_HASH_LOOKUP_BULK_MAX).
 639  * @param positions
 640  *   Output containing a list of values, corresponding to the list of keys that
 641  *   can be used by the caller as an offset into an array of user data. These
 642  *   values are unique for each key, and are the same values that were returned
 643  *   when each key was added. If a key in the list was not found, then -ENOENT
 644  *   will be the value.
 645  * @return
 646  *   -EINVAL if there's an error, otherwise 0.
 647  */
 648 int
 649 rte_hash_lookup_bulk(const struct rte_hash *h, const void **keys,
 650                       uint32_t num_keys, int32_t *positions);
 651
 652 /**
 653  * Iterate through the hash table, returning key-value pairs.
 654  *
 655  * @param h
 656  *   Hash table to iterate
 657  * @param key
 658  *   Output containing the key where current iterator
 659  *   was pointing at
 660  * @param data
 661  *   Output containing the data associated with key.
 662  *   Returns NULL if data was not stored.
 663  * @param next
 664  *   Pointer to iterator. Should be 0 to start iterating the hash table.
 665  *   Iterator is incremented after each call of this function.
 666  * @return
 667  *   Position where key was stored, if successful.
 668  *   - -EINVAL if the parameters are invalid.
 669  *   - -ENOENT if end of the hash table.
 670  */
 671 int32_t
 672 rte_hash_iterate(const struct rte_hash *h, const void **key, void **data, uint32_t *next);
 673
 674 /**
 675  * @warning
 676  * @b EXPERIMENTAL: this API may change without prior notice
 677  *
 678  * Associate RCU QSBR variable with a Hash object.
 679  * This API should be called to enable the integrated RCU QSBR support and
 680  * should be called immediately after creating the Hash object.
 681  *
 682  * @param h
 683  *   the hash object to add RCU QSBR
 684  * @param cfg
 685  *   RCU QSBR configuration
 686  * @return
 687  *   On success - 0
 688  *   On error - 1 with error code set in rte_errno.
 689  *   Possible rte_errno codes are:
 690  *   - EINVAL - invalid pointer
 691  *   - EEXIST - already added QSBR
 692  *   - ENOMEM - memory allocation failure
 693  */
 694 __rte_experimental
 695 int rte_hash_rcu_qsbr_add(struct rte_hash *h, struct rte_hash_rcu_config *cfg);
 696
 697 #ifdef __cplusplus
 698 }
 699 #endif
 700
 701 #endif /* _RTE_HASH_H_ */