DPDK  24.11.0-rc1
Functions
rte_ring_elem.h File Reference
#include <rte_ring_core.h>
#include <rte_ring_elem_pvt.h>
#include <rte_ring_hts.h>
#include <rte_ring_rts.h>
#include <rte_ring_peek.h>
#include <rte_ring_peek_zc.h>
#include <rte_ring.h>

Go to the source code of this file.

Functions

ssize_t rte_ring_get_memsize_elem (unsigned int esize, unsigned int count)
 
struct rte_ringrte_ring_create_elem (const char *name, unsigned int esize, unsigned int count, int socket_id, unsigned int flags)
 
static __rte_always_inline unsigned int rte_ring_mp_enqueue_bulk_elem (struct rte_ring *r, const void *obj_table, unsigned int esize, unsigned int n, unsigned int *free_space)
 
static __rte_always_inline unsigned int rte_ring_sp_enqueue_bulk_elem (struct rte_ring *r, const void *obj_table, unsigned int esize, unsigned int n, unsigned int *free_space)
 
static __rte_always_inline unsigned int rte_ring_enqueue_bulk_elem (struct rte_ring *r, const void *obj_table, unsigned int esize, unsigned int n, unsigned int *free_space)
 
static __rte_always_inline int rte_ring_mp_enqueue_elem (struct rte_ring *r, void *obj, unsigned int esize)
 
static __rte_always_inline int rte_ring_sp_enqueue_elem (struct rte_ring *r, void *obj, unsigned int esize)
 
static __rte_always_inline int rte_ring_enqueue_elem (struct rte_ring *r, void *obj, unsigned int esize)
 
static __rte_always_inline unsigned int rte_ring_mc_dequeue_bulk_elem (struct rte_ring *r, void *obj_table, unsigned int esize, unsigned int n, unsigned int *available)
 
