---
name: "rte_member_free"
section: "3"
platform: "linux"
package: "dpdk-doc"
version: "24.11.4-0+deb13u1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/rte_member.h"
---

# rte\_member\_free(3)

Part of [rte\_member.h(3)](/rte_member.h/3.md).

## NAME

rte\_member.h

## SYNOPSIS

`#include <stdint.h>`\
 `#include <stdbool.h>`\
 `#include <inttypes.h>`\
 `#include <rte_common.h>`\
 `#include <rte_jhash.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

struct rte\_member\_setsum \* **rte\_member\_find\_existing** (const char \*name)\
 struct rte\_member\_setsum \* **rte\_member\_create** (const struct **rte\_member\_parameters** \*params)\
 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\_free** (struct rte\_member\_setsum \*setsum)\
 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

RTE Membership Library

The Membership Library is an extension and generalization of a traditional filter (for example Bloom Filter and cuckoo filter) structure that has multiple usages in a variety of workloads and applications. The library is used to test if a key belongs to certain sets. Two types of such 'set-summary' structures are implemented: hash-table based (HT) and vector bloom filter (vBF). For HT setsummary, two subtypes or modes are available, cache and non-cache modes. The table below summarize some properties of the different implementations.

Definition in file **rte\_member.h**.

## Macro Definition Documentation

### #define RTE\_MEMBER\_NO\_MATCH 0

Invalid set ID used to mean no match found.

Definition at line **66** of file **rte\_member.h**.

### #define RTE\_MEMBER\_ENTRIES\_MAX (1 \<\< 30)

Maximum size of hash table that can be created.

Definition at line **68** of file **rte\_member.h**.

### #define RTE\_MEMBER\_LOOKUP\_BULK\_MAX 64

Maximum number of keys that can be searched as a bulk

Definition at line **70** of file **rte\_member.h**.

### #define RTE\_MEMBER\_BUCKET\_ENTRIES 16

Entry count per bucket in hash table based mode.

Definition at line **72** of file **rte\_member.h**.

### #define RTE\_MEMBER\_NAMESIZE 32

Maximum number of characters in setsum name.

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

As packets 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 the flag if prefer always bounded mode, which only starts sampling after receiving enough packets to keep the results accuracy always bounded.

Definition at line **86** of file **rte\_member.h**.

### #define RTE\_MEMBER\_SKETCH\_COUNT\_BYTE 0x02

For sketch, use the flag if 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 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

Define 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* **114** *of file* **rte\_member.h***.*

## Function Documentation

### struct rte\_member\_setsum \* rte\_member\_find\_existing (const char \* name)

*Find an existing set-summary and return a pointer to it.*

**Parameters**

*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*

### struct rte\_member\_setsum \* rte\_member\_create (const struct rte\_member\_parameters \* params)

*Create set-summary (SS).*

**Parameters**

*params Parameters to initialize the setsummary.*

**Returns**

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

### 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*

**Parameters**

*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.*

### 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*

**Parameters**

*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.*

### 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.*

**Parameters**

*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.*

### 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.*

**Parameters**

*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.*

### int rte\_member\_add (const struct rte\_member\_setsum \* setsum, const void \* key, member\_set\_t set\_id)

*Insert key into set-summary (SS).*

**Parameters**

*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.*

### 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.*

**Parameters**

*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.*

### 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.*

**Parameters**

*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.*

### int rte\_member\_report\_heavyhitter (const struct rte\_member\_setsum \* setsum, void \*\* keys, uint64\_t \* counts)

*Report heavyhitter flow-keys into set-summary (SS).*

**Parameters**

*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.*

### void rte\_member\_free (struct rte\_member\_setsum \* setsum)

*De-allocate memory used by set-summary.*

**Parameters**

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

### 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.*

**Parameters**

*setsum Pointer to the set-summary.*

### 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.*

**Parameters**

*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.*