rte_ring_peek.h(3)

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

💖 rte_ring_peek.h — bestie's guide to the DPDK ring peek API 💖

okay so this is rte_ring_peek.h, a Library Functions Manual page from the DPDK crew. it's giving "let me peek at the ring without yeeting stuff out of it" energy, and honestly? iconic. periodt. 🎀

✨ SYNOPSIS ✨

first things first, the include situation:

#include <rte_ring_peek_elem_pvt.h>

🌸 Functions 🌸

no cap, here's the whole lineup of static inline cuties this header brings to the function party:

static __rte_always_inline unsigned int rte_ring_enqueue_bulk_elem_start
    (struct rte_ring *r, unsigned int n, unsigned int *free_space)

static __rte_always_inline unsigned int rte_ring_enqueue_bulk_start
    (struct rte_ring *r, unsigned int n, unsigned int *free_space)

static __rte_always_inline unsigned int
    rte_ring_enqueue_burst_elem_start (struct rte_ring *r, unsigned int
    n, unsigned int *free_space)

static __rte_always_inline unsigned int rte_ring_enqueue_burst_start
    (struct rte_ring *r, unsigned int n, unsigned int *free_space)

static __rte_always_inline void rte_ring_enqueue_elem_finish (struct
    rte_ring *r, const void *obj_table, unsigned int esize, unsigned int
    n)

static __rte_always_inline void rte_ring_enqueue_finish (struct rte_ring
    *r, void *const *obj_table, unsigned int n)

static __rte_always_inline unsigned int rte_ring_dequeue_bulk_elem_start
    (struct rte_ring *r, void *obj_table, unsigned int esize, unsigned
    int n, unsigned int *available)

static __rte_always_inline unsigned int rte_ring_dequeue_bulk_start
    (struct rte_ring *r, void **obj_table, unsigned int n, unsigned int
    *available)

static __rte_always_inline unsigned int
    rte_ring_dequeue_burst_elem_start (struct rte_ring *r, void
    *obj_table, unsigned int esize, unsigned int n, unsigned int
    *available)

static __rte_always_inline unsigned int rte_ring_dequeue_burst_start
    (struct rte_ring *r, void **obj_table, unsigned int n, unsigned int
    *available)

static __rte_always_inline void rte_ring_dequeue_elem_finish (struct
    rte_ring *r, unsigned int n)

static __rte_always_inline void rte_ring_dequeue_finish (struct rte_ring
    *r, unsigned int n)

🔥 Detailed Description 🔥

okay real talk bestie: it is NOT recommended to include this file directly. like, do not do it. the assignment is to include <rte_ring_elem.h> instead. this is the way. trust.

so here's the tea on the Ring Peek API ☕✨

the rte_ring glow-up with serialized producer/consumer (aka HTS sync mode) makes it possible to split the public enqueue/dequeue API into two phases, and that's the whole moment:

  • enqueue/dequeue start 🚀
  • enqueue/dequeue finish 🏁

and like, that split is what lets a user inspect objects sitting in the ring without removing them from it (aka the ✨ MT safe peek ✨). it's giving main character energy fr.

heads up bestie: right now this new API is only available for two sync modes: 1. Single Producer/Single Consumer (RTE_RING_SYNC_ST) 2. Serialized Producer/Serialized Consumer (RTE_RING_SYNC_MT_HTS) and it is a user responsibility to create/init the ring with the appropriate sync modes selected. you gotta do that part yourself, no one's gonna do it for you 💅

as an example, here's the vibe — reading 1 elem from the ring:

// read 1 elem from the ring:
n = rte_ring_dequeue_bulk_start(ring, &obj, 1, NULL);
if (n != 0) {
  //examine object
  if (object_examine(obj) == KEEP)
    //decided to keep it in the ring.
    rte_ring_dequeue_finish(ring, 0);
  else
    //decided to remove it from the ring.
    rte_ring_dequeue_finish(ring, n);
}
IMPORTANTLLY bestie, do not sleep on this: between start and finish none other thread can proceed with enqueue(/dequeue) operation till finish completes. it's a whole exclusive moment, okay? 🔒👑

Definition in file rte_ring_peek.h. 📄

✨ Function Documentation ✨

okay bestie, this is the part where we meet every single function one by one 🫶 they all live in the same file, rte_ring_peek.h, and yes there are a lot of them. buckle up 💅

🌸 rte_ring_enqueue_bulk_elem_start

__rte_always_inline unsigned int
rte_ring_enqueue_bulk_elem_start(struct rte_ring * r,
                                 unsigned int n,
                                 unsigned int * free_space) [static]

