rte_fbarray.h(3)

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

💖 rte_fbarray.h 💖

okay so bestie, welcome to the <rte_fbarray.h> glow-up ✨ this is a manual page, it lives in section 3, and it's all about a file-backed shared indexed array for DPDK. yes that's a mouthful. no we're not skipping a single detail. let's get into it 🫶

🌸 SYNOPSIS 🌸

#include <stdio.h>
#include <rte_rwlock.h>

✨ Functions

int rte_fbarray_init (struct rte_fbarray *arr, const char *name, unsigned int len, unsigned int elt_sz)
int rte_fbarray_attach (struct rte_fbarray *arr)
int rte_fbarray_destroy (struct rte_fbarray *arr)
int rte_fbarray_detach (struct rte_fbarray *arr)
void * rte_fbarray_get (const struct rte_fbarray *arr, unsigned int idx)
int rte_fbarray_find_idx (const struct rte_fbarray *arr, const void *elt)
int rte_fbarray_set_used (struct rte_fbarray *arr, unsigned int idx)
int rte_fbarray_set_free (struct rte_fbarray *arr, unsigned int idx)
int rte_fbarray_is_used (struct rte_fbarray *arr, unsigned int idx)
int rte_fbarray_find_next_free (struct rte_fbarray *arr, unsigned int start)
int rte_fbarray_find_next_used (struct rte_fbarray *arr, unsigned int start)
int rte_fbarray_find_next_n_free (struct rte_fbarray *arr, unsigned int start, unsigned int n)
int rte_fbarray_find_next_n_used (struct rte_fbarray *arr, unsigned int start, unsigned int n)
int rte_fbarray_find_contig_free (struct rte_fbarray *arr, unsigned int start)
int rte_fbarray_find_contig_used (struct rte_fbarray *arr, unsigned int start)
int rte_fbarray_find_prev_free (struct rte_fbarray *arr, unsigned int start)
int rte_fbarray_find_prev_used (struct rte_fbarray *arr, unsigned int start)
int rte_fbarray_find_prev_n_free (struct rte_fbarray *arr, unsigned int start, unsigned int n)
int rte_fbarray_find_prev_n_used (struct rte_fbarray *arr, unsigned int start, unsigned int n)
int rte_fbarray_find_rev_contig_free (struct rte_fbarray *arr, unsigned int start)
int rte_fbarray_find_rev_contig_used (struct rte_fbarray *arr, unsigned int start)
int rte_fbarray_find_biggest_free (struct rte_fbarray *arr, unsigned int start)
int rte_fbarray_find_biggest_used (struct rte_fbarray *arr, unsigned int start)
int rte_fbarray_find_rev_biggest_free (struct rte_fbarray *arr, unsigned int start)
int rte_fbarray_find_rev_biggest_used (struct rte_fbarray *arr, unsigned int start)
void rte_fbarray_dump_metadata (struct rte_fbarray *arr, FILE *f)

🦋 Detailed Description 🦋

File-backed shared indexed array for DPDK. 💅 that's the whole vibe. it's an array, it's indexed, it's backed by a file, and it's shared. iconic behavior fr fr.

the basic workflow, bestie 👑

this is the expected flow and honestly it's giving main character energy:

  1. allocate the array, either with rte_fbarray_init() or with rte_fbarray_attach() — which one depends on whether it's shared between multiple DPDK processes or not 🤔
  2. find free spots using rte_fbarray_find_next_free()
  3. get a pointer to the data in that free spot using rte_fbarray_get(), then copy your data into the pointer (element size is fixed, no cap 🧢)
  4. mark the entry as used using rte_fbarray_set_used()

⚠️ the "who gets affected" lore

calls to rte_fbarray_init() and rte_fbarray_destroy() will have consequences for all processes, while calls to rte_fbarray_attach() and rte_fbarray_detach() will only have consequences within a single process.

so like — it is safe to call rte_fbarray_attach() or rte_fbarray_detach() while another process is using rte_fbarray, provided no other thread within the same process will try to use rte_fbarray before attaching or after detaching. read that twice, bestie, it's a whole condition.

and it is not safe to call rte_fbarray_init() or rte_fbarray_destroy() while another thread or another process is using rte_fbarray. like. do not do that. that's the danger zone 💀

Definition in file rte_fbarray.h.

💖 Function Documentation 💖

int rte_fbarray_init (struct rte_fbarray * arr, const char * name, unsigned int len, unsigned int elt_sz)

