DPDK  20.08.0
Functions
rte_ring_rts.h File Reference
#include <rte_ring_rts_c11_mem.h>

Go to the source code of this file.

Functions

static __rte_experimental __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_experimental __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_experimental __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_experimental __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_experimental __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_experimental __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_experimental __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_experimental __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 __rte_experimental uint32_t rte_ring_get_prod_htd_max (const struct rte_ring *r)
 
static __rte_experimental int rte_ring_set_prod_htd_max (struct rte_ring *r, uint32_t v)
 
static __rte_experimental uint32_t rte_ring_get_cons_htd_max (const struct rte_ring *r)
 
static __rte_experimental int rte_ring_set_cons_htd_max (struct rte_ring *r, uint32_t v)
 

Detailed Description

EXPERIMENTAL: this API may change without prior notice 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

static __rte_experimental __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 164 of file rte_ring_rts.h.

static __rte_experimental __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 192 of file rte_ring_rts.h.

static __rte_experimental __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 220 of file rte_ring_rts.h.

static __rte_experimental __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 250 of file rte_ring_rts.h.

static __rte_experimental __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 274 of file rte_ring_rts.h.

static __rte_experimental __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 298 of file rte_ring_rts.h.

static __rte_experimental __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 322 of file rte_ring_rts.h.

static __rte_experimental __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 348 of file rte_ring_rts.h.

static __rte_experimental 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 366 of file rte_ring_rts.h.

static __rte_experimental 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 386 of file rte_ring_rts.h.

static __rte_experimental 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 406 of file rte_ring_rts.h.

static __rte_experimental 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 426 of file rte_ring_rts.h.