So like — this one starts to enqueue a bunch of objects onto the ring. But here's the thing bestie, it's giving "reservation only" energy: no actual objects get put in the queue by this function, it just reserves that ability for you. You have to call the matching enqueue_elem_finish() to actually copy the objects in and complete the enqueue operation. no finish, no objects, periodt. 😤

Parameters

  • r — a pointer to the ring structure.
  • n — the number of objects to add in the ring from the obj_table.
  • free_space — if non-NULL, returns the amount of space in the ring after the enqueue operation has finished.

Returns

The number of objects that can be enqueued, either 0 or n.

Defined at line 70 of file rte_ring_peek.h.

🌸 rte_ring_enqueue_bulk_start

__rte_always_inline unsigned int
rte_ring_enqueue_bulk_start(struct rte_ring * r,
                            unsigned int n,
                            unsigned int * free_space) [static]

Same vibe as before, but the non-elem flavor 🦋 it starts to enqueue several objects on the ring. Again — literally zero objects are put in the queue by this function, it's just reserving for you. You gotta call the appropriate enqueue_finish() to copy objects into the queue and finish the whole operation.

Parameters

  • r — a pointer to the ring structure.
  • n — the number of objects to add in the ring from the obj_table.
  • free_space — if non-NULL, returns the amount of space in the ring after the enqueue operation has finished.

Returns

The number of objects that can be enqueued, either 0 or n.

Defined at line 95 of file rte_ring_peek.h.

🌸 rte_ring_enqueue_burst_elem_start

__rte_always_inline unsigned int
rte_ring_enqueue_burst_elem_start(struct rte_ring * r,
                                  unsigned int n,
                                  unsigned int * free_space) [static]

burst era ✨ starts enqueuing several objects on the ring. And once again, no cap: this function does not put any actual objects in the queue, it just reserves the ability for you. Call the appropriate enqueue_elem_finish() to copy the objects into the queue and complete the enqueue operation.

Parameters

  • r — a pointer to the ring structure.
  • n — the number of objects to add in the ring from the obj_table.
  • free_space — if non-NULL, returns the amount of space in the ring after the enqueue operation has finished.

Returns

Actual number of objects that can be enqueued.

Defined at line 119 of file rte_ring_peek.h.

🌸 rte_ring_enqueue_burst_start

__rte_always_inline unsigned int
rte_ring_enqueue_burst_start(struct rte_ring * r,
                             unsigned int n,
                             unsigned int * free_space) [static]

the burst one, non-elem edition 💜 starts to enqueue several objects on the ring. no actual objects are put in by this function, it just reserves for user such ability — you know the drill by now. Use the appropriate enqueue_finish() to copy objects into the queue and complete the enqueue operation.

Parameters

  • r — a pointer to the ring structure.
  • n — the number of objects to add in the ring from the obj_table.
  • free_space — if non-NULL, returns the amount of space in the ring after the enqueue operation has finished.

Returns

Actual number of objects that can be enqueued.

Defined at line 144 of file rte_ring_peek.h.

🎀 rte_ring_enqueue_elem_finish

__rte_always_inline void
rte_ring_enqueue_elem_finish(struct rte_ring * r,
                             const void * obj_table,
                             unsigned int esize,
                             unsigned int n) [static]

the main character of the enqueue saga 👑 this completes the enqueueing of several objects on the ring. crucial detail bestie: the number of objects you enqueue here should not exceed the return value from the previous enqueue_start call. overshoot that and it's giving chaos, not slay. 💀

Parameters

  • r — a pointer to the ring structure.
  • obj_table — a pointer to a table of objects.
  • esize — the size of ring element, in bytes. It must be a multiple of 4. This must be the same value used while creating the ring. Otherwise the results are undefined. 😭 so please, match your values.
  • n — the number of objects to add to the ring from the obj_table.
Defined at line 167 of file rte_ring_peek.h.

🎀 rte_ring_enqueue_finish

__rte_always_inline void
rte_ring_enqueue_finish(struct rte_ring * r,
                        void *const * obj_table,
                        unsigned int n) [static]

completes the enqueueing of several objects on the ring 🫶 same rule as always: the number of objects you enqueue here should not exceed the previous enqueue_start return value.

Parameters

  • r — a pointer to the ring structure.
  • obj_table — a pointer to a table of objects.
  • n — the number of objects to add to the ring from the obj_table.
Defined at line 206 of file rte_ring_peek.h.

🦋 rte_ring_dequeue_bulk_elem_start

__rte_always_inline unsigned int
rte_ring_dequeue_bulk_elem_start(struct rte_ring * r,
                                 void * obj_table,
                                 unsigned int esize,
                                 unsigned int n,
                                 unsigned int * available) [static]

