DPDK  16.11.11
Data Structures | Macros | Functions
rte_ring.h File Reference
#include <stdio.h>
#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>
#include <rte_memzone.h>

Go to the source code of this file.

Data Structures

struct  rte_ring
 
struct  rte_ring::prod
 
struct  rte_ring::cons
 

Macros

#define RTE_RING_MZ_PREFIX   "RG_"
 
#define RTE_RING_PAUSE_REP_COUNT   0
 
#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

ssize_t rte_ring_get_memsize (unsigned count)
 
int rte_ring_init (struct rte_ring *r, const char *name, unsigned count, unsigned flags)
 
struct rte_ringrte_ring_create (const char *name, unsigned count, int socket_id, unsigned flags)
 
void rte_ring_free (struct rte_ring *r)
 
int rte_ring_set_water_mark (struct rte_ring *r, unsigned count)
 
void rte_ring_dump (FILE *f, 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 (FILE *f)
 
struct rte_ringrte_ring_lookup (const char *name)
 
static unsigned rte_ring_mp_enqueue_burst (struct rte_ring *r, void *const *obj_table, unsigned n)
 
static unsigned rte_ring_sp_enqueue_burst (struct rte_ring *r, void *const *obj_table, unsigned n)
 
static unsigned rte_ring_enqueue_burst (struct rte_ring *r, void *const *obj_table, unsigned n)
 
static unsigned rte_ring_mc_dequeue_burst (struct rte_ring *r, void **obj_table, unsigned n)
 
static unsigned rte_ring_sc_dequeue_burst (struct rte_ring *r, void **obj_table, unsigned n)
 
static unsigned 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:

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

Definition in file rte_ring.h.

Macro Definition Documentation

#define RTE_RING_MZ_PREFIX   "RG_"

The maximum length of a ring name.

Definition at line 130 of file rte_ring.h.

#define RTE_RING_PAUSE_REP_COUNT   0

Yield after pause num of times, no yield if RTE_RING_PAUSE_REP not defined.

Definition at line 136 of file rte_ring.h.

#define RING_F_SP_ENQ   0x0001
#define RING_F_SC_DEQ   0x0002
#define RTE_RING_QUOT_EXCEED   (1 << 31)

Quota exceed for burst ops

Definition at line 198 of file rte_ring.h.

#define RTE_RING_SZ_MASK   (unsigned)(0x0fffffff)

Ring size mask

Definition at line 199 of file rte_ring.h.

Function Documentation

ssize_t rte_ring_get_memsize ( unsigned  count)

Calculate the memory size needed for a ring

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

Parameters
countThe number of elements in the ring (must be a power of 2).
Returns
  • The memory size needed for the ring on success.
  • -EINVAL if count is not a power of 2.
int rte_ring_init ( struct rte_ring r,
const char *  name,
unsigned  count,
unsigned  flags 
)

Initialize a ring structure.

Initialize a ring structure in memory pointed by "r". The size of the memory area must be large enough to store the ring structure and the object table. It is advised to use rte_ring_get_memsize() to get the appropriate size.

The 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 free ring from an empty ring.

The ring is not added in RTE_TAILQ_RING global list. Indeed, the memory given by the caller may not be shareable among dpdk processes.

Parameters
rThe pointer to the ring structure followed by the objects table.
nameThe name of the ring.
countThe number of elements in the ring (must be a power of 2).
flagsAn OR of the following:
Returns
0 on success, or a negative value on error.
struct rte_ring* rte_ring_create ( const char *  name,
unsigned  count,
int  socket_id,
unsigned  flags 
)

Create a new ring named name in memory.

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 free ring from an empty ring.

The ring is added in RTE_TAILQ_RING list.

Parameters
nameThe name of the ring.
countThe size of 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
  • E_RTE_SECONDARY - function was called from a secondary process instance
  • 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
Examples:
distributor/main.c, ip_pipeline/init.c, load_balancer/init.c, multi_process/client_server_mp/mp_server/init.c, multi_process/l2fwd_fork/main.c, multi_process/simple_mp/main.c, packet_ordering/main.c, performance-thread/common/lthread_tls.c, performance-thread/l3fwd-thread/main.c, qos_sched/init.c, and quota_watermark/qw/init.c.
void rte_ring_free ( struct rte_ring r)

De-allocate all memory used by the ring.

Parameters
rRing to free
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
rA pointer to the ring structure.
countThe new water mark value.
Returns
  • 0: Success; water mark changed.
  • -EINVAL: Invalid water mark value.
Examples:
quota_watermark/qw/init.c, and quota_watermark/qwctl/commands.c.
void rte_ring_dump ( FILE *  f,
const struct rte_ring r 
)

Dump the status of the ring to a file.

Parameters
fA pointer to a file for output
rA pointer to the ring structure.
Examples:
quota_watermark/qwctl/commands.c.
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
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.
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.

Definition at line 798 of file rte_ring.h.

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
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.
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.
Examples:
load_balancer/runtime.c, and qos_sched/app_thread.c.

Definition at line 820 of file rte_ring.h.

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
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.
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.
Examples:
multi_process/client_server_mp/mp_server/main.c, and quota_watermark/qw/main.c.

Definition at line 846 of file rte_ring.h.

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
rA pointer to the ring structure.
objA 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.
Examples:
performance-thread/common/lthread_tls.c.

Definition at line 872 of file rte_ring.h.

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

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

Parameters
rA pointer to the ring structure.
objA 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.
Examples:
ip_pipeline/thread.c, and ip_pipeline/thread_fe.c.

Definition at line 891 of file rte_ring.h.

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
rA pointer to the ring structure.
objA 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.
Examples:
multi_process/l2fwd_fork/main.c, and multi_process/simple_mp/mp_commands.c.

Definition at line 914 of file rte_ring.h.

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
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.
Returns
  • 0: Success; objects dequeued.
  • -ENOENT: Not enough entries in the ring to dequeue; no object is dequeued.

Definition at line 940 of file rte_ring.h.

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
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, must be strictly positive.
Returns
  • 0: Success; objects dequeued.
  • -ENOENT: Not enough entries in the ring to dequeue; no object is dequeued.
Examples:
load_balancer/runtime.c, and qos_sched/app_thread.c.

Definition at line 961 of file rte_ring.h.

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
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.
Returns
  • 0: Success; objects dequeued.
  • -ENOENT: Not enough entries in the ring to dequeue, no object is dequeued.
Examples:
multi_process/client_server_mp/mp_client/client.c.

Definition at line 985 of file rte_ring.h.

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
rA pointer to the ring structure.
obj_pA 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.
Examples:
performance-thread/common/lthread_tls.c.

Definition at line 1009 of file rte_ring.h.

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
rA pointer to the ring structure.
obj_pA 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.
Examples:
ip_pipeline/thread.c, and ip_pipeline/thread_fe.c.

Definition at line 1027 of file rte_ring.h.

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
rA pointer to the ring structure.
obj_pA 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.
Examples:
multi_process/l2fwd_fork/main.c, and multi_process/simple_mp/main.c.

Definition at line 1049 of file rte_ring.h.

static int rte_ring_full ( const struct rte_ring r)
inlinestatic

Test if a ring is full.

Parameters
rA pointer to the ring structure.
Returns
  • 1: The ring is full.
  • 0: The ring is not full.

Definition at line 1067 of file rte_ring.h.

static int rte_ring_empty ( const struct rte_ring r)
inlinestatic

Test if a ring is empty.

Parameters
rA pointer to the ring structure.
Returns
  • 1: The ring is empty.
  • 0: The ring is not empty.
Examples:
quota_watermark/qw/main.c.

Definition at line 1084 of file rte_ring.h.

static unsigned rte_ring_count ( const struct rte_ring r)
inlinestatic

Return the number of entries in a ring.

Parameters
rA pointer to the ring structure.
Returns
The number of entries in the ring.
Examples:
multi_process/client_server_mp/mp_client/client.c, and quota_watermark/qw/main.c.

Definition at line 1100 of file rte_ring.h.

static unsigned rte_ring_free_count ( const struct rte_ring r)
inlinestatic

Return the number of free entries in a ring.

Parameters
rA pointer to the ring structure.
Returns
The number of free entries in the ring.

Definition at line 1116 of file rte_ring.h.

void rte_ring_list_dump ( FILE *  f)

Dump the status of all rings on the console

Parameters
fA pointer to a file for output
struct rte_ring* rte_ring_lookup ( const char *  name)

Search a ring from its name

Parameters
nameThe 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.
Examples:
multi_process/client_server_mp/mp_client/client.c, multi_process/l2fwd_fork/main.c, multi_process/simple_mp/main.c, qos_sched/init.c, and quota_watermark/qwctl/commands.c.
static unsigned 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
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.
Returns
  • n: Actual number of objects enqueued.

Definition at line 1159 of file rte_ring.h.

static unsigned 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
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.
Returns
  • n: Actual number of objects enqueued.
Examples:
performance-thread/l3fwd-thread/main.c.

Definition at line 1178 of file rte_ring.h.

static unsigned 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
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.
Returns
  • n: Actual number of objects enqueued.
Examples:
distributor/main.c, and packet_ordering/main.c.

Definition at line 1201 of file rte_ring.h.

static unsigned 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
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.
Returns
  • n: Actual number of objects dequeued, 0 if ring is empty

Definition at line 1228 of file rte_ring.h.

static unsigned 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
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.
Returns
  • n: Actual number of objects dequeued, 0 if ring is empty
Examples:
performance-thread/l3fwd-thread/main.c, and qos_sched/app_thread.c.

Definition at line 1248 of file rte_ring.h.

static unsigned 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
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.
Returns
  • Number of objects dequeued
Examples:
distributor/main.c, packet_ordering/main.c, and quota_watermark/qw/main.c.

Definition at line 1270 of file rte_ring.h.