rte_event_ring.h(3)

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

🌈 NAME 🌈

rte_event_ring.h — bestie, it's the event ring header, and it's iconic 💅 this is page rte_event_ring.h(3) from the Library Functions Manual, and we're gonna go through every single crumb of it, no cap.

✨ SYNOPSIS ✨

#include <stdint.h>
#include <rte_common.h>
#include <rte_ring.h>
#include <rte_ring_elem.h>
#include 'rte_eventdev.h'
okay so yes, that last include is literally wrapped in single quotes, not angle brackets. That's not me being quirky, that's what the page says. Copy it exactly fr fr 🫶

🧚 Data Structures

  • struct rte_event_ring — the main character itself 🎀

🦋 Functions

static __rte_always_inline unsigned int rte_event_ring_count (const
    struct rte_event_ring *r)
static __rte_always_inline unsigned int rte_event_ring_free_count (const
    struct rte_event_ring *r)
static __rte_always_inline unsigned int rte_event_ring_enqueue_bulk
    (struct rte_event_ring *r, const struct rte_event *events, unsigned
    int n, uint16_t *free_space)
static __rte_always_inline unsigned int rte_event_ring_dequeue_bulk
    (struct rte_event_ring *r, struct rte_event *events, unsigned int n,
    uint16_t *available)
static __rte_always_inline unsigned int rte_event_ring_enqueue_burst
    (struct rte_event_ring *r, const struct rte_event *events, unsigned
    int n, uint16_t *free_space)
static __rte_always_inline unsigned int rte_event_ring_dequeue_burst
    (struct rte_event_ring *r, struct rte_event *events, unsigned int n,
    uint16_t *available)
