rte_efd.h(3)

📦
version 25.11.3 · 9 versions
, in ubuntu resolute, ubuntu stonking

💖 rte_efd.h — it's giving "perfect hash table, but make it fashion" 💖

okay bestie, sit down, hydrate, because today we're reading the header for the RTE EFD Table (that's Elastic Flow Distributor energy, and yes, it's a real manual in the Library Functions Manual, section 3). this whole page is basically the group chat of everything you can call in rte_efd.h, and I am obsessed with it. no cap. 🦋

✨ SYNOPSIS ✨

first things first, you gotta bring this in:

#include <stdint.h>

🎀 Macros 🎀

#define RTE_EFD_VALUE_NUM_BITS   (8)
#define RTE_EFD_BURST_MAX   (32)
#define RTE_EFD_NAMESIZE   32

🌸 Functions 🌸

struct rte_efd_table * rte_efd_create (const char *name, uint32_t
    max_num_rules, uint32_t key_len, uint64_t online_cpu_socket_bitmask,
    uint8_t offline_cpu_socket)
void rte_efd_free (struct rte_efd_table *table)
struct rte_efd_table * rte_efd_find_existing (const char *name)
int rte_efd_update (struct rte_efd_table *table, unsigned int socket_id,
    const void *key, efd_value_t value)
int rte_efd_delete (struct rte_efd_table *table, unsigned int socket_id,
    const void *key, efd_value_t *prev_value)
efd_value_t rte_efd_lookup (const struct rte_efd_table *table, unsigned
    int socket_id, const void *key)
void rte_efd_lookup_bulk (const struct rte_efd_table *table, unsigned
    int socket_id, int num_keys, const void **key_list, efd_value_t
    *value_list)

here's the vibe check on each one, real quick:

  • rte_efd_create — makes you a whole EFD table ✨
  • rte_efd_free — releases the resources, bye bestie 👋
  • rte_efd_find_existing — finds a table that already exists and hands you the pointer 🫶
  • rte_efd_update — sets a value for a key, updates live across the socket-local chunks 💅
  • rte_efd_delete — removes the value hanging out with that key 🧚
  • rte_efd_lookup — gets the value for one key, and it's multi-thread safe 🔥
  • rte_efd_lookup_bulk — same thing but for a whole squad of keys at once 🌈

📖 Detailed Description 📖

RTE EFD Table

Definition in file rte_efd.h.

🍓 Macro Definition Documentation 🍓

#define RTE_EFD_VALUE_NUM_BITS (8)

!!! This parameter should be adjusted for your application !!!

okay so this one is the main character of the macros, lowkey. it sets how many bits of value your table can hold. so if you set it to 3, you can store 8 values in the table (between 0 and 7). math is mathing. 💖

this number directly affects the performance of both lookups and insertion. generically speaking: performance goes down the more bits you store in the table.

it's also directly proportional to the size of the online region used for lookups. so like, bigger bits, bigger region, you see the vision.

and ngl, because of the way the CPU operates on memory, your best lookup performance happens when RTE_EFD_VALUE_NUM_BITS is a multiple of 8. those values align the hash indexes on 16-byte boundaries. the greatest performance drop is moving from 8->9 bits, 16->17 bits, etc. 💀

this value must be between 1 and 32.

Definition at line 65 of file rte_efd.h.

#define RTE_EFD_BURST_MAX (32)

maximum number of keys that can be looked up in one call to efd_lookup_bulk. that's it, that's the whole vibe. ✨

Definition at line 99 of file rte_efd.h.

#define RTE_EFD_NAMESIZE 32

maximum number of characters in an efd name. keep it cute, keep it short 🎀

Definition at line 103 of file rte_efd.h.

🌟 Function Documentation 🌟

struct rte_efd_table * rte_efd_create (const char * name, uint32_t max_num_rules, uint32_t key_len, uint64_t online_cpu_socket_bitmask, uint8_t offline_cpu_socket)

creates an EFD table with a single offline region and multiple per-socket internally-managed copies of the online table used for lookups. it's giving architecture, honestly. 🦋

Parameters

  • name — EFD table name
  • max_num_rules — minimum number of rules the table should be sized to hold. will be rounded up to the next smallest valid table size
  • key_len — length of the key
  • online_cpu_socket_bitmask — bitmask specifying which sockets should get a copy of the online table. LSB = socket 0, etc.
  • offline_cpu_socket — identifies the socket where the offline table will be allocated (and most efficiently accessed in the case of updates/insertions)