Set up rte_fbarray structure and allocate underlying resources. ✨

call this function to correctly set up rte_fbarray and allocate the underlying files that will be backing the data in the current process. lowkey important: in order to use and share rte_fbarray between multiple processes, the data pointed to by the arr pointer must itself be allocated in shared memory. don't forget that part 🫶

Parameters

  • arr — valid pointer to allocated rte_fbarray structure.
  • name — unique name to be assigned to this array.
  • len — number of elements initially available in the array.
  • elt_sz — size of each element.

Returns

  • 0 on success 🎉
  • -1 on failure, with rte_errno indicating reason for failure 😭

int rte_fbarray_attach (struct rte_fbarray * arr)

Attach to a file backing an already allocated and correctly set up rte_fbarray structure. 🧚

call this function to attach to the file that will be backing the data in the current process. the structure must have been previously correctly set up with a call to rte_fbarray_init(). calls to rte_fbarray_attach() are usually meant to be performed in a multiprocessing scenario, with the data pointed to by the arr pointer allocated in shared memory. multiprocessing moment fr fr 🔥

Parameters

  • arr — valid pointer to allocated and correctly set up rte_fbarray structure.

Returns

  • 0 on success 🎉
  • -1 on failure, with rte_errno indicating reason for failure 😭

int rte_fbarray_destroy (struct rte_fbarray * arr)

Deallocate resources for an already allocated and correctly set up rte_fbarray structure, and remove the underlying file. 🫣

call this function to deallocate all resources associated with an rte_fbarray structure within the current process. it will also zero-fill the data pointed to by the arr pointer and remove the underlying file backing the data, so it is expected that by the time this function is called, all other processes have detached from this rte_fbarray. like, all of them. everybody out. periodt 💅

Parameters

  • arr — valid pointer to allocated and correctly set up rte_fbarray structure.

Returns

  • 0 on success 🎉
  • -1 on failure, with rte_errno indicating reason for failure 😭

int rte_fbarray_detach (struct rte_fbarray * arr)

Deallocate resources for an already allocated and correctly set up rte_fbarray structure. 🌈

call this function to deallocate all resources associated with an rte_fbarray structure within the current process. (note the difference from rte_fbarray_destroy() — this one is just you, bestie, not the whole group chat 💖)

Parameters

  • arr — valid pointer to allocated and correctly set up rte_fbarray structure.

Returns

  • 0 on success 🎉
  • -1 on failure, with rte_errno indicating reason for failure 😭

void * rte_fbarray_get (const struct rte_fbarray * arr, unsigned int idx)

Get pointer to element residing at specified index. 🎀

Parameters

  • arr — valid pointer to allocated and correctly set up rte_fbarray structure.
  • idx — index of an element to get a pointer to.

Returns

  • non-NULL pointer on success 💅
  • NULL on failure, with rte_errno indicating reason for failure 😭

int rte_fbarray_find_idx (const struct rte_fbarray * arr, const void * elt)

Find index of a specified element within the array. 🔍

Parameters

  • arr — valid pointer to allocated and correctly set up rte_fbarray structure.
  • elt — pointer to element to find index to.

Returns

  • non-negative integer on success ✨
  • -1 on failure, with rte_errno indicating reason for failure 😭

int rte_fbarray_set_used (struct rte_fbarray * arr, unsigned int idx)

Mark specified element as used. ✅

Parameters

  • arr — valid pointer to allocated and correctly set up rte_fbarray structure.
  • idx — element index to mark as used.

Returns

  • 0 on success 🎉
  • -1 on failure, with rte_errno indicating reason for failure 😭

int rte_fbarray_set_free (struct rte_fbarray * arr, unsigned int idx)

Mark specified element as free. 🕊️

Parameters

  • arr — valid pointer to allocated and correctly set up rte_fbarray structure.
  • idx — element index to mark as free.

Returns

  • 0 on success 🎉
  • -1 on failure, with rte_errno indicating reason for failure 😭

int rte_fbarray_is_used (struct rte_fbarray * arr, unsigned int idx)

Check whether element at specified index is marked as used. 👀 vibe check on that index

Parameters

  • arr — valid pointer to allocated and correctly set up rte_fbarray structure.
  • idx — element index to check as used.

Returns

  • 1 if element is used
  • 0 if element is unused
  • -1 on failure, with rte_errno indicating reason for failure 😭

