rte_member.h(3)

📦 version 26.03, in nixos 26.05, nixpkgs unstable

💖 NAME 💖

rte_member.h — bestie, this is the header file itself, the whole membership library vibe lives in here ✨

✨ SYNOPSIS ✨

Okay so first things first, the includes you're gonna need, no cap:

#include <stdint.h>
#include <stdbool.h>
#include <inttypes.h>
#include <rte_common.h>

🌸 Data Structures 🌸

  • struct rte_member_parameters

🎀 Macros 🎀

#define RTE_MEMBER_NO_MATCH   0
#define RTE_MEMBER_ENTRIES_MAX   (1 << 30)
#define RTE_MEMBER_LOOKUP_BULK_MAX   64
#define RTE_MEMBER_BUCKET_ENTRIES   16
#define RTE_MEMBER_NAMESIZE   32
#define RTE_RAND_MAX   ~0LLU
#define RTE_MEMBER_SKETCH_ALWAYS_BOUNDED   0x01
#define RTE_MEMBER_SKETCH_COUNT_BYTE   0x02

🦋 Typedefs 🦋

  • typedef uint16_t member_set_t

🌈 Enumerations 🌈

enum rte_member_setsum_type { RTE_MEMBER_TYPE_HT = 0,
    RTE_MEMBER_TYPE_VBF, RTE_MEMBER_TYPE_SKETCH, RTE_MEMBER_NUM_TYPE }

💅 Functions 💅

Here's the whole function lineup, copied exactly so you can yeet them straight into your code 😌

struct rte_member_setsum * rte_member_find_existing (const char *name)
void rte_member_free (struct rte_member_setsum *setsum)
struct rte_member_setsum * rte_member_create (const struct
    rte_member_parameters *params) __rte_malloc
    __rte_dealloc(rte_member_free
struct rte_member_setsum int rte_member_lookup (const struct
    rte_member_setsum *setsum, const void *key, member_set_t *set_id)
int rte_member_lookup_bulk (const struct rte_member_setsum *setsum,
    const void **keys, uint32_t num_keys, member_set_t *set_ids)
int rte_member_lookup_multi (const struct rte_member_setsum *setsum,
    const void *key, uint32_t max_match_per_key, member_set_t *set_id)
int rte_member_lookup_multi_bulk (const struct rte_member_setsum
    *setsum, const void **keys, uint32_t num_keys, uint32_t
    max_match_per_key, uint32_t *match_count, member_set_t *set_ids)
int rte_member_add (const struct rte_member_setsum *setsum, const void
    *key, member_set_t set_id)
int rte_member_add_byte_count (const struct rte_member_setsum *setsum,
    const void *key, uint32_t byte_count)
int rte_member_query_count (const struct rte_member_setsum *setsum,
    const void *key, uint64_t *count)
int rte_member_report_heavyhitter (const struct rte_member_setsum
    *setsum, void **keys, uint64_t *counts)
void rte_member_reset (const struct rte_member_setsum *setsum)
int rte_member_delete (const struct rte_member_setsum *setsum, const
    void *key, member_set_t set_id)

🌸 Detailed Description 🌸

So this is the RTE Membership Library, and bestie, it's literally an extension and generalization of a traditional filter (think Bloom Filter, think cuckoo filter 👀) — except it's the kind of structure that has multiple usages across a whole variety of workloads and applications. Main character energy, honestly.

The library's whole thing is testing whether a key belongs to certain sets. And there are two types of these "set-summary" structures implemented:

  • hash-table based (HT)
  • vector bloom filter (vBF)

And for HT setsummary specifically, there are two subtypes aka modes available: cache and non-cache modes 🔥

The original doc says "The table below summarize some properties of the different implementations." — so yeah, there's a table that lives over in the header docs summarizing properties of the different implementations. (It's a Doxygen table situation, iykyk.)

Definition in file rte_member.h.

🎀 Macro Definition Documentation 🎀

#define RTE_MEMBER_NO_MATCH 0

This is the invalid set ID — it's the value that means "nope, no match found" 🙈 Use it as your "nothing here" signal.

Definition at line 66 of file rte_member.h.

#define RTE_MEMBER_ENTRIES_MAX (1 << 30)

The maximum size of hash table that can be created. That's the ceiling, bestie, don't try to go past it 💀

Definition at line 68 of file rte_member.h.

#define RTE_MEMBER_LOOKUP_BULK_MAX 64

The maximum number of keys you can search as a bulk. Sixty-four, periodt 💅

Definition at line 70 of file rte_member.h.

#define RTE_MEMBER_BUCKET_ENTRIES 16

Entry count per bucket in hash table based mode. Sixteen entries per bucket, that's the rule 🎀

Definition at line 72 of file rte_member.h.

#define RTE_MEMBER_NAMESIZE 32

Maximum number of characters in setsum name. Thirty-two characters, so don't go naming your setsum a whole novel ✨

Definition at line 74 of file rte_member.h.

