#include <stdint.h>
#include <sys/queue.h>
#include <errno.h>
#include <rte_common.h>
#include <rte_memory.h>
#include <rte_lcore.h>
#include <rte_atomic.h>
#include <rte_branch_prediction.h>

Data Structures
struct	rte_ring
struct	rte_ring::prod
struct	rte_ring::cons

Macros
#define	RTE_RING_NAMESIZE 32
#define	RING_F_SP_ENQ 0x0001
#define	RING_F_SC_DEQ 0x0002
#define	RTE_RING_QUOT_EXCEED (1 << 31)
#define	RTE_RING_SZ_MASK (unsigned)(0x0fffffff)

Functions
struct rte_ring *	rte_ring_create (const char *name, unsigned count, int socket_id, unsigned flags)
int	rte_ring_set_water_mark (struct rte_ring *r, unsigned count)
void	rte_ring_dump (const struct rte_ring *r)
static int	rte_ring_mp_enqueue_bulk (struct rte_ring r, void const *obj_table, unsigned n)
static int	rte_ring_sp_enqueue_bulk (struct rte_ring r, void const *obj_table, unsigned n)
static int	rte_ring_enqueue_bulk (struct rte_ring r, void const *obj_table, unsigned n)
static int	rte_ring_mp_enqueue (struct rte_ring r, void obj)
static int	rte_ring_sp_enqueue (struct rte_ring r, void obj)
static int	rte_ring_enqueue (struct rte_ring r, void obj)
static int	rte_ring_mc_dequeue_bulk (struct rte_ring r, void *obj_table, unsigned n)
static int	rte_ring_sc_dequeue_bulk (struct rte_ring r, void *obj_table, unsigned n)
static int	rte_ring_dequeue_bulk (struct rte_ring r, void *obj_table, unsigned n)
static int	rte_ring_mc_dequeue (struct rte_ring r, void *obj_p)
static int	rte_ring_sc_dequeue (struct rte_ring r, void *obj_p)
static int	rte_ring_dequeue (struct rte_ring r, void *obj_p)
static int	rte_ring_full (const struct rte_ring *r)
static int	rte_ring_empty (const struct rte_ring *r)
static unsigned	rte_ring_count (const struct rte_ring *r)
static unsigned	rte_ring_free_count (const struct rte_ring *r)
void	rte_ring_list_dump (void)
struct rte_ring *	rte_ring_lookup (const char *name)
static int	rte_ring_mp_enqueue_burst (struct rte_ring r, void const *obj_table, unsigned n)
static int	rte_ring_sp_enqueue_burst (struct rte_ring r, void const *obj_table, unsigned n)
static int	rte_ring_enqueue_burst (struct rte_ring r, void const *obj_table, unsigned n)
static int	rte_ring_mc_dequeue_burst (struct rte_ring r, void *obj_table, unsigned n)
static int	rte_ring_sc_dequeue_burst (struct rte_ring r, void *obj_table, unsigned n)
static int	rte_ring_dequeue_burst (struct rte_ring r, void *obj_table, unsigned n)

Detailed Description

RTE Ring

The Ring Manager is a fixed-size queue, implemented as a table of pointers. Head and tail pointers are modified atomically, allowing concurrent access to it. It has the following features:

FIFO (First In First Out)
Maximum size is fixed; the pointers are stored in a table.
Lockless implementation.
Multi- or single-consumer dequeue.
Multi- or single-producer enqueue.
Bulk dequeue.
Bulk enqueue.

Note: the ring implementation is not preemptable. A lcore must not be interrupted by another task that uses the same ring.

Macro Definition Documentation

#define RING_F_SC_DEQ 0x0002

The default dequeue is "single-consumer".

#define RING_F_SP_ENQ 0x0001

The default enqueue is "single-producer".

#define RTE_RING_NAMESIZE 32

The maximum length of a ring name.

#define RTE_RING_QUOT_EXCEED (1 << 31)

Quota exceed for burst ops