static __rte_always_inline unsigned int rte_ring_sc_dequeue_bulk_elem (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_elem (struct rte_ring *r, void *obj_table, unsigned int esize, unsigned int n, unsigned int *available)
 
static __rte_always_inline int rte_ring_mc_dequeue_elem (struct rte_ring *r, void *obj_p, unsigned int esize)
 
static __rte_always_inline int rte_ring_sc_dequeue_elem (struct rte_ring *r, void *obj_p, unsigned int esize)
 
static __rte_always_inline int rte_ring_dequeue_elem (struct rte_ring *r, void *obj_p, unsigned int esize)
 
static __rte_always_inline unsigned int rte_ring_mp_enqueue_burst_elem (struct rte_ring *r, const void *obj_table, unsigned int esize, unsigned int n, unsigned int *free_space)
 
static __rte_always_inline unsigned int rte_ring_sp_enqueue_burst_elem (struct rte_ring *r, const void *obj_table, unsigned int esize, unsigned int n, unsigned int *free_space)
 
static __rte_always_inline unsigned int rte_ring_enqueue_burst_elem (struct rte_ring *r, const void *obj_table, unsigned int esize, unsigned int n, unsigned int *free_space)
 
static __rte_always_inline unsigned int rte_ring_mc_dequeue_burst_elem (struct rte_ring *r, void *obj_table, unsigned int esize, unsigned int n, unsigned int *available)
 
static __rte_always_inline unsigned int rte_ring_sc_dequeue_burst_elem (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_elem (struct rte_ring *r, void *obj_table, unsigned int esize, unsigned int n, unsigned int *available)
 

Detailed Description

RTE Ring with user defined element size

Definition in file rte_ring_elem.h.

Function Documentation

◆ rte_ring_get_memsize_elem()

ssize_t rte_ring_get_memsize_elem ( unsigned int  esize,
unsigned int  count 
)

Calculate the memory size needed for a ring with given element size

This function returns the number of bytes needed for a ring, given the number of elements in it and the size of the element. This value is the sum of the size of the structure rte_ring and the size of the memory needed for storing the elements. The value is aligned to a cache line size.

Parameters
esizeThe size of ring element, in bytes. It must be a multiple of 4.
countThe number of elements in the ring (must be a power of 2).
Returns
  • The memory size needed for the ring on success.
  • -EINVAL - esize is not a multiple of 4 or count provided is not a power of 2.

◆ rte_ring_create_elem()

struct rte_ring* rte_ring_create_elem ( const char *  name,
unsigned int  esize,
unsigned int  count,
int  socket_id,
unsigned int  flags 
)

Create a new ring named name that stores elements with given size.

This function uses memzone_reserve() to allocate memory. Then it calls rte_ring_init() to initialize an empty ring.

The new ring size is set to count, which must be a power of two. Water marking is disabled by default. The real usable ring size is count-1 instead of count to differentiate a full ring from an empty ring.

The ring is added in RTE_TAILQ_RING list.

Parameters
nameThe name of the ring.
esizeThe size of ring element, in bytes. It must be a multiple of 4.
countThe number of elements in the ring (must be a power of 2).
socket_idThe 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.
flagsAn OR of the following:
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
  • EINVAL - esize is not a multiple of 4 or 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

◆ rte_ring_mp_enqueue_bulk_elem()

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

Enqueue several objects on the ring (multi-producers safe).

This function uses a "compare and set" instruction to move the producer index atomically.

Parameters
rA pointer to the ring structure.
obj_tableA pointer to a table of objects.
esizeThe 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.
nThe number of objects to add in the ring from the obj_table.
free_spaceif non-NULL, returns the amount of space in the ring after the enqueue operation has finished.
Returns
The number of objects enqueued, either 0 or n

Definition at line 127 of file rte_ring_elem.h.

◆ rte_ring_sp_enqueue_bulk_elem()

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

Enqueue several objects on a ring

Warning
This API is NOT multi-producers safe
Parameters
rA pointer to the ring structure.
obj_tableA pointer to a table of objects.
esizeThe 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.
nThe number of objects to add in the ring from the obj_table.
free_spaceif non-NULL, returns the amount of space in the ring after the enqueue operation has finished.
Returns
The number of objects enqueued, either 0 or n

Definition at line 156 of file rte_ring_elem.h.

◆ rte_ring_enqueue_bulk_elem()

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

Enqueue several objects on a ring.

This function calls the multi-producer or the single-producer version depending on the default behavior that was specified at ring creation time (see flags).

Parameters
rA pointer to the ring structure.
obj_tableA pointer to a table of objects.
esizeThe 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.
nThe number of objects to add in the ring from the obj_table.
free_spaceif non-NULL, returns the amount of space in the ring after the enqueue operation has finished.
Returns
The number of objects enqueued, either 0 or n

Definition at line 190 of file rte_ring_elem.h.

◆ rte_ring_mp_enqueue_elem()

static __rte_always_inline int rte_ring_mp_enqueue_elem ( struct rte_ring r,
void *  obj,
unsigned int  esize 
)
static

Enqueue one object on a ring (multi-producers safe).

This function uses a "compare and set" instruction to move the producer index atomically.

Parameters
rA pointer to the ring structure.
objA pointer to the object to be added.
esizeThe 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.
Returns
  • 0: Success; objects enqueued.
  • -ENOBUFS: Not enough room in the ring to enqueue; no object is enqueued.

Definition at line 234 of file rte_ring_elem.h.

◆ rte_ring_sp_enqueue_elem()

static __rte_always_inline int rte_ring_sp_enqueue_elem ( struct rte_ring r,
void *  obj,
unsigned int  esize 
)
static

Enqueue one object on a ring

Warning
This API is NOT multi-producers safe
Parameters
rA pointer to the ring structure.
objA pointer to the object to be added.
esizeThe 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.
Returns
  • 0: Success; objects enqueued.
  • -ENOBUFS: Not enough room in the ring to enqueue; no object is enqueued.

Definition at line 258 of file rte_ring_elem.h.

◆ rte_ring_enqueue_elem()

static __rte_always_inline int rte_ring_enqueue_elem ( struct rte_ring r,
void *  obj,
unsigned int  esize 
)
static

Enqueue one object on a ring.

This function calls the multi-producer or the single-producer version, depending on the default behaviour that was specified at ring creation time (see flags).

Parameters
rA pointer to the ring structure.
objA pointer to the object to be added.
esizeThe 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.
Returns
  • 0: Success; objects enqueued.
  • -ENOBUFS: Not enough room in the ring to enqueue; no object is enqueued.

Definition at line 284 of file rte_ring_elem.h.

◆ rte_ring_mc_dequeue_bulk_elem()

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

Dequeue several objects from a ring (multi-consumers safe).

This function uses a "compare and set" instruction to move the consumer index atomically.

Parameters
rA pointer to the ring structure.
obj_tableA pointer to a table of objects that will be filled.
esizeThe 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.
nThe number of objects to dequeue from the ring to the obj_table.
availableIf non-NULL, returns the number of remaining ring entries after the dequeue has finished.
Returns
The number of objects dequeued, either 0 or n

Definition at line 313 of file rte_ring_elem.h.

◆ rte_ring_sc_dequeue_bulk_elem()

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

Dequeue several objects from a ring (NOT multi-consumers safe).

Parameters
rA pointer to the ring structure.
obj_tableA pointer to a table of objects that will be filled.
esizeThe 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.
nThe number of objects to dequeue from the ring to the obj_table, must be strictly positive.
availableIf non-NULL, returns the number of remaining ring entries after the dequeue has finished.
Returns
The number of objects dequeued, either 0 or n

Definition at line 341 of file rte_ring_elem.h.

◆ rte_ring_dequeue_bulk_elem()

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

Dequeue several objects from a ring.

This function calls the multi-consumers or the single-consumer version, depending on the default behaviour that was specified at ring creation time (see flags).

Parameters
rA pointer to the ring structure.
obj_tableA pointer to a table of objects that will be filled.
esizeThe 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.
nThe number of objects to dequeue from the ring to the obj_table.
availableIf non-NULL, returns the number of remaining ring entries after the dequeue has finished.
Returns
The number of objects dequeued, either 0 or n

Definition at line 372 of file rte_ring_elem.h.

◆ rte_ring_mc_dequeue_elem()

static __rte_always_inline int rte_ring_mc_dequeue_elem ( struct rte_ring r,
void *  obj_p,
unsigned int  esize 
)
static

Dequeue one object from a ring (multi-consumers safe).

This function uses a "compare and set" instruction to move the consumer index atomically.

Parameters
rA pointer to the ring structure.
obj_pA pointer to the object that will be filled.
esizeThe 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.
Returns
  • 0: Success; objects dequeued.
  • -ENOENT: Not enough entries in the ring to dequeue; no object is dequeued.

Definition at line 417 of file rte_ring_elem.h.

◆ rte_ring_sc_dequeue_elem()

static __rte_always_inline int rte_ring_sc_dequeue_elem ( struct rte_ring r,
void *  obj_p,
unsigned int  esize 
)
static

Dequeue one object from a ring (NOT multi-consumers safe).

Parameters
rA pointer to the ring structure.
obj_pA pointer to the object that will be filled.
esizeThe 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.
Returns
  • 0: Success; objects dequeued.
  • -ENOENT: Not enough entries in the ring to dequeue, no object is dequeued.

Definition at line 441 of file rte_ring_elem.h.

◆ rte_ring_dequeue_elem()

static __rte_always_inline int rte_ring_dequeue_elem ( struct rte_ring r,
void *  obj_p,
unsigned int  esize 
)
static

Dequeue one object from a ring.

This function calls the multi-consumers or the single-consumer version depending on the default behaviour that was specified at ring creation time (see flags).

Parameters
rA pointer to the ring structure.
obj_pA pointer to the object that will be filled.
esizeThe 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.
Returns
  • 0: Success, objects dequeued.
  • -ENOENT: Not enough entries in the ring to dequeue, no object is dequeued.

Definition at line 469 of file rte_ring_elem.h.

◆ rte_ring_mp_enqueue_burst_elem()

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

Enqueue several objects on the ring (multi-producers safe).

This function uses a "compare and set" instruction to move the producer index atomically.

Parameters
rA pointer to the ring structure.
obj_tableA pointer to a table of objects.
esizeThe 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.
nThe number of objects to add in the ring from the obj_table.
free_spaceif non-NULL, returns the amount of space in the ring after the enqueue operation has finished.
Returns
  • n: Actual number of objects enqueued.

Definition at line 498 of file rte_ring_elem.h.

◆ rte_ring_sp_enqueue_burst_elem()

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

Enqueue several objects on a ring

Warning
This API is NOT multi-producers safe
Parameters
rA pointer to the ring structure.
obj_tableA pointer to a table of objects.
esizeThe 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.
nThe number of objects to add in the ring from the obj_table.
free_spaceif non-NULL, returns the amount of space in the ring after the enqueue operation has finished.
Returns
  • n: Actual number of objects enqueued.

Definition at line 527 of file rte_ring_elem.h.

◆ rte_ring_enqueue_burst_elem()

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

Enqueue several objects on a ring.

This function calls the multi-producer or the single-producer version depending on the default behavior that was specified at ring creation time (see flags).

Parameters
rA pointer to the ring structure.
obj_tableA pointer to a table of objects.
esizeThe 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.
nThe number of objects to add in the ring from the obj_table.
free_spaceif non-NULL, returns the amount of space in the ring after the enqueue operation has finished.
Returns
  • n: Actual number of objects enqueued.

Definition at line 558 of file rte_ring_elem.h.

◆ rte_ring_mc_dequeue_burst_elem()

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

Dequeue several objects from a ring (multi-consumers safe). When the request objects are more than the available objects, only dequeue the actual number of objects

This function uses a "compare and set" instruction to move the consumer index atomically.

Parameters
rA pointer to the ring structure.
obj_tableA pointer to a table of objects that will be filled.
esizeThe 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.
nThe number of objects to dequeue from the ring to the obj_table.
availableIf non-NULL, returns the number of remaining ring entries after the dequeue has finished.
Returns
  • n: Actual number of objects dequeued, 0 if ring is empty

Definition at line 608 of file rte_ring_elem.h.

◆ rte_ring_sc_dequeue_burst_elem()

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

Dequeue several objects from a ring (NOT multi-consumers safe).When the request objects are more than the available objects, only dequeue the actual number of objects

Parameters
rA pointer to the ring structure.
obj_tableA pointer to a table of objects that will be filled.
esizeThe 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.
nThe number of objects to dequeue from the ring to the obj_table.
availableIf non-NULL, returns the number of remaining ring entries after the dequeue has finished.
Returns
  • n: Actual number of objects dequeued, 0 if ring is empty

Definition at line 637 of file rte_ring_elem.h.

◆ rte_ring_dequeue_burst_elem()

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

Dequeue multiple objects from a ring up to a maximum number.

This function calls the multi-consumers or the single-consumer version, depending on the default behaviour that was specified at ring creation time (see flags).

Parameters
rA pointer to the ring structure.
obj_tableA pointer to a table of objects that will be filled.
esizeThe 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.
nThe number of objects to dequeue from the ring to the obj_table.
availableIf non-NULL, returns the number of remaining ring entries after the dequeue has finished.
Returns
  • Number of objects dequeued

Definition at line 668 of file rte_ring_elem.h.