and now we flip the whole thing — dequeue time, bestie 💖 this starts to dequeue several objects from the ring. heads up: the user has to call the appropriate dequeue_finish() to complete the given dequeue operation and actually remove objects from the ring. starting isn't finishing, iykyk.

Parameters

  • r — a pointer to the ring structure.
  • obj_table — a pointer to a table of objects that will be filled.
  • esize — the size of ring element, in bytes. It must be a multiple of 4. This must be the same value used while creating the ring. Otherwise the results are undefined.
  • n — the number of objects to dequeue from the ring to the obj_table.
  • available — if non-NULL, returns the number of remaining ring entries after the dequeue has finished.

Returns

The number of objects dequeued, either 0 or n.

Defined at line 234 of file rte_ring_peek.h.

🦋 rte_ring_dequeue_bulk_start

__rte_always_inline unsigned int
rte_ring_dequeue_bulk_start(struct rte_ring * r,
                            void ** obj_table,
                            unsigned int n,
                            unsigned int * available) [static]

starts to dequeue several objects from the ring ✨ and again — you have to call the appropriate dequeue_finish() to complete this dequeue operation and actually remove the objects from the ring.

Parameters

  • r — a pointer to the ring structure.
  • obj_table — a pointer to a table of void * pointers (objects) that will be filled.
  • n — the number of objects to dequeue from the ring to the obj_table.
  • available — if non-NULL, returns the number of remaining ring entries after the dequeue has finished.

Returns

Actual number of objects dequeued.

Defined at line 259 of file rte_ring_peek.h.

🦋 rte_ring_dequeue_burst_elem_start

__rte_always_inline unsigned int
rte_ring_dequeue_burst_elem_start(struct rte_ring * r,
                                  void * obj_table,
                                  unsigned int esize,
                                  unsigned int n,
                                  unsigned int * available) [static]

burst dequeue, elem style 🌈 starts dequeuing several objects from the ring. the user has to call the appropriate dequeue_finish() to complete the dequeue operation and actually remove objects from the ring. don't leave it half done, that's not the vibe. 🙈

Parameters

  • r — a pointer to the ring structure.
  • obj_table — a pointer to a table of objects that will be filled.
  • esize — the size of ring element, in bytes. It must be a multiple of 4. This must be the same value used while creating the ring. Otherwise the results are undefined.
  • n — the number of objects to dequeue from the ring to the obj_table.
  • available — if non-NULL, returns the number of remaining ring entries after the dequeue has finished.

Returns

The actual number of objects dequeued.

Defined at line 288 of file rte_ring_peek.h.

🦋 rte_ring_dequeue_burst_start

__rte_always_inline unsigned int
rte_ring_dequeue_burst_start(struct rte_ring * r,
                             void ** obj_table,
                             unsigned int n,
                             unsigned int * available) [static]

last of the start squad 🌟 starts to dequeue several objects from the ring. you already know: user has to call the appropriate dequeue_finish() to complete the given dequeue operation and actually remove objects from the ring.

Parameters

  • r — a pointer to the ring structure.
  • obj_table — a pointer to a table of void * pointers (objects) that will be filled.
  • n — the number of objects to dequeue from the ring to the obj_table.
  • available — if non-NULL, returns the number of remaining ring entries after the dequeue has finished.

Returns

The actual number of objects dequeued.

Defined at line 313 of file rte_ring_peek.h.

💜 rte_ring_dequeue_elem_finish

__rte_always_inline void
rte_ring_dequeue_elem_finish(struct rte_ring * r,
                             unsigned int n) [static]

the closer for the elem dequeue arc 🎀 completes the dequeuing of several objects from the ring. rule of thumb: the number of objects to dequeue should not exceed the previous dequeue_start return value.

Parameters

  • r — a pointer to the ring structure.
  • n — the number of objects to remove from the ring.
Defined at line 331 of file rte_ring_peek.h.

💜 rte_ring_dequeue_finish

__rte_always_inline void
rte_ring_dequeue_finish(struct rte_ring * r,
                        unsigned int n) [static]

and that's a wrap on the functions, bestie 🌸 completes the dequeuing of several objects from the ring. same deal: the number of objects to dequeue should not exceed the previous dequeue_start return value.

Parameters

  • r — a pointer to the ring structure.
  • n — the number of objects to remove from the ring.
Defined at line 363 of file rte_ring_peek.h.

👑 Author

Generated automatically by Doxygen for DPDK from the source code.

okay that's literally the whole page 💖 you made it to the end and that's iconic behavior, no cap 🫶 this was pulled straight from DPDK Version 25.11.3, all about rte_ring_peek.h(3). go forth and peek responsibly, bestie 💅✨

📦 where this page comes from