#define RTE_RAND_MAX ~0LLU

Max value of the random number 🌈

Definition at line 76 of file rte_member.h.

#define RTE_MEMBER_SKETCH_ALWAYS_BOUNDED 0x01

Okay so here's the situation: as packets get skipped in the sampling-based algorithm, the accounting results accuracy is not guaranteed in the start stage 😭 There should be a "convergence time" to achieve the accuracy after receiving enough packets. For sketch, use this flag if you prefer always bounded mode — which only starts sampling after receiving enough packets, so the results accuracy stays always bounded 🫶

Definition at line 86 of file rte_member.h.

#define RTE_MEMBER_SKETCH_COUNT_BYTE 0x02

For sketch, use this flag if you want to count packet size instead of packet count 👑

Definition at line 88 of file rte_member.h.

🦋 Typedef Documentation 🦋

typedef uint16_t member_set_t

The set ID type that's stored internally in hash table based set summary 💖

Definition at line 64 of file rte_member.h.

👑 Enumeration Type Documentation 👑

enum rte_member_setsum_type

This one defines the different set summary types ⭐

Enumerator:

  • RTE_MEMBER_TYPE_HT — Hash table based set summary.
  • RTE_MEMBER_TYPE_VBF — Vector of bloom filters.

Definition at line 105 of file rte_member.h.

heads up: the synopsis up top also lists RTE_MEMBER_TYPE_SKETCH and RTE_MEMBER_NUM_TYPE in the enum, so keep those in mind too, bestie 🧚

💅 FUNCTION DOCUMENTATION 💅

okay bestie, this is where the actual functions live. every signature below is pasted exactly as the page has it — even the weird ones. i am not “fixing” anything, that’s not the assignment. periodt. 🫶

🎀 rte_member_find_existing 🎀

struct rte_member_setsum * rte_member_find_existing (const char * name)

Find an existing set-summary and return a pointer to it. lowkey a “do you already exist, bestie?” check. ✨

  • name — Name of the set-summary.

Returns: Pointer to the set-summary or NULL if object not found with rte_errno set appropriately. Possible rte_errno values include:

  • ENOENT — value not available for return

🦋 rte_member_free 🦋

void rte_member_free (struct rte_member_setsum * setsum)

De-allocate memory used by set-summary. say bye to the allocation, bestie. 🫶

  • setsum — Pointer to the set summary. If setsum is NULL, no operation is performed.

🌸 rte_member_create 🌸

struct rte_member_setsum * rte_member_create (const struct rte_member_parameters * params)

Create set-summary (SS). main character creation energy. 👑

  • params — Parameters to initialize the setsummary.

Returns: Return the pointer to the setsummary. Return value is NULL if the creation failed.

💖 rte_member_lookup 💖

struct rte_member_setsum int rte_member_lookup (const struct rte_member_setsum * setsum, const void * key, member_set_t * set_id)

Lookup key in set-summary (SS). Single key lookup and return as soon as the first match found. yes, <struct rte_member_setsum int ...> is exactly what the page says — i’m holding it gently and not editing it. no cap. 😭

  • setsum — Pointer of a setsummary.
  • key — Pointer of the key to be looked up.
  • set_id — Output the set id matches the key.

Returns: Return 1 for found a match and 0 for not found a match.

🧚 rte_member_lookup_bulk 🧚

int rte_member_lookup_bulk (const struct rte_member_setsum * setsum, const void ** keys, uint32_t num_keys, member_set_t * set_ids)

Lookup bulk of keys in set-summary (SS). Each key lookup returns as soon as the first match found. bulk mode said “i can do this all day.” 💅

  • setsum — Pointer of a setsummary.
  • keys — Pointer of the bulk of keys to be looked up.
  • num_keys — Number of keys that will be lookup.
  • set_ids — Output set ids for all the keys to this array. User should preallocate array that can contain all results, which size is the num_keys.

Returns: The number of keys that found a match.

🍓 rte_member_lookup_multi 🍓

int rte_member_lookup_multi (const struct rte_member_setsum * setsum, const void * key, uint32_t max_match_per_key, member_set_t * set_id)

Lookup a key in set-summary (SS) for multiple matches. The key lookup will find all matched entries (multiple match). Note that for cache mode of HT, each key can have at most one match. This is because keys with same signature that maps to same bucket will overwrite each other. So multi-match lookup should be used for vBF and non-cache HT. that overwrite detail is important, bestie — don’t sleep on it. 🔥

  • setsum — Pointer of a set-summary.
  • key — Pointer of the key that to be looked up.
  • max_match_per_key — User specified maximum number of matches for each key. The function returns as soon as this number of matches found for the key.
  • set_id — Output set ids for all the matches of the key. User needs to preallocate the array that can contain max_match_per_key number of results.

Returns: The number of matches that found for the key. For cache mode HT set-summary, the number should be at most 1.

🌈 rte_member_lookup_multi_bulk 🌈

