CNDP  22.08.0
cne_ring_api.h File Reference
#include <errno.h>
#include <stdio.h>
#include <cne_common.h>

Go to the source code of this file.

Macros

#define RING_F_SP_ENQ   0x0001
 
#define RING_F_SC_DEQ   0x0002
 
#define RING_F_ALLOCATED   0x8000
 
#define RING_F_EXACT_SZ   0x0004
 
#define CNE_RING_SZ_MASK   (0x7fffffffU)
 

Functions

CNDP_API ssize_t cne_ring_get_memsize_elem (unsigned int esize, unsigned int count)
 
CNDP_API ssize_t cne_ring_get_memsize (unsigned count)
 
CNDP_API cne_ring_t * cne_ring_create (const char *name, unsigned int esize, unsigned count, unsigned flags)
 
CNDP_API cne_ring_t * cne_ring_init (void *addr, ssize_t size, const char *name, unsigned int esize, unsigned int count, unsigned int flags)
 
CNDP_API void cne_ring_free (cne_ring_t *r)
 
CNDP_API void cne_ring_dump (FILE *f, cne_ring_t *r)
 
CNDP_API void cne_ring_reset (cne_ring_t *r)
 
CNDP_API unsigned cne_ring_count (const cne_ring_t *r)
 
CNDP_API unsigned cne_ring_free_count (const cne_ring_t *r)
 
CNDP_API int cne_ring_full (const cne_ring_t *r)
 
CNDP_API int cne_ring_empty (const cne_ring_t *r)
 
CNDP_API unsigned cne_ring_get_size (const cne_ring_t *r)
 
CNDP_API unsigned cne_ring_get_capacity (const cne_ring_t *r)
 
CNDP_API const char * cne_ring_get_name (const cne_ring_t *r)
 
CNDP_API int cne_ring_get_flags (const cne_ring_t *r)
 
CNDP_API uint32_t cne_ring_get_mask (const cne_ring_t *r)
 
CNDP_API uint32_t cne_ring_get_prod_head (const cne_ring_t *r)
 
CNDP_API uint32_t cne_ring_get_prod_tail (const cne_ring_t *r)
 
CNDP_API uint32_t cne_ring_get_cons_head (const cne_ring_t *r)
 
CNDP_API uint32_t cne_ring_get_cons_tail (const cne_ring_t *r)
 
CNDP_API unsigned int cne_ring_enqueue_bulk (cne_ring_t *r, void *const *obj_table, unsigned int n, unsigned int *free_space)
 
__cne_always_inline int cne_ring_enqueue (cne_ring_t *r, void *obj)
 
CNDP_API unsigned int cne_ring_dequeue_bulk (cne_ring_t *r, void **obj_table, unsigned int n, unsigned int *available)
 
CNDP_API __cne_always_inline int cne_ring_dequeue (cne_ring_t *r, void **obj_p)
 
CNDP_API unsigned cne_ring_enqueue_burst (cne_ring_t *r, void *const *obj_table, unsigned int n, unsigned int *free_space)
 
CNDP_API unsigned cne_ring_dequeue_burst (cne_ring_t *r, void **obj_table, unsigned int n, unsigned int *available)
 
CNDP_API unsigned int cne_ring_enqueue_bulk_elem (cne_ring_t *r, const void *obj_table, unsigned int esize, unsigned int n, unsigned int *free_space)
 
CNDP_API __cne_always_inline int cne_ring_enqueue_elem (cne_ring_t *r, void *obj, unsigned int esize)
 
CNDP_API unsigned int cne_ring_dequeue_bulk_elem (cne_ring_t *r, void *obj_table, unsigned int esize, unsigned int n, unsigned int *available)
 
CNDP_API __cne_always_inline int cne_ring_dequeue_elem (cne_ring_t *r, void *obj_p, unsigned int esize)
 
CNDP_API unsigned cne_ring_enqueue_burst_elem (cne_ring_t *r, const void *obj_table, unsigned int esize, unsigned int n, unsigned int *free_space)
 
CNDP_API unsigned int cne_ring_dequeue_burst_elem (cne_ring_t *r, void *obj_table, unsigned int esize, unsigned int n, unsigned int *available)
 

Detailed Description

CNDP Ring API

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 preemptible. Refer to Programmer's guide/Cloud Native Environment/Multiple pthread/Known Issues/cne_ring for more information.

Note: no global list of rings is maintained by this library. It's expected that the application will maintain a list of the rings it uses. As such, the application should ensure that the ring names it uses are unique.

Definition in file cne_ring_api.h.

Macro Definition Documentation

◆ RING_F_SP_ENQ

#define RING_F_SP_ENQ   0x0001

The default enqueue is "single-producer".

Definition at line 49 of file cne_ring_api.h.

◆ RING_F_SC_DEQ

#define RING_F_SC_DEQ   0x0002

The default dequeue is "single-consumer".

