.TH "rte_member.h" 3 "Version 25.11.0" "DPDK" \" -*- nroff -*-
.ad l
.nh
.SH NAME
rte_member.h
.SH SYNOPSIS
.br
.PP
\fR#include <stdint\&.h>\fP
.br
\fR#include <stdbool\&.h>\fP
.br
\fR#include <inttypes\&.h>\fP
.br
\fR#include <rte_common\&.h>\fP
.br

.SS "Data Structures"

.in +1c
.ti -1c
.RI "struct \fBrte_member_parameters\fP"
.br
.in -1c
.SS "Macros"

.in +1c
.ti -1c
.RI "#define \fBRTE_MEMBER_NO_MATCH\fP   0"
.br
.ti -1c
.RI "#define \fBRTE_MEMBER_ENTRIES_MAX\fP   (1 << 30)"
.br
.ti -1c
.RI "#define \fBRTE_MEMBER_LOOKUP_BULK_MAX\fP   64"
.br
.ti -1c
.RI "#define \fBRTE_MEMBER_BUCKET_ENTRIES\fP   16"
.br
.ti -1c
.RI "#define \fBRTE_MEMBER_NAMESIZE\fP   32"
.br
.ti -1c
.RI "#define \fBRTE_RAND_MAX\fP   ~0LLU"
.br
.ti -1c
.RI "#define \fBRTE_MEMBER_SKETCH_ALWAYS_BOUNDED\fP   0x01"
.br
.ti -1c
.RI "#define \fBRTE_MEMBER_SKETCH_COUNT_BYTE\fP   0x02"
.br
.in -1c
.SS "Typedefs"

.in +1c
.ti -1c
.RI "\fBtypedef\fP uint16_t \fBmember_set_t\fP"
.br
.in -1c
.SS "Enumerations"

.in +1c
.ti -1c
.RI "enum \fBrte_member_setsum_type\fP { \fBRTE_MEMBER_TYPE_HT\fP = 0, \fBRTE_MEMBER_TYPE_VBF\fP, \fBRTE_MEMBER_TYPE_SKETCH\fP, \fBRTE_MEMBER_NUM_TYPE\fP }"
.br
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "struct rte_member_setsum * \fBrte_member_find_existing\fP (const char *name)"
.br
.ti -1c
.RI "void \fBrte_member_free\fP (struct rte_member_setsum *setsum)"
.br
.ti -1c
.RI "struct rte_member_setsum * \fBrte_member_create\fP (const struct \fBrte_member_parameters\fP *params) \fB__rte_malloc\fP \fB__rte_dealloc\fP(\fBrte_member_free\fP"
.br
.ti -1c
.RI "struct rte_member_setsum int \fBrte_member_lookup\fP (const struct rte_member_setsum *setsum, const void *key, \fBmember_set_t\fP *set_id)"
.br
.ti -1c
.RI "int \fBrte_member_lookup_bulk\fP (const struct rte_member_setsum *setsum, const void **keys, uint32_t num_keys, \fBmember_set_t\fP *set_ids)"
.br
.ti -1c
.RI "int \fBrte_member_lookup_multi\fP (const struct rte_member_setsum *setsum, const void *key, uint32_t max_match_per_key, \fBmember_set_t\fP *set_id)"
.br
.ti -1c
.RI "int \fBrte_member_lookup_multi_bulk\fP (const struct rte_member_setsum *setsum, const void **keys, uint32_t num_keys, uint32_t max_match_per_key, uint32_t *match_count, \fBmember_set_t\fP *set_ids)"
.br
.ti -1c
.RI "int \fBrte_member_add\fP (const struct rte_member_setsum *setsum, const void *key, \fBmember_set_t\fP set_id)"
.br
.ti -1c
.RI "int \fBrte_member_add_byte_count\fP (const struct rte_member_setsum *setsum, const void *key, uint32_t byte_count)"
.br
.ti -1c
.RI "int \fBrte_member_query_count\fP (const struct rte_member_setsum *setsum, const void *key, uint64_t *count)"
.br
.ti -1c
.RI "int \fBrte_member_report_heavyhitter\fP (const struct rte_member_setsum *setsum, void **keys, uint64_t *counts)"
.br
.ti -1c
.RI "void \fBrte_member_reset\fP (const struct rte_member_setsum *setsum)"
.br
.ti -1c
.RI "int \fBrte_member_delete\fP (const struct rte_member_setsum *setsum, const void *key, \fBmember_set_t\fP set_id)"
.br
.in -1c
.SH "Detailed Description"
.PP 
RTE Membership Library