int rte_fbarray_find_next_free (struct rte_fbarray * arr, unsigned int start)

Find index of next free element, starting at specified index. 🌸

Parameters

  • arr — valid pointer to allocated and correctly set up rte_fbarray structure.
  • start — element index to start search from.

Returns

  • non-negative integer on success ✨
  • -1 on failure, with rte_errno indicating reason for failure 😭

int rte_fbarray_find_next_used (struct rte_fbarray * arr, unsigned int start)

Find index of next used element, starting at specified index. 🌸

Parameters

  • arr — valid pointer to allocated and correctly set up rte_fbarray structure.
  • start — element index to start search from.

Returns

  • non-negative integer on success ✨
  • -1 on failure, with rte_errno indicating reason for failure 😭

int rte_fbarray_find_next_n_free (struct rte_fbarray * arr, unsigned int start, unsigned int n)

Find index of next chunk of n free elements, starting at specified index. 🍓

Parameters

  • arr — valid pointer to allocated and correctly set up rte_fbarray structure.
  • start — element index to start search from.
  • n — number of free elements to look for.

Returns

  • non-negative integer on success ✨
  • -1 on failure, with rte_errno indicating reason for failure 😭

int rte_fbarray_find_next_n_used (struct rte_fbarray * arr, unsigned int start, unsigned int n)

Find index of next chunk of n used elements, starting at specified index. 🍓

Parameters

  • arr — valid pointer to allocated and correctly set up rte_fbarray structure.
  • start — element index to start search from.
  • n — number of used elements to look for.

Returns

  • non-negative integer on success ✨
  • -1 on failure, with rte_errno indicating reason for failure 😭

int rte_fbarray_find_contig_free (struct rte_fbarray * arr, unsigned int start)

Find how many more free entries there are, starting at specified index. 🧮

Parameters

  • arr — valid pointer to allocated and correctly set up rte_fbarray structure.
  • start — element index to start search from.

Returns

  • non-negative integer on success ✨
  • -1 on failure, with rte_errno indicating reason for failure 😭

int rte_fbarray_find_contig_used (struct rte_fbarray * arr, unsigned int start)

Find how many more used entries there are, starting at specified index. 🧮

Parameters

  • arr — valid pointer to allocated and correctly set up rte_fbarray structure.
  • start — element index to start search from.

Returns

  • non-negative integer on success ✨
  • -1 on failure, with rte_errno indicating reason for failure 😭

and that's only part 1, bestie — there's more coming, don't go anywhere 🫶

🌸 rte_fbarray_find_prev_free 🌸

int rte_fbarray_find_prev_free (struct rte_fbarray * arr, unsigned int start)

okay so bestie, imagine you're scrolling backwards through the array — this one finds the index of the previous free element, starting at the index you give it. Going up, not down. 💅