Definition at line 50 of file cne_ring_api.h.

◆ RING_F_ALLOCATED

#define RING_F_ALLOCATED   0x8000

The ring structure and data was allocated (internal only)

Definition at line 51 of file cne_ring_api.h.

◆ RING_F_EXACT_SZ

#define RING_F_EXACT_SZ   0x0004

Ring is to hold exactly requested number of entries. Without this flag set, the ring size requested must be a power of 2, and the usable space will be that size - 1. With the flag, the requested size will be rounded up to the next power of two, but the usable space will be exactly that requested. Worst case, if a power-of-2 size is requested, half the ring space will be wasted.

Definition at line 61 of file cne_ring_api.h.

◆ CNE_RING_SZ_MASK

#define CNE_RING_SZ_MASK   (0x7fffffffU)

Ring size mask

Definition at line 62 of file cne_ring_api.h.

Function Documentation

◆ cne_ring_get_memsize_elem()

CNDP_API ssize_t cne_ring_get_memsize_elem ( unsigned int  esize,
unsigned int  count 
)

Calculate the memory size needed for a ring with given element size

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

Parameters
esizeThe size of ring element, in bytes. It must be a multiple of 4.
countThe number of elements in the ring (must be a power of 2).
Returns
  • The memory size needed for the ring on success.
  • -EINVAL - esize is not a multiple of 4 or count provided is not a power of 2.

◆ cne_ring_get_memsize()

CNDP_API ssize_t cne_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 cne_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.

◆ cne_ring_create()

CNDP_API cne_ring_t* cne_ring_create ( const char *  name,
unsigned int  esize,
unsigned  count,
unsigned  flags 
)

Create a new ring in memory.

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.

Parameters
nameThe name of the ring.
esizeThe size of ring element, in bytes. It must be a multiple of 4, or 0 to assign the default element size.
countThe size of the ring (must be a power of 2).
flagsAn OR of the following:
Returns
On success, the pointer to the new allocated ring. NULL on error with errno set appropriately. Possible errno values include:
  • EINVAL - invalid name, esize, count or count provided is not a power of 2
  • ENAMETOOLONG - name is too long
  • ENOMEM - could not allocate ring

◆ cne_ring_init()

CNDP_API cne_ring_t* cne_ring_init ( void *  addr,
ssize_t  size,
const char *  name,
unsigned int  esize,
unsigned int  count,
unsigned int  flags 
)

Create a new ring in memory using the specified address and size of memory

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

Parameters
addrAddress of memory to use for constructing the new ring. Can be NULL to have memory allocated via calloc() call.
sizeSize of the memory buffer pointed by the addr argument. Can be zero if addr is NULL and the size must be able to hold the cne_ring_t structure and ring.
nameThe name of the ring.
esizeThe size of ring element, in bytes. It must be a multiple of 4, or 0 to assign the default element size.
countThe size of the ring (must be a power of 2).
flagsAn OR of the following:
Returns
On success, the pointer to the new allocated ring. NULL on error with errno set appropriately. Possible errno values include:
  • EINVAL - invalid name, esize, count or count provided is not a power of 2
  • ENAMETOOLONG - name is too long
  • ENOMEM - could not allocate ring

◆ cne_ring_free()

CNDP_API void cne_ring_free ( cne_ring_t *  r)

De-allocate all memory used by the ring.

Parameters
rRing to free

◆ cne_ring_dump()

CNDP_API void cne_ring_dump ( FILE *  f,
cne_ring_t *  r 
)

Dump the status of the ring to a file.

Parameters
fA pointer to a file for output
rA pointer to the ring structure.

◆ cne_ring_reset()

CNDP_API void cne_ring_reset ( cne_ring_t *  r)

Flush a ring.

This function flush all the elements in a ring

Parameters
rA pointer to the ring structure.

◆ cne_ring_count()

CNDP_API unsigned cne_ring_count ( const cne_ring_t *  r)

Return the number of entries in a ring.

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

◆ cne_ring_free_count()

CNDP_API unsigned cne_ring_free_count ( const cne_ring_t *  r)

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.

◆ cne_ring_full()

CNDP_API int cne_ring_full ( const cne_ring_t *  r)

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.

◆ cne_ring_empty()

CNDP_API int cne_ring_empty ( const cne_ring_t *  r)

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.

◆ cne_ring_get_size()

CNDP_API unsigned cne_ring_get_size ( const cne_ring_t *  r)

Return the size of the ring.

Parameters
rA pointer to the ring structure.
Returns
The size of the data store used by the ring. NOTE: this is not the same as the usable space in the ring. To query that use cne_ring_get_capacity().

◆ cne_ring_get_capacity()

CNDP_API unsigned cne_ring_get_capacity ( const cne_ring_t *  r)

Return the number of elements which can be stored in the ring.

Parameters
rA pointer to the ring structure.
Returns
The usable size of the ring.

◆ cne_ring_get_name()