.PP
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\&. 
.PP
Definition in file \fBrte_member\&.h\fP\&.
.SH "Macro Definition Documentation"
.PP 
.SS "#define RTE_MEMBER_NO_MATCH   0"
Invalid set ID used to mean no match found\&. 
.PP
Definition at line \fB66\fP of file \fBrte_member\&.h\fP\&.
.SS "#define RTE_MEMBER_ENTRIES_MAX   (1 << 30)"
Maximum size of hash table that can be created\&. 
.PP
Definition at line \fB68\fP of file \fBrte_member\&.h\fP\&.
.SS "#define RTE_MEMBER_LOOKUP_BULK_MAX   64"
Maximum number of keys that can be searched as a bulk 
.PP
Definition at line \fB70\fP of file \fBrte_member\&.h\fP\&.
.SS "#define RTE_MEMBER_BUCKET_ENTRIES   16"
Entry count per bucket in hash table based mode\&. 
.PP
Definition at line \fB72\fP of file \fBrte_member\&.h\fP\&.
.SS "#define RTE_MEMBER_NAMESIZE   32"
Maximum number of characters in setsum name\&. 
.PP
Definition at line \fB74\fP of file \fBrte_member\&.h\fP\&.
.SS "#define RTE_RAND_MAX   ~0LLU"
Max value of the random number 
.PP
Definition at line \fB76\fP of file \fBrte_member\&.h\fP\&.
.SS "#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\&. 
.PP
Definition at line \fB86\fP of file \fBrte_member\&.h\fP\&.
.SS "#define RTE_MEMBER_SKETCH_COUNT_BYTE   0x02"
For sketch, use the flag if to count packet size instead of packet count 
.PP
Definition at line \fB88\fP of file \fBrte_member\&.h\fP\&.
.SH "Typedef Documentation"
.PP 
.SS "\fBtypedef\fP uint16_t \fBmember_set_t\fP"
The set ID type that stored internally in hash table based set summary\&. 
.PP
Definition at line \fB64\fP of file \fBrte_member\&.h\fP\&.
.SH "Enumeration Type Documentation"
.PP 
.SS "enum \fBrte_member_setsum_type\fP"
Define different set summary types 
.PP
\fBEnumerator\fP
.in +1c
.TP
\f(BIRTE_MEMBER_TYPE_HT \fP
Hash table based set summary\&. 
.TP
\f(BIRTE_MEMBER_TYPE_VBF \fP
Vector of bloom filters\&. 
.PP
Definition at line \fB105\fP of file \fBrte_member\&.h\fP\&.
.SH "Function Documentation"
.PP 
.SS "struct rte_member_setsum * rte_member_find_existing (const char * name)"
Find an existing set-summary and return a pointer to it\&.

.PP
\fBParameters\fP
.RS 4
\fIname\fP Name of the set-summary\&. 
.RE
.PP
\fBReturns\fP
.RS 4
Pointer to the set-summary or NULL if object not found with rte_errno set appropriately\&. Possible rte_errno values include:
.IP "\(bu" 2
ENOENT - value not available for return 
.PP
.RE
.PP

.SS "void rte_member_free (struct rte_member_setsum * setsum)"
De-allocate memory used by set-summary\&.

.PP
\fBParameters\fP
.RS 4
\fIsetsum\fP Pointer to the set summary\&. If setsum is NULL, no operation is performed\&. 
.RE
.PP

.SS "struct rte_member_setsum * rte_member_create (const struct \fBrte_member_parameters\fP * params)"
Create set-summary (SS)\&.

.PP
\fBParameters\fP
.RS 4
\fIparams\fP Parameters to initialize the setsummary\&. 
.RE
.PP
\fBReturns\fP
.RS 4
Return the pointer to the setsummary\&. Return value is NULL if the creation failed\&. 
.RE
.PP

.SS "struct rte_member_setsum int rte_member_lookup (const struct rte_member_setsum * setsum, const void * key, \fBmember_set_t\fP * set_id)"
Lookup key in set-summary (SS)\&. Single key lookup and return as soon as the first match found

.PP
\fBParameters\fP
.RS 4
\fIsetsum\fP Pointer of a setsummary\&. 
.br
\fIkey\fP Pointer of the key to be looked up\&. 
.br
\fIset_id\fP Output the set id matches the key\&. 
.RE
.PP
\fBReturns\fP
.RS 4
Return 1 for found a match and 0 for not found a match\&. 
.RE
.PP

.SS "int rte_member_lookup_bulk (const struct rte_member_setsum * setsum, const void ** keys, uint32_t num_keys, \fBmember_set_t\fP * set_ids)"
Lookup bulk of keys in set-summary (SS)\&. Each key lookup returns as soon as the first match found

.PP
\fBParameters\fP
.RS 4
\fIsetsum\fP Pointer of a setsummary\&. 
.br
\fIkeys\fP Pointer of the bulk of keys to be looked up\&. 
.br
\fInum_keys\fP Number of keys that will be lookup\&. 
.br
\fIset_ids\fP 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\&. 
.RE
.PP
\fBReturns\fP
.RS 4
The number of keys that found a match\&. 
.RE
.PP

.SS "int rte_member_lookup_multi (const struct rte_member_setsum * setsum, const void * key, uint32_t max_match_per_key, \fBmember_set_t\fP * 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\&.

.PP
\fBParameters\fP
.RS 4
\fIsetsum\fP Pointer of a set-summary\&. 
.br
\fIkey\fP Pointer of the key that to be looked up\&. 
.br
\fImax_match_per_key\fP User specified maximum number of matches for each key\&. The function returns as soon as this number of matches found for the key\&. 
.br
\fIset_id\fP 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\&. 
.RE
.PP
\fBReturns\fP
.RS 4
The number of matches that found for the key\&. For cache mode HT set-summary, the number should be at most 1\&. 
.RE
.PP

.SS "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, \fBmember_set_t\fP * 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\&.

.PP
\fBParameters\fP
.RS 4
\fIsetsum\fP Pointer of a setsummary\&. 
.br
\fIkeys\fP Pointer of the keys to be looked up\&. 
.br
\fInum_keys\fP The number of keys that will be lookup\&. 
.br
\fImax_match_per_key\fP The possible maximum number of matches for each key\&. 
.br
\fImatch_count\fP Output the number of matches for each key in an array\&. 
.br
\fIset_ids\fP 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] 
.RE
.PP
\fBReturns\fP
.RS 4
The number of keys that found one or more matches in the set-summary\&. 
.RE
.PP

.SS "int rte_member_add (const struct rte_member_setsum * setsum, const void * key, \fBmember_set_t\fP set_id)"
Insert key into set-summary (SS)\&.

.PP
\fBParameters\fP
.RS 4
\fIsetsum\fP Pointer of a set-summary\&. 
.br
\fIkey\fP Pointer of the key to be added\&. 
.br
\fIset_id\fP 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\&. 
.RE
.PP
\fBReturns\fP
.RS 4
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\&. 
.RE
.PP

.SS "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\&.

.PP
\fBParameters\fP
.RS 4
\fIsetsum\fP Pointer of a set-summary\&. 
.br
\fIkey\fP Pointer of the key to be added\&. 
.br
\fIbyte_count\fP Add the byte count of the packet into the sketch\&. 
.RE
.PP
\fBReturns\fP
.RS 4
Return -EINVAL for invalid parameters, otherwise return 0\&. 
.RE
.PP

.SS "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\&.

.PP
\fBParameters\fP
.RS 4
\fIsetsum\fP Pointer of a set-summary\&. 
.br
\fIkey\fP Pointer of the key to be added\&. 
.br
\fIcount\fP The output packet count or byte count\&. 
.RE
.PP
\fBReturns\fP
.RS 4
Return -EINVAL for invalid parameters\&. 
.RE
.PP

.SS "int rte_member_report_heavyhitter (const struct rte_member_setsum * setsum, void ** keys, uint64_t * counts)"
Report heavyhitter flow-keys into set-summary (SS)\&.

.PP
\fBParameters\fP
.RS 4
\fIsetsum\fP Pointer of a set-summary\&. 
.br
\fIkeys\fP Pointer of the output top-k key array\&. 
.br
\fIcounts\fP Pointer of the output packet count or byte count array of the top-k keys\&. 
.RE
.PP
\fBReturns\fP
.RS 4
Return -EINVAL for invalid parameters\&. Return a positive integer indicate how many heavy hitters are reported\&. 
.RE
.PP

.SS "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\&.

.PP
\fBParameters\fP
.RS 4
\fIsetsum\fP Pointer to the set-summary\&. 
.RE
.PP

.SS "int rte_member_delete (const struct rte_member_setsum * setsum, const void * key, \fBmember_set_t\fP 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\&.

.PP
\fBParameters\fP
.RS 4
\fIsetsum\fP Pointer to the set-summary\&. 
.br
\fIkey\fP Pointer of the key to be deleted\&. 
.br
\fIset_id\fP 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\&. 
.RE
.PP
\fBReturns\fP
.RS 4
If no entry found to delete, an error code of -ENOENT could be returned\&. 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for DPDK from the source code\&.