int rte_member_lookup_multi_bulk (const struct rte_member_setsum * setsum, const void ** keys, uint32_t num_keys, uint32_t max_match_per_key, uint32_t * match_count, member_set_t * set_ids)

Lookup a bulk of keys in set-summary (SS) for multiple matches each key. Each key lookup will find all matched entries (multiple match). Note that for cache mode HT, each key can have at most one match. So multi-match function is mainly used for vBF and non-cache mode HT. combo move: bulk and multi. she ate. ✨

  • setsum — Pointer of a setsummary.
  • keys — Pointer of the keys to be looked up.
  • num_keys — The number of keys that will be lookup.
  • max_match_per_key — The possible maximum number of matches for each key.
  • match_count — Output the number of matches for each key in an array.
  • set_ids — Return set ids for all the matches of all keys. Users pass in a preallocated 2D array with first dimension as key index and second dimension as match index. For example set_ids[bulk_size][max_match_per_key]

Returns: The number of keys that found one or more matches in the set-summary.

👑 rte_member_add 👑

int rte_member_add (const struct rte_member_setsum * setsum, const void * key, member_set_t set_id)

Insert key into set-summary (SS). adding to the set, putting your key on the map, very main character. 💅

  • setsum — Pointer of a set-summary.
  • key — Pointer of the key to be added.
  • set_id — The set id associated with the key that needs to be added. Different mode supports different set_id ranges. 0 cannot be used as set_id since RTE_MEMBER_NO_MATCH by default is set as 0. For HT mode, the set_id has range as [1, 0x7FFF], MSB is reserved. For vBF mode the set id is limited by the num_set parameter when create the set-summary. For sketch mode, this id is ignored.

Returns: HT (cache mode) and vBF should never fail unless the set_id is not in the valid range. In such case -EINVAL is returned. For HT (non-cache mode) it could fail with -ENOSPC error code when table is full. For success it returns different values for different modes to provide extra information for users. Return 0 for HT (cache mode) if the add does not cause eviction, return 1 otherwise. Return 0 for non-cache mode if success, -ENOSPC for full, and 1 if cuckoo eviction happens. Always returns 0 for vBF mode and sketch.

🎀 rte_member_add_byte_count 🎀

int rte_member_add_byte_count (const struct rte_member_setsum * setsum, const void * key, uint32_t byte_count)

Add the packet byte size into the sketch. sketch mode said “give me the bytes.” 🍓

  • setsum — Pointer of a set-summary.
  • key — Pointer of the key to be added.
  • byte_count — Add the byte count of the packet into the sketch.

Returns: Return -EINVAL for invalid parameters, otherwise return 0.

🦋 rte_member_query_count 🦋

int rte_member_query_count (const struct rte_member_setsum * setsum, const void * key, uint64_t * count)

Query packet count for a certain flow-key. asking the set-summary “bestie, what’s the count?” 💖

  • setsum — Pointer of a set-summary.
  • key — Pointer of the key to be added.
  • count — The output packet count or byte count.

Returns: Return -EINVAL for invalid parameters.

🌟 rte_member_report_heavyhitter 🌟

int rte_member_report_heavyhitter (const struct rte_member_setsum * setsum, void ** keys, uint64_t * counts)

Report heavyhitter flow-keys into set-summary (SS). heavyhitters are the ones with main character energy, obviously. 👑

  • setsum — Pointer of a set-summary.
  • keys — Pointer of the output top-k key array.
  • counts — Pointer of the output packet count or byte count array of the top-k keys.

Returns: Return -EINVAL for invalid parameters. Return a positive integer indicate how many heavy hitters are reported.

💜 rte_member_reset 💜

void rte_member_reset (const struct rte_member_setsum * setsum)

Reset the set-summary tables. E.g. reset bits to be 0 in BF, reset set_id in each entry to be RTE_MEMBER_NO_MATCH in HT based SS. fresh start, clean slate, new era. ✨

  • setsum — Pointer to the set-summary.

💀 rte_member_delete 💀

int rte_member_delete (const struct rte_member_setsum * setsum, const void * key, member_set_t set_id)

Delete items from the set-summary. Note that vBF does not support deletion in current implementation. For vBF, error code of -EINVAL will be returned. so vBF said “no deleting today,” and that’s literally in the doc. 🙈

  • setsum — Pointer to the set-summary.
  • key — Pointer of the key to be deleted.
  • set_id — For HT mode, we need both key and its corresponding set_id to properly delete the key. Without set_id, we may delete other keys with the same signature.

Returns: If no entry found to delete, an error code of -ENOENT could be returned.

🌸 AUTHOR 🌸

Generated automatically by Doxygen for DPDK from the source code.

okay that’s the whole page, bestie. the footer situation is literally DPDK, Version 26.03.0, and this page is rte_member.h(3) — Doxygen generated it for DPDK from the source code, so it’s official official. mwah 💋🎀✨

📦 where this page comes from