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

esize	The size of ring element, in bytes. It must be a multiple of 4.
count	The 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

count

The 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

name	The name of the ring.
esize	The size of ring element, in bytes. It must be a multiple of 4, or 0 to assign the default element size.
count	The size of the ring (must be a power of 2).
flags	An OR of the following: RING_F_SP_ENQ: If this flag is set, the default behavior when using cne_ring_enqueue() or cne_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 cne_ring_dequeue() or cne_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 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

addr	Address of memory to use for constructing the new ring. Can be NULL to have memory allocated via calloc() call.
size	Size 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.
name	The name of the ring.
esize	The size of ring element, in bytes. It must be a multiple of 4, or 0 to assign the default element size.
count	The size of the ring (must be a power of 2).
flags	An OR of the following: RING_F_SP_ENQ: If this flag is set, the default behavior when using cne_ring_enqueue() or cne_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 cne_ring_dequeue() or cne_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 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

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

f	A pointer to a file for output
r	A 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

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

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.

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

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

• 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

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

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

r	A pointer to the ring structure.
obj	A pointer to the object to be added.
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.

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

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

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

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

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

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.

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

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

• Number of objects dequeued