#define RTE_RING_SZ_MASK (unsigned)(0x0fffffff)

Ring size mask

Function Documentation

static unsigned rte_ring_count ( const struct rte_ring * r )

inlinestatic

Return the number of entries in a ring.

Parameters

r	A pointer to the ring structure.

Returns: The number of entries in the ring.

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

read

Create a new ring named name in memory.

This function uses memzone_reserve() to allocate memory. Its size is set to count, which must be a power of two. Water marking is disabled by default. Note that the real usable ring size is count-1 instead of count.

Parameters

name	The name of the ring.
count	The size of the ring (must be a power of 2).
socket_id	The 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.
flags	An OR of the following: RING_F_SP_ENQ: If this flag is set, the default behavior when using `rte_ring_enqueue()` or `rte_ring_enqueue_bulk()` is "single-producer". Otherwise, it is "multi-producers". RING_F_SC_DEQ: If this flag is set, the default behavior when using `rte_ring_dequeue()` or `rte_ring_dequeue_bulk()` is "single-consumer". Otherwise, it is "multi-consumers".

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
E_RTE_SECONDARY - function was called from a secondary process instance
E_RTE_NO_TAILQ - no tailq list could be got for the ring list
EINVAL - 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

static int rte_ring_dequeue	(	struct rte_ring *	r,
		void **	obj_p
	)

inlinestatic

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

r	A pointer to the ring structure.
obj_p	A pointer to a void * pointer (object) that will be filled.

Returns

0: Success, objects dequeued.
-ENOENT: Not enough entries in the ring to dequeue, no object is dequeued.

static int rte_ring_dequeue_bulk	(	struct rte_ring *	r,
		void **	obj_table,
		unsigned	n
	)

inlinestatic

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

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.

Returns

0: Success; objects dequeued.
-ENOENT: Not enough entries in the ring to dequeue, no object is dequeued.

static int rte_ring_dequeue_burst	(	struct rte_ring *	r,
		void **	obj_table,
		unsigned	n
	)

inlinestatic

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

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.

Returns

Number of objects dequeued, or a negative error code on error

void rte_ring_dump ( const struct rte_ring * r )

Dump the status of the ring to the console.

Parameters

r	A pointer to the ring structure.

static int rte_ring_empty ( const struct rte_ring * r )

inlinestatic

Test if a ring is empty.

Parameters

r	A pointer to the ring structure.

Returns

1: The ring is empty.
0: The ring is not empty.

static int rte_ring_enqueue	(	struct rte_ring *	r,
		void *	obj
	)

inlinestatic

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

r	A pointer to the ring structure.
obj	A pointer to the object to be added.

Returns

0: Success; objects enqueued.
-EDQUOT: Quota exceeded. The objects have been enqueued, but the high water mark is exceeded.
-ENOBUFS: Not enough room in the ring to enqueue; no object is enqueued.

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

inlinestatic

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

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.

Returns

0: Success; objects enqueued.
-EDQUOT: Quota exceeded. The objects have been enqueued, but the high water mark is exceeded.
-ENOBUFS: Not enough room in the ring to enqueue; no object is enqueued.

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

inlinestatic

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

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.

Returns

n: Actual number of objects enqueued.

static unsigned rte_ring_free_count ( const struct rte_ring * r )

inlinestatic

Return the number of free entries in a ring.

Parameters

r	A pointer to the ring structure.

Returns: The number of free entries in the ring.

static int rte_ring_full ( const struct rte_ring * r )

inlinestatic

Test if a ring is full.

Parameters

r	A pointer to the ring structure.

Returns

1: The ring is full.
0: The ring is not full.

void rte_ring_list_dump ( void )

Dump the status of all rings on the console

struct rte_ring* rte_ring_lookup ( const char * name )

read

Search a ring from its name

Parameters

name	The name of the ring.

Returns

The pointer to the ring matching the name, or NULL if not found, with rte_errno set appropriately. Possible rte_errno values include:

ENOENT - required entry not available to return.

