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:

• introduce update counter (cnt) for both head and tail.
• increment head.cnt for each head.value update
• write head.value and head.cnt atomically (64-bit CAS)
• move tail.value ahead only when tail.cnt + 1 == head.cnt (indicating that this is the last thread updating the tail)
• increment tail.cnt when each enqueue/dequeue op finishes (no matter if tail.value going to change or not)
• write tail.value and tail.cnt atomically (64-bit CAS)

To avoid producer/consumer starvation:

• limit max allowed distance between head and tail value (HTD_MAX). I.E. thread is allowed to proceed with changing head.value, only when: head.value - tail.value <= HTD_MAX HTD_MAX is an optional parameter. With HTD_MAX == 0 we'll have fully serialized ring - i.e. only one thread at a time will be able to enqueue/dequeue to/from the ring. With HTD_MAX >= ring.capacity - no limitation. By default HTD_MAX == ring.capacity / 8.

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

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.
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 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

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

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

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.
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

• 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

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

• 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

r	A pointer to the ring structure.
obj_table	A pointer to a table of void * pointers (objects).
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 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

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 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

r	A pointer to the ring structure.
obj_table	A pointer to a table of void * pointers (objects).
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

• 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

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

• 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

r	A 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

r	A pointer to the ring structure.
v	new 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

r	A 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

r	A pointer to the ring structure.
v	new HTD value to setup.

Returns

Zero on success, or negative error code otherwise.

Definition at line 331 of file rte_ring_rts.h.