#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include <errno.h>
#include <inttypes.h>
#include <sys/queue.h>
#include <sys/types.h>
#include <cne.h>
#include <cne_common.h>
#include <cne_log.h>

Data Structures
struct	mempool_cfg

Typedefs
typedef void	mempool_t

typedef void()	mempool_obj_cb_t(mempool_t mp, void opaque, void *obj, unsigned obj_idx)

typedef void()	mempool_ctor_t(mempool_t , void )

typedef struct mempool_cfg	mempool_cfg_t

Functions
CNDP_API mempool_t *	mempool_create (struct mempool_cfg *cinfo)

CNDP_API mempool_t *	mempool_create_empty (struct mempool_cfg *cinfo)

CNDP_API void	mempool_destroy (mempool_t *mp)

CNDP_API int	mempool_populate (mempool_t mp, char vaddr, size_t len)

CNDP_API uint32_t	mempool_obj_iter (mempool_t mp, mempool_obj_cb_t obj_cb, void *obj_cb_arg)

CNDP_API void	mempool_dump (mempool_t *mp)

CNDP_API struct mempool_cache *	mempool_default_cache (mempool_t *mp)

CNDP_API void	mempool_generic_put (mempool_t mp, void const obj_table, unsigned int n, struct mempool_cache cache)

CNDP_API void	mempool_put_bulk (mempool_t mp, void const *obj_table, unsigned int n)

CNDP_API void	mempool_put (mempool_t mp, void obj)

CNDP_API int	mempool_generic_get (mempool_t mp, void obj_table, unsigned int n, struct mempool_cache cache)

CNDP_API int	mempool_get_bulk (mempool_t mp, void *obj_table, unsigned int n)

CNDP_API int	mempool_get (mempool_t mp, void *obj_p)

CNDP_API unsigned int	mempool_avail_count (const mempool_t *mp)

CNDP_API unsigned int	mempool_in_use_count (const mempool_t *mp)

CNDP_API int	mempool_full (const mempool_t *mp)

CNDP_API int	mempool_empty (const mempool_t *mp)

CNDP_API void *	mempool_ring_addr (mempool_t *mp)

CNDP_API void *	mempool_buff_addr (mempool_t *mp)

CNDP_API int	mempool_objcnt (mempool_t *mp)

CNDP_API int	mempool_objsz (mempool_t *mp)

CNDP_API int	mempool_cache_sz (mempool_t *mp)

CNDP_API int	mempool_cache_len (mempool_t *mp, int idx)

CNDP_API int	mempool_obj_index (mempool_t mp, void obj)

CNDP_API void *	mempool_obj_at_index (mempool_t *mp, int idx)

Detailed Description

CNE Mempool.

A memory pool is an allocator of fixed-size object. It is identified by its name, and uses a ring to store free objects.

Objects owned by a mempool should never be added in another mempool. When an object is freed using mempool_put() or equivalent, the object data is not modified; the user can save some meta-data in the object data and retrieve them when allocating a new object.

Note: the mempool implementation is not preemptible. An thread must not be interrupted by another task that uses the same mempool (because it uses a ring which is not preemptible).

Definition in file mempool.h.

Typedef Documentation

◆ mempool_t

typedef void mempool_t

Opaque pointer for mempool

Definition at line 45 of file mempool.h.

◆ mempool_obj_cb_t

typedef void() mempool_obj_cb_t(mempool_t *mp, void *opaque, void *obj, unsigned obj_idx)

An object callback function for mempool.

Used by mempool_create() and mempool_obj_iter().

Definition at line 52 of file mempool.h.

◆ mempool_ctor_t

typedef void() mempool_ctor_t(mempool_t *, void *)

A mempool constructor callback function.

Arguments are the mempool and the opaque pointer given by the user in mempool_create().

Definition at line 61 of file mempool.h.

◆ mempool_cfg_t

typedef struct mempool_cfg mempool_cfg_t

Parameters

objcnt	The number of elements in the mempool. The optimum size (in terms of memory usage) for a mempool is when n is a power of two minus one: n = (2^q - 1).
objsz	The size of each element.
cache_sz	Size of the for the mempool
addr	The address to the start of the mempool. If the addr is NULL then it will be allocated from the system memory and freed when the mempool is destroyed.
mp_init	A function pointer that is called for initialization of the pool, before object initialization. This parameter can be NULL if not needed.
mp_init_arg	An opaque pointer to data that can be used in the mempool constructor function.
obj_init	A function pointer that is called for each object at initialization of the pool. The user can set some meta data in objects if needed. This parameter can be NULL if not needed. The obj_init() function takes the mempool pointer, the init_arg, the object pointer and the object number as parameters.
obj_init_arg	An opaque pointer to data that can be used as an argument for each call to the object constructor function.

Function Documentation

