DPDK  24.03.0
Functions
rte_ring_rts.h File Reference
#include <rte_ring_rts_elem_pvt.h>

Go to the source code of this file.

Functions

static __rte_always_inline unsigned int rte_ring_mp_rts_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_mc_rts_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_mp_rts_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_rts_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_mp_rts_enqueue_bulk (struct rte_ring *r, void *const *obj_table, unsigned int n, unsigned int *free_space)
 
static __rte_always_inline unsigned int rte_ring_mc_rts_dequeue_bulk (struct rte_ring *r, void **obj_table, unsigned int n, unsigned int *available)
 
static __rte_always_inline unsigned int rte_ring_mp_rts_enqueue_burst (struct rte_ring *r, void *const *obj_table, unsigned int n, unsigned int *free_space)
 
static __rte_always_inline unsigned int rte_ring_mc_rts_dequeue_burst (struct rte_ring *r, void **obj_table, unsigned int n, unsigned int *available)
 
static uint32_t rte_ring_get_prod_htd_max (const struct rte_ring *r)
 
static int rte_ring_set_prod_htd_max (struct rte_ring *r, uint32_t v)
 
static uint32_t rte_ring_get_cons_htd_max (const struct rte_ring *r)
 
static int rte_ring_set_cons_htd_max (struct rte_ring *r, uint32_t v)
 

Detailed Description

It is not recommended to include this file directly. Please include <rte_ring.h> instead.

Contains functions for Relaxed Tail Sync (RTS) ring mode. The main idea remains the same as for our original MP/MC synchronization mechanism. The main difference is that tail value is increased not by every thread that finished enqueue/dequeue, but only by the current last one doing enqueue/dequeue. That allows threads to skip spinning on tail value, leaving actual tail value change to last thread at a given instance. RTS requires 2 64-bit CAS for each enqueue(/dequeue) operation: one for head update, second for tail update. As a gain it allows thread to avoid spinning/waiting on tail value. In comparison original MP/MC algorithm requires one 32-bit CAS for head update and waiting/spinning on tail value.

Brief outline:

To avoid producer/consumer starvation:

Definition in file rte_ring_rts.h.

Function Documentation

◆ rte_ring_mp_rts_enqueue_bulk_elem()

static __rte_always_inline unsigned int rte_ring_mp_rts_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 RTS ring (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 80 of file rte_ring_rts.h.

◆ rte_ring_mc_rts_dequeue_bulk_elem()

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

Dequeue several objects from an RTS ring (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.
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 107 of file rte_ring_rts.h.

◆ rte_ring_mp_rts_enqueue_burst_elem()

static __rte_always_inline unsigned int rte_ring_mp_rts_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 RTS ring (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 134 of file rte_ring_rts.h.

◆ rte_ring_mc_rts_dequeue_burst_elem()

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

Dequeue several objects from an RTS ring (multi-consumers safe). When the requested 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 163 of file rte_ring_rts.h.

◆ rte_ring_mp_rts_enqueue_bulk()

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

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

Parameters
rA pointer to the ring structure.
obj_tableA pointer to a table of void * pointers (objects).
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 186 of file rte_ring_rts.h.

◆ rte_ring_mc_rts_dequeue_bulk()

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

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

Parameters
rA pointer to the ring structure.
obj_tableA pointer to a table of void * pointers (objects) that will be filled.
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 209 of file rte_ring_rts.h.

◆ rte_ring_mp_rts_enqueue_burst()

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

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

Parameters
rA pointer to the ring structure.
obj_tableA pointer to a table of void * pointers (objects).
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 232 of file rte_ring_rts.h.

◆ rte_ring_mc_rts_dequeue_burst()

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

Dequeue several objects from an RTS ring (multi-consumers safe). When the requested 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 void * pointers (objects) that will be filled.
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 257 of file rte_ring_rts.h.

◆ rte_ring_get_prod_htd_max()

static uint32_t rte_ring_get_prod_htd_max ( const struct rte_ring r)
inlinestatic

Return producer max Head-Tail-Distance (HTD).

Parameters
rA pointer to the ring structure.
Returns
Producer HTD value, if producer is set in appropriate sync mode, or UINT32_MAX otherwise.

Definition at line 274 of file rte_ring_rts.h.

◆ rte_ring_set_prod_htd_max()

static int rte_ring_set_prod_htd_max ( struct rte_ring r,
uint32_t  v 
)
inlinestatic

Set producer max Head-Tail-Distance (HTD). Note that producer has to use appropriate sync mode (RTS).

Parameters
rA pointer to the ring structure.
vnew HTD value to setup.
Returns
Zero on success, or negative error code otherwise.

Definition at line 293 of file rte_ring_rts.h.

◆ rte_ring_get_cons_htd_max()

static uint32_t rte_ring_get_cons_htd_max ( const struct rte_ring r)
inlinestatic

Return consumer max Head-Tail-Distance (HTD).

Parameters
rA pointer to the ring structure.
Returns
Consumer HTD value, if consumer is set in appropriate sync mode, or UINT32_MAX otherwise.

Definition at line 312 of file rte_ring_rts.h.

◆ rte_ring_set_cons_htd_max()

static int rte_ring_set_cons_htd_max ( struct rte_ring r,
uint32_t  v 
)
inlinestatic

Set consumer max Head-Tail-Distance (HTD). Note that consumer has to use appropriate sync mode (RTS).

Parameters
rA pointer to the ring structure.
vnew HTD value to setup.
Returns
Zero on success, or negative error code otherwise.

Definition at line 331 of file rte_ring_rts.h.