void rte_event_ring_free (struct rte_event_ring *r)
struct rte_event_ring * rte_event_ring_create (const char *name,
    unsigned int count, int socket_id, unsigned int flags) __rte_malloc
    __rte_dealloc(rte_event_ring_free
struct rte_event_ring struct rte_event_ring * rte_event_ring_lookup
    (const char *name)
static unsigned int rte_event_ring_get_size (const struct rte_event_ring
    *r)
static unsigned int rte_event_ring_get_capacity (const struct
    rte_event_ring *r)
not the __rte_dealloc(rte_event_ring_free with its little unclosed paren at the end 😭 that's verbatim from the page, leave it be bestie, it's doing its best.

💖 Detailed Description 💖

RTE Event Ring

Okay so here's the vibe: this gives you a ring implementation for passing rte_event structures from one core to another. That's the whole plot. Core-to-core event passing, slay ✨

Definition in file rte_event_ring.h.

👑 Function Documentation 👑

__rte_always_inline unsigned int rte_event_ring_count (const struct rte_event_ring * r) [static]

Returns the number of events in the ring 🎀

Parameters

  • r — pointer to the event ring

Returns

  • the number of events in the ring

Definition at line 50 of file rte_event_ring.h.

__rte_always_inline unsigned int rte_event_ring_free_count (const struct rte_event_ring * r) [static]

Returns the amount of free space in the ring 🦋

Parameters

  • r — pointer to the event ring

Returns

  • the number of free slots in the ring, i.e. the number of events that can be successfully enqueued before dequeue must be called

Definition at line 65 of file rte_event_ring.h.

__rte_always_inline unsigned int rte_event_ring_enqueue_bulk (struct rte_event_ring * r, const struct rte_event * events, unsigned int n, uint16_t * free_space) [static]

Enqueue several objects on a ring.

The way this one works: it calls the <highlight>multi-producer</highlight> or the <highlight>single-producer</highlight> version depending on the default behavior that was specified at ring creation time (see flags). So it's lowkey just doing what you told it to at birth 🍼

Parameters

  • r — pointer to the event ring
  • events — pointer to an array of struct rte_event objects
  • n — The number of events in the array to enqueue
  • free_space — if non-NULL, returns the amount of space in the ring after the enqueue operation has completed

Returns

  • the number of objects enqueued, either 0 or n

Definition at line 91 of file rte_event_ring.h.

__rte_always_inline unsigned int rte_event_ring_dequeue_bulk (struct rte_event_ring * r, struct rte_event * events, unsigned int n, uint16_t * available) [static]

Dequeue a set of events from a ring

Note: this API does not work with pointers to events, rather it copies the events themselves to the destination events buffer. Bestie, actual events, not lil pointer crumbs. Important 💅

Parameters

  • r — pointer to the event ring
  • events — pointer to an array to hold the struct rte_event objects
  • n — number of events that can be held in the events array
  • available — if non-null, is updated to indicate the number of events remaining in the ring once the dequeue has completed

Returns

  • the number of objects dequeued, either 0 or n

Definition at line 127 of file rte_event_ring.h.

__rte_always_inline unsigned int rte_event_ring_enqueue_burst (struct rte_event_ring * r, const struct rte_event * events, unsigned int n, uint16_t * free_space) [static]

Enqueue a set of events onto a ring 🔥

Note: this API enqueues by copying the events themselves onto the ring, rather than just placing a pointer to each event onto the ring. This means that statically-allocated events can safely be enqueued by this API. So your static babies are safe, periodt 💖

Parameters

  • r — pointer to the event ring
  • events — pointer to an array of struct rte_event objects
  • n — number of events in the array to enqueue
  • free_space — if non-null, is updated to indicate the amount of free space in the ring once the enqueue has completed.

Returns

  • the number of elements, n', enqueued to the ring, 0 <= n' <= n

Definition at line 165 of file rte_event_ring.h.

__rte_always_inline unsigned int rte_event_ring_dequeue_burst (struct rte_event_ring * r, struct rte_event * events, unsigned int n, uint16_t * available) [static]

Dequeue a set of events from a ring 🦋

Note: this API does not work with pointers to events, rather it copies the events themselves to the destination events buffer. Same deal as rte_event_ring_dequeue_bulk, iykyk 🌸

Parameters

  • r — pointer to the event ring
  • events — pointer to an array to hold the struct rte_event objects
  • n — number of events that can be held in the events array
  • available — if non-null, is updated to indicate the number of events remaining in the ring once the dequeue has completed

Returns

  • the number of elements, n', dequeued from the ring, 0 <= n' <= n

Definition at line 201 of file rte_event_ring.h.

void rte_event_ring_free (struct rte_event_ring * r)

De-allocate all memory used by the ring. Cleanup era 🧹✨

Parameters

  • r — Pointer to ring to created with rte_event_ring_create(). If r is NULL, no operation is performed. So passing NULL is a lil no-op, not a crime 🫶

struct rte_event_ring * rte_event_ring_create (const char * name, unsigned int count, int socket_id, unsigned int flags)

Create an event ring structure 👑

This function allocates memory and initializes an event ring inside that memory. It's giving architect energy, building the whole thing from scratch 🎀

Parameters

  • name — name to be given to the ring
  • count — the number of elements to be stored in the ring. If the flag RING_F_EXACT_SZ is not set, this must be a power of 2, and the actual usable space in the ring will be count - 1 entries. If the flag RING_F_EXACT_SZ is set, the this can be any value up to the ring size limit - 1, and the usable space will be exactly that requested.
  • socket_id — The socket_id argument is the socket identifier in case of NUMA. The value can be SOCKET_ID_ANY if there is no NUMA constraint for the reserved zone.
  • flags — An OR of the following:
    • RING_F_SP_ENQ: If this flag is set, the default behavior when using rte_ring_enqueue() or rte_ring_enqueue_bulk() is "single-producer". Otherwise, it is "multi-producers".
    • RING_F_SC_DEQ: If this flag is set, the default behavior when using rte_ring_dequeue() or rte_ring_dequeue_bulk() is "single-consumer". Otherwise, it is "multi-consumers".
    • RING_F_EXACT_SZ: If this flag is set, the count parameter is to be taken as the exact usable size of the ring, and as such does not need to be a power of 2. The underlying ring memory should be a power-of-2 size greater than the count value.

Returns

On success, the pointer to the new allocated ring. NULL on error with rte_errno set appropriately. Possible errno values include:

  • E_RTE_NO_CONFIG — function could not get pointer to rte_config structure
  • E_RTE_SECONDARY — function was called from a secondary process instance
  • EINVAL — count provided is not a power of 2
  • ENOSPC — the maximum number of memzones has already been allocated
  • EEXIST — a memzone with the same name already exists
  • ENOMEM — no appropriate memory area found in which to create memzone
bestie if you see NULL come back, check rte_errno immediately, don't just sit there guessing 😭 the answer is right there.

struct rte_event_ring struct rte_event_ring * rte_event_ring_lookup (const char * name)

Search for an event ring based on its name 🔍

Parameters

  • name — The name of the ring.

Returns

The pointer to the ring matching the name, or NULL if not found, with rte_errno set appropriately. Possible rte_errno values include:

  • ENOENT — required entry not available to return.

unsigned int rte_event_ring_get_size (const struct rte_event_ring * r) [inline], [static]

Return the size of the event ring. 📏

Parameters

  • r — A pointer to the ring structure.

Returns

The size of the data store used by the ring. NOTE: this is not the same as the usable space in the ring. To query that use rte_ring_get_capacity().

do not, I repeat do NOT, confuse size with usable space. That's the classic blunder and it will humble you 💀 use rte_ring_get_capacity() for capacity, bestie.

Definition at line 328 of file rte_event_ring.h.

unsigned int rte_event_ring_get_capacity (const struct rte_event_ring * r) [inline], [static]

Return the number of elements which can be stored in the event ring. 🍓

Parameters

  • r — A pointer to the ring structure.

Returns

The usable size of the ring.

Definition at line 342 of file rte_event_ring.h.

🫶 Author 🫶

Generated automatically by Doxygen for DPDK from the source code.

and that's the whole page, bestie, we ate 💅✨ source is DPDK Version 25.11.3, and this was page rte_event_ring.h(3) from the Library Functions Manual — go build something iconic with it, mwah 🎀

📦 where this page comes from