◆ mempool_create()

CNDP_API mempool_t* mempool_create ( struct mempool_cfg * cinfo )

Create a new mempool in memory.

This function uses mmap_alloc() to allocate memory. The pool contains n elements of elt_size. Its size is set to n.

Parameters

cinfo Pointer to the mempool_cfg structure

Returns

The pointer to the new allocated mempool, on success. NULL on error with errno set appropriately. Possible errno values include:

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

◆ mempool_create_empty()

CNDP_API mempool_t* mempool_create_empty ( struct mempool_cfg * cinfo )

Create an empty mempool

The mempool is allocated and initialized, but it is not populated: no memory is allocated for the mempool elements. The user has to call mempool_populate_*() to add memory chunks to the pool. Once populated, the user may also want to initialize each object with mempool_obj_iter().

Parameters

cinfo Pointer to the mempool_cfg structure

Returns: The pointer to the new allocated mempool, on success. NULL on error with errno set appropriately. See mempool_create() for details.

◆ mempool_destroy()

CNDP_API void mempool_destroy ( mempool_t * mp )

Free a mempool

Unlink the mempool from global list, free the memory chunks, and all memory referenced by the mempool. The objects must not be used by other cores as they will be freed.

Parameters

mp	A pointer to the mempool structure.

◆ mempool_populate()

CNDP_API int mempool_populate	(	mempool_t *	mp,
		char *	vaddr,
		size_t	len
	)

Initialize a mempool buffer area with given address and size

Parameters

mp	The mempool pointer
vaddr	The start of the virtual address to use for buffers
len	The length of the buffer space

Returns: 0 on success and -1 on error

◆ mempool_obj_iter()

CNDP_API uint32_t mempool_obj_iter	(	mempool_t *	mp,
		mempool_obj_cb_t *	obj_cb,
		void *	obj_cb_arg
	)

Call a function for each mempool element

Iterate across all objects attached to a cne_mempool and call the callback function on it.

Parameters

mp	A pointer to an initialized mempool.
obj_cb	A function pointer that is called for each object.
obj_cb_arg	An opaque pointer passed to the callback function.

Returns: Number of objects iterated.

◆ mempool_dump()

CNDP_API void mempool_dump ( mempool_t * mp )

Dump the status of the mempool to a file.

Parameters

mp	A pointer to the mempool structure.

◆ mempool_default_cache()

CNDP_API struct mempool_cache* mempool_default_cache ( mempool_t * mp )

Get a pointer to the per-thread default mempool cache.

Parameters

mp	A pointer to the mempool structure.

Returns: A pointer to the mempool cache or NULL if disabled or non-CNE thread.

◆ mempool_generic_put()

CNDP_API void mempool_generic_put	(	mempool_t *	mp,
		void const	obj_table,
		unsigned int	n,
		struct mempool_cache *	cache
	)

Put several objects back in the mempool.

Parameters

mp	A pointer to the mempool structure.
obj_table	A pointer to a table of void * pointers (objects).
n	The number of objects to add in the mempool from the obj_table.
cache	A pointer to a mempool cache structure. May be NULL if not needed.

◆ mempool_put_bulk()

CNDP_API void mempool_put_bulk	(	mempool_t *	mp,
		void const	obj_table,
		unsigned int	n
	)

Put several objects back in the mempool.

This function calls the multi-producer or the single-producer version depending on the default behavior that was specified at mempool creation time (see flags).

Parameters

mp	A pointer to the mempool structure.
obj_table	A pointer to a table of void * pointers (objects).
n	The number of objects to add in the mempool from obj_table.

◆ mempool_put()

CNDP_API void mempool_put	(	mempool_t *	mp,
		void *	obj
	)

Put one object back in the mempool.

This function calls the multi-producer or the single-producer version depending on the default behavior that was specified at mempool creation time (see flags).

Parameters

mp	A pointer to the mempool structure.
obj	A pointer to the object to be added.

◆ mempool_generic_get()

CNDP_API int mempool_generic_get	(	mempool_t *	mp,
		void **	obj_table,
		unsigned int	n,
		struct mempool_cache *	cache
	)

Get several objects from the mempool.

If cache is enabled, objects will be retrieved first from cache, subsequently from the common pool. Note that it can return -ENOENT when the local cache and common pool are empty, even if cache from other threads are full.

Parameters

mp	A pointer to the mempool structure.
obj_table	A pointer to a table of void * pointers (objects) that will be filled.
n	The number of objects to get from mempool to obj_table.
cache	A pointer to a mempool cache structure. May be NULL if not needed.

Returns

0: Success; objects taken.
-ENOENT: Not enough entries in the mempool; no object is retrieved.

◆ mempool_get_bulk()

CNDP_API int mempool_get_bulk	(	mempool_t *	mp,
		void **	obj_table,
		unsigned int	n
	)