static int rte_ring_mc_dequeue	(	struct rte_ring *	r,
		void **	obj_p
	)

inlinestatic

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

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

Parameters

r	A pointer to the ring structure.
obj_p	A pointer to a void * pointer (object) that will be filled.

Returns

0: Success; objects dequeued.
-ENOENT: Not enough entries in the ring to dequeue; no object is dequeued.

static int rte_ring_mc_dequeue_bulk	(	struct rte_ring *	r,
		void **	obj_table,
		unsigned	n
	)

inlinestatic

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

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

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.

Returns

0: Success; objects dequeued.
-ENOENT: Not enough entries in the ring to dequeue; no object is dequeued.

static int rte_ring_mc_dequeue_burst	(	struct rte_ring *	r,
		void **	obj_table,
		unsigned	n
	)

inlinestatic

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

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.

Returns

n: Actual number of objects dequeued, 0 if ring is empty

static int rte_ring_mp_enqueue	(	struct rte_ring *	r,
		void *	obj
	)

inlinestatic

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

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

Parameters

r	A pointer to the ring structure.
obj	A pointer to the object to be added.

Returns

0: Success; objects enqueued.
-EDQUOT: Quota exceeded. The objects have been enqueued, but the high water mark is exceeded.
-ENOBUFS: Not enough room in the ring to enqueue; no object is enqueued.

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

inlinestatic

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

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

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.

Returns

0: Success; objects enqueue.
-EDQUOT: Quota exceeded. The objects have been enqueued, but the high water mark is exceeded.
-ENOBUFS: Not enough room in the ring to enqueue, no object is enqueued.

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

inlinestatic

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

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

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.

Returns

n: Actual number of objects enqueued.

static int rte_ring_sc_dequeue	(	struct rte_ring *	r,
		void **	obj_p
	)

inlinestatic

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

Parameters

r	A pointer to the ring structure.
obj_p	A pointer to a void * pointer (object) that will be filled.

Returns

0: Success; objects dequeued.
-ENOENT: Not enough entries in the ring to dequeue, no object is dequeued.

static int rte_ring_sc_dequeue_bulk	(	struct rte_ring *	r,
		void **	obj_table,
		unsigned	n
	)

inlinestatic

Dequeue several objects from a ring (NOT 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, must be strictly positive.

Returns

0: Success; objects dequeued.
-ENOENT: Not enough entries in the ring to dequeue; no object is dequeued.

static int rte_ring_sc_dequeue_burst	(	struct rte_ring *	r,
		void **	obj_table,
		unsigned	n
	)

inlinestatic

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

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.

Returns

n: Actual number of objects dequeued, 0 if ring is empty

int rte_ring_set_water_mark	(	struct rte_ring *	r,
		unsigned	count
	)

Change the high water mark.

If count is 0, water marking is disabled. Otherwise, it is set to the count value. The count value must be greater than 0 and less than the ring size.

This function can be called at any time (not necessarily at initialization).

Parameters

r	A pointer to the ring structure.
count	The new water mark value.

Returns

0: Success; water mark changed.
-EINVAL: Invalid water mark value.

static int rte_ring_sp_enqueue	(	struct rte_ring *	r,
		void *	obj
	)

inlinestatic

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

Parameters

r	A pointer to the ring structure.
obj	A pointer to the object to be added.

Returns

0: Success; objects enqueued.
-EDQUOT: Quota exceeded. The objects have been enqueued, but the high water mark is exceeded.
-ENOBUFS: Not enough room in the ring to enqueue; no object is enqueued.

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

inlinestatic

Enqueue several objects on a ring (NOT 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.

Returns

0: Success; objects enqueued.
-EDQUOT: Quota exceeded. The objects have been enqueued, but the high water mark is exceeded.
-ENOBUFS: Not enough room in the ring to enqueue; no object is enqueued.

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

inlinestatic

Enqueue several objects on a ring (NOT 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.

Returns

n: Actual number of objects enqueued.

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

Function Documentation