Parameters

  • arr — valid pointer to an allocated and correctly set up rte_fbarray structure. (yes it needs to be set up properly, we've been over this 🫶)
  • start — element index to start the search from.

Returns

  • non-negative integer on success ✨
  • -1 on failure, with rte_errno telling you why it failed. 😭

🦋 rte_fbarray_find_prev_used 🦋

int rte_fbarray_find_prev_used (struct rte_fbarray * arr, unsigned int start)

Same energy as above but for used elements — finds the index of the previous used one, starting at the index you pass in. 🎀

Parameters

  • arr — valid pointer to an allocated and correctly set up rte_fbarray structure.
  • start — element index to start the search from.

Returns

  • non-negative integer on success ✨
  • -1 on failure, with rte_errno indicating the reason for failure. 💀

💖 rte_fbarray_find_prev_n_free 💖

int rte_fbarray_find_prev_n_free (struct rte_fbarray * arr, unsigned int start, unsigned int n)

This one is giving chunk energy: it finds the lowest start index of a chunk of n free elements, going down from the specified index. So you're not looking for one lil spot, you're looking for a whole squad of them. 👑

Parameters

  • arr — valid pointer to an allocated and correctly set up rte_fbarray structure.
  • start — element index to start the search from.
  • n — number of free elements to look for.

Returns

  • non-negative integer on success ✨
  • -1 on failure, with rte_errno indicating reason for failure. 😭

🌈 rte_fbarray_find_prev_n_used 🌈

int rte_fbarray_find_prev_n_used (struct rte_fbarray * arr, unsigned int start, unsigned int n)

Fr fr the used-version of the last one — finds the lowest start index of a chunk of n used elements, down from the specified index. 🍓

Parameters

  • arr — valid pointer to an allocated and correctly set up rte_fbarray structure.
  • start — element index to start the search from.
  • n — number of used elements to look for.

Returns

  • non-negative integer on success ✨
  • -1 on failure, with rte_errno indicating reason for failure. 💀

🧚 rte_fbarray_find_rev_contig_free 🧚

int rte_fbarray_find_rev_contig_free (struct rte_fbarray * arr, unsigned int start)

Find how many more free entries there are before the specified index — literally like rte_fbarray_find_contig_free but going in reverse. Rewind-core. ⏪

Parameters

  • arr — valid pointer to an allocated and correctly set up rte_fbarray structure.
  • start — element index to start the search from.

Returns

  • non-negative integer on success ✨
  • -1 on failure, with rte_errno indicating reason for failure. 😭

💜 rte_fbarray_find_rev_contig_used 💜

int rte_fbarray_find_rev_contig_used (struct rte_fbarray * arr, unsigned int start)

Find how many more used entries there are before the specified index — like rte_fbarray_find_contig_used but going in reverse. Same vibe, opposite direction. 🔄

Parameters

  • arr — valid pointer to an allocated and correctly set up rte_fbarray structure.
  • start — element index to start the search from.

Returns

  • non-negative integer on success ✨
  • -1 on failure, with rte_errno indicating reason for failure. 💀

✨ rte_fbarray_find_biggest_free ✨

int rte_fbarray_find_biggest_free (struct rte_fbarray * arr, unsigned int start)

Not me finding the biggest chunk of free elements for you 😌 — it returns the index of the biggest chunk of free elements, starting at the specified index. Main character chunk energy only.

Parameters

  • arr — valid pointer to an allocated and correctly set up rte_fbarray structure.
  • start — element index to start the search from.

Returns

  • non-negative integer on success ✨
  • -1 on failure, with rte_errno indicating reason for failure. 😭

🔥 rte_fbarray_find_biggest_used 🔥

int rte_fbarray_find_biggest_used (struct rte_fbarray * arr, unsigned int start)

Find the index of the biggest chunk of used elements, starting at the specified index. Yup, biggest, not just any. No half-measures here bestie. 💅

Parameters

  • arr — valid pointer to an allocated and correctly set up rte_fbarray structure.
  • start — element index to start the search from.

Returns

  • non-negative integer on success ✨
  • -1 on failure, with rte_errno indicating reason for failure. 💀

🎀 rte_fbarray_find_rev_biggest_free 🎀

int rte_fbarray_find_rev_biggest_free (struct rte_fbarray * arr, unsigned int start)

Find the index of the biggest chunk of free elements before a specified index — like rte_fbarray_find_biggest_free, but going in reverse. 🫶

Parameters

  • arr — valid pointer to an allocated and correctly set up rte_fbarray structure.
  • start — element index to start the search from.

Returns

  • non-negative integer on success ✨
  • -1 on failure, with rte_errno indicating reason for failure. 😭

🦋 rte_fbarray_find_rev_biggest_used 🦋

int rte_fbarray_find_rev_biggest_used (struct rte_fbarray * arr, unsigned int start)

Find the index of the biggest chunk of used elements before a specified index — like rte_fbarray_find_biggest_used, but going in reverse. Backwards but make it iconic. 🌀

Parameters

  • arr — valid pointer to an allocated and correctly set up rte_fbarray structure.
  • start — element index to start the search from.

Returns

  • non-negative integer on success ✨
  • -1 on failure, with rte_errno indicating reason for failure. 💀

📋 rte_fbarray_dump_metadata 📋

void rte_fbarray_dump_metadata (struct rte_fbarray * arr, FILE * f)

Dump rte_fbarray metadata. Just... spill all the tea into a file. 🍵 (It returns nothing — void — it just does the thing.)

Parameters

  • arr — valid pointer to an allocated and correctly set up rte_fbarray structure.
  • f — file object to dump the information into.

👑 Author 👑

Generated automatically by Doxygen for DPDK from the source code. (Not a human, not a bestie, just Doxygen doing its lil automated thing. Respect the machine. 🤖✨)

okay that's the whole thing, we ate and left no crumbs 💅 this was DPDK, Version 25.11.3, and you've been reading rte_fbarray.h(3) — go forth and free your elements, queen. 🎀🌈💖

📦 where this page comes from