CNDP_API const char* cne_ring_get_name ( const cne_ring_t *  r)

Return the ring name

Parameters
rA pointer to the ring structure.
Returns
The the ring name.

◆ cne_ring_get_flags()

CNDP_API int cne_ring_get_flags ( const cne_ring_t *  r)

Return the ring flags

Parameters
rA pointer to the ring structure.
Returns
The the ring flags.

◆ cne_ring_get_mask()

CNDP_API uint32_t cne_ring_get_mask ( const cne_ring_t *  r)

Return the ring mask

Parameters
rA pointer to the ring structure.
Returns
The the ring mask.

◆ cne_ring_get_prod_head()

CNDP_API uint32_t cne_ring_get_prod_head ( const cne_ring_t *  r)

Return the ring prod head

Parameters
rA pointer to the ring structure.
Returns
The the ring prod head

◆ cne_ring_get_prod_tail()

CNDP_API uint32_t cne_ring_get_prod_tail ( const cne_ring_t *  r)

Return the ring prod tail

Parameters
rA pointer to the ring structure.
Returns
The the ring prod tail

◆ cne_ring_get_cons_head()

CNDP_API uint32_t cne_ring_get_cons_head ( const cne_ring_t *  r)

Return the ring cons head

Parameters
rA pointer to the ring structure.
Returns
The the ring cons head

◆ cne_ring_get_cons_tail()

CNDP_API uint32_t cne_ring_get_cons_tail ( const cne_ring_t *  r)

Return the ring cons tail

Parameters
rA pointer to the ring structure.
Returns
The the ring cons tail

◆ cne_ring_enqueue_bulk()

CNDP_API unsigned int cne_ring_enqueue_bulk ( cne_ring_t *  r,
void *const *  obj_table,
unsigned int  n,
unsigned int *  free_space 
)

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

◆ cne_ring_enqueue()

__cne_always_inline int cne_ring_enqueue ( cne_ring_t *  r,
void *  obj 
)

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.
  • -ENOBUFS: Not enough room in the ring to enqueue; no object is enqueued.

Definition at line 368 of file cne_ring_api.h.

◆ cne_ring_dequeue_bulk()

CNDP_API unsigned int cne_ring_dequeue_bulk ( cne_ring_t *  r,
void **  obj_table,
unsigned int  n,
unsigned int *  available 
)

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

◆ cne_ring_dequeue()

CNDP_API __cne_always_inline int cne_ring_dequeue ( cne_ring_t *  r,
void **  obj_p 
)

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.

Definition at line 412 of file cne_ring_api.h.

◆ cne_ring_enqueue_burst()

CNDP_API unsigned cne_ring_enqueue_burst ( cne_ring_t *  r,
void *const *  obj_table,
unsigned int  n,
unsigned int *  free_space 
)

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

◆ cne_ring_dequeue_burst()

CNDP_API unsigned cne_ring_dequeue_burst ( cne_ring_t *  r,
void **  obj_table,
unsigned int  n,
unsigned int *  available 
)

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.
availableIf non-NULL, returns the number of remaining ring entries after the dequeue has finished.
Returns
  • Number of objects dequeued

◆ cne_ring_enqueue_bulk_elem()

CNDP_API unsigned int cne_ring_enqueue_bulk_elem ( cne_ring_t *  r,
const void *  obj_table,
unsigned int  esize,
unsigned int  n,
unsigned int *  free_space 
)

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

◆ cne_ring_enqueue_elem()

CNDP_API __cne_always_inline int cne_ring_enqueue_elem ( cne_ring_t *  r,
void *  obj,
unsigned int  esize 
)

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.
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.
Returns
  • 0: Success; objects enqueued.
  • -ENOBUFS: Not enough room in the ring to enqueue; no object is enqueued.

Definition at line 512 of file cne_ring_api.h.

◆ cne_ring_dequeue_bulk_elem()

CNDP_API unsigned int cne_ring_dequeue_bulk_elem ( cne_ring_t *  r,
void *  obj_table,
unsigned int  esize,
unsigned int  n,
unsigned int *  available 
)

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

◆ cne_ring_dequeue_elem()

CNDP_API __cne_always_inline int cne_ring_dequeue_elem ( cne_ring_t *  r,
void *  obj_p,
unsigned int  esize 
)

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

Definition at line 564 of file cne_ring_api.h.

◆ cne_ring_enqueue_burst_elem()

CNDP_API unsigned cne_ring_enqueue_burst_elem ( cne_ring_t *  r,
const void *  obj_table,
unsigned int  esize,
unsigned int  n,
unsigned int *  free_space 
)

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

◆ cne_ring_dequeue_burst_elem()

CNDP_API unsigned int cne_ring_dequeue_burst_elem ( cne_ring_t *  r,
void *  obj_table,
unsigned int  esize,
unsigned int  n,
unsigned int *  available 
)

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 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
  • Number of objects dequeued