Get several objects from the mempool.

This function calls the multi-consumers or the single-consumer version, depending on the default behaviour that was specified at mempool creation time (see flags).

Parameters

mp	A pointer to the mempool structure.
obj_table	A pointer to a table of void * pointers (objects) that will be filled.
n	The number of objects to get from the mempool to obj_table.

Returns

0: Success; objects taken
-ENOENT: Not enough entries in the mempool; no object is retrieved.

◆ mempool_get()

CNDP_API int mempool_get	(	mempool_t *	mp,
		void **	obj_p
	)

Get one object from the mempool.

This function calls the multi-consumers or the single-consumer version, depending on the default behavior that was specified at mempool creation (see flags).

Parameters

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

Returns

0: Success; objects taken.
-ENOENT: Not enough entries in the mempool; no object is retrieved.

◆ mempool_avail_count()

CNDP_API unsigned int mempool_avail_count ( const mempool_t * mp )

Return the number of entries in the mempool.

Parameters

mp	A pointer to the mempool structure.

Returns: The number of entries in the mempool.

◆ mempool_in_use_count()

CNDP_API unsigned int mempool_in_use_count ( const mempool_t * mp )

Return the number of elements which have been allocated from the mempool

Parameters

mp	A pointer to the mempool structure.

Returns: The number of free entries in the mempool.

◆ mempool_full()

CNDP_API int mempool_full ( const mempool_t * mp )

Test if the mempool is full.

Parameters

mp	A pointer to the mempool structure.

Returns

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

◆ mempool_empty()

CNDP_API int mempool_empty ( const mempool_t * mp )

Test if the mempool is empty.

Parameters

mp	A pointer to the mempool structure.

Returns

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

◆ mempool_ring_addr()

CNDP_API void* mempool_ring_addr ( mempool_t * mp )

Return the mempool ring pointer.

Parameters

mp	The ring pointer for the mempool.

Returns: The ring pointer or NULL on error

◆ mempool_buff_addr()

CNDP_API void* mempool_buff_addr ( mempool_t * mp )

Return the mempool buffer pointer.

Parameters

mp	The object memory pointer for the mempool.

Returns: The object memory pointer or NULL on error

◆ mempool_objcnt()

CNDP_API int mempool_objcnt ( mempool_t * mp )

Return number of objects in mempool.

Parameters

mp	Mempool pointer

Returns: The number of objects in the mempool or -1 on error

◆ mempool_objsz()

CNDP_API int mempool_objsz ( mempool_t * mp )

Return size of objects in mempool.

Parameters

mp	Mempool pointer

Returns: The size of objects in the mempool or -1 on error

◆ mempool_cache_sz()

CNDP_API int mempool_cache_sz ( mempool_t * mp )

Return the cache size of the mempool.

Parameters

mp	The mempool pointer

Returns: The mempool cache size or -1 on error

◆ mempool_cache_len()

CNDP_API int mempool_cache_len	(	mempool_t *	mp,
		int	idx
	)

Return the length of the cache entry noted by idx

Parameters

mp	The mempool pointer
idx	The index value into the cache list

Returns: The number of entries in the cache or -1 on error

◆ mempool_obj_index()

CNDP_API int mempool_obj_index	(	mempool_t *	mp,
		void *	obj
	)

Determine the object index value in the mempool.

Parameters

mp	The mempool_t pointer to use to calculate the object index.
obj	The object pointer to use in calculation

Returns: -1 on error or object index value.

◆ mempool_obj_at_index()

CNDP_API void* mempool_obj_at_index	(	mempool_t *	mp,
		int	idx
	)

Return the object pointer for the given mempool_t and index value

Parameters

mp	The mempool_t pointer to use to calculate the object address.
idx	The index value into the mempool buffer array.

Returns: NULL on error or pointer to object.

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ mempool_t

◆ mempool_obj_cb_t

◆ mempool_ctor_t

◆ mempool_cfg_t

Function Documentation

◆ mempool_create()

◆ mempool_create_empty()

◆ mempool_destroy()

◆ mempool_populate()

◆ mempool_obj_iter()

◆ mempool_dump()

◆ mempool_default_cache()

◆ mempool_generic_put()

◆ mempool_put_bulk()

◆ mempool_put()

◆ mempool_generic_get()

◆ mempool_get_bulk()

◆ mempool_get()

◆ mempool_avail_count()

◆ mempool_in_use_count()

◆ mempool_full()

◆ mempool_empty()

◆ mempool_ring_addr()

◆ mempool_buff_addr()

◆ mempool_objcnt()

◆ mempool_objsz()

◆ mempool_cache_sz()

◆ mempool_cache_len()

◆ mempool_obj_index()

◆ mempool_obj_at_index()