Returns

EFD table, or NULL if table allocation failed or the bitmask is invalid 😭

void rte_efd_free (struct rte_efd_table * table)

releases the resources from an EFD table. live, laugh, free your memory 🫶

Parameters

  • table — pointer to table allocated with rte_efd_create(). if table is NULL, no operation is performed.

struct rte_efd_table * rte_efd_find_existing (const char * name)

find an existing EFD table object and return a pointer to it. it's giving "hey, are you already here?" 💅

Parameters

  • name — name of the EFD table as passed to rte_efd_create()

Returns

pointer to EFD table or NULL if object not found, with rte_errno set appropriately. possible rte_errno values include:

  • ENOENT — value not available for return

int rte_efd_update (struct rte_efd_table * table, unsigned int socket_id, const void * key, efd_value_t value)

computes an updated table entry for the supplied key/value pair. the update is then immediately applied to the provided table, and all socket-local copies of the chunks are updated. 🔥

⚠️ this operation is not multi-thread safe and should only be called from one thread. bestie. one thread. I'm serious.

Parameters

  • table — EFD table to reference
  • socket_id — socket ID to use to lookup existing value (ideally caller's socket id)
  • key — EFD table key to modify
  • value — value to associate with the key

Returns

  • RTE_EFD_UPDATE_WARN_GROUP_FULL — operation is insert, and the last available space in the key's group was just used. future inserts may fail as groups fill up. this operation was still successful, and entry contains a valid update
  • RTE_EFD_UPDATE_FAILED — either the EFD failed to find a suitable perfect hash or the group was full. this is a fatal error, and the table is now in an indeterminate state 💀
  • RTE_EFD_UPDATE_NO_CHANGE — operation resulted in no change to the table (same value already exists)
  • 0 — success ✨

int rte_efd_delete (struct rte_efd_table * table, unsigned int socket_id, const void * key, efd_value_t * prev_value)

removes any value currently associated with the specified key from the table. 🧹

⚠️ this operation is not multi-thread safe and should only be called from one thread.

Parameters

  • table — EFD table to reference
  • socket_id — socket ID to use to lookup existing value (ideally caller's socket id)
  • key — EFD table key to delete
  • prev_value — if not NULL, will store the previous value here before deleting it

Returns

0 — successfully found and deleted the key. nonzero otherwise.

efd_value_t rte_efd_lookup (const struct rte_efd_table * table, unsigned int socket_id, const void * key)

looks up the value associated with a key. this operation is multi-thread safe. slay 🌈

NOTE: lookups will always succeed — this is a property of using a perfect hash table. if the specified key was never inserted, a pseudorandom answer will be returned. there is no way to know based on the lookup if the key was ever inserted originally, so this must be tracked elsewhere. not me finding out lookups are just out here lying to me 😭

Parameters

  • table — EFD table to reference
  • socket_id — socket ID to use to lookup existing value (ideally caller's socket id)
  • key — EFD table key to look up

Returns

value associated with the key, or random junk if the key was never inserted. fr fr. 🫠

void rte_efd_lookup_bulk (const struct rte_efd_table * table, unsigned int socket_id, int num_keys, const void ** key_list, efd_value_t * value_list)

looks up the value associated with several keys. this operation is multi-thread safe. group lookup, group chat energy 👑

NOTE: lookups will always succeed — this is a property of using a perfect hash table. if the specified key was never inserted, a pseudorandom answer will be returned. there is no way to know based on the lookup if the key was ever inserted originally, so this must be tracked elsewhere.

Parameters

  • table — EFD table to reference
  • socket_id — socket ID to use to lookup existing value (ideally caller's socket id)
  • num_keys — number of keys in the key_list array, must be less than RTE_EFD_BURST_MAX
  • key_list — array of num_keys pointers which point to keys to look up
  • value_list — array of size num_keys where lookup values will be stored

👑 Author 👑

generated automatically by Doxygen for DPDK from the source code. so like, no human wrote this one, it's Doxygen's own little diva. 💅

and that's the whole page, bestie. every option, every return value, every warning, all of it, untouched. periodt. ✨

DPDK — Version 25.11.3 💖 mwah, go write some perfect hashes, ily 🫶🎀🦋

📦 where this page comes from