universe@390: universe@390:

Memory pool implementation. universe@390: More...

universe@390:

#include "ucx.h"
universe@390: #include "allocator.h"
universe@390: #include <stddef.h>
universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

universe@390: Data Structures
struct	UcxMempool
	UCX mempool structure. More...

universe@390: universe@390: universe@390: universe@390: universe@390:

universe@390: Macros
#define	ucx_mempool_new_default() ucx_mempool_new(16)
	Shorthand for a new default memory pool with a capacity of 16 elements. More...

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

universe@390: Functions
UcxMempool *	ucx_mempool_new (size_t n)
	Creates a memory pool with the specified initial size. More...

int	ucx_mempool_chcap (UcxMempool *pool, size_t newcap)
	Resizes a memory pool. More...

void *	ucx_mempool_malloc (UcxMempool *pool, size_t n)
	Allocates pooled memory. More...

void *	ucx_mempool_calloc (UcxMempool *pool, size_t nelem, size_t elsize)
	Allocates a pooled memory array. More...

void *	ucx_mempool_realloc (UcxMempool pool, void ptr, size_t n)
	Reallocates pooled memory. More...

void	ucx_mempool_free (UcxMempool pool, void ptr)
	Frees pooled memory. More...

void	ucx_mempool_destroy (UcxMempool *pool)
	Destroys a memory pool. More...

void	ucx_mempool_set_destr (void *ptr, ucx_destructor func)
	Sets a destructor function for the specified memory. More...

void	ucx_mempool_reg_destr (UcxMempool pool, void ptr, ucx_destructor destr)
	Registers a destructor function for the specified (non-pooled) memory. More...

universe@390:

Detailed Description

universe@390:

Memory pool implementation.

universe@390:

Author: Mike Becker; universe@390: Olaf Wintermann

universe@390:

Macro Definition Documentation

universe@390: universe@390:

◆ ucx_mempool_new_default

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

#define ucx_mempool_new_default ( ) ucx_mempool_new(16)

universe@390:

universe@390: universe@390:

Shorthand for a new default memory pool with a capacity of 16 elements.

universe@390: universe@390:

universe@390:

Function Documentation

universe@390: universe@390:

◆ ucx_mempool_calloc()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

void* ucx_mempool_calloc	(	UcxMempool *	pool,
		size_t	nelem,
		size_t	elsize
	)

universe@390:

universe@390: universe@390:

Allocates a pooled memory array.

universe@390:

The content of the allocated memory is set to zero.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390: universe@390:

pool	the memory pool
nelem	amount of elements to allocate
elsize	amount of memory per element

universe@390:

Returns: a pointer to the allocated memory

universe@390:

See also: ucx_allocator_calloc()

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_mempool_chcap()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

int ucx_mempool_chcap	(	UcxMempool *	pool,
		size_t	newcap
	)

universe@390:

universe@390: universe@390:

Resizes a memory pool.

universe@390:

This function will fail if the new capacity is not sufficient for the present data.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390:

pool	the pool to resize
newcap	the new capacity

universe@390:

Returns: zero on success or non-zero on failure

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_mempool_destroy()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

void ucx_mempool_destroy ( UcxMempool * pool )

universe@390:

universe@390: universe@390:

Destroys a memory pool.

universe@390:

For each element the destructor function (if any) is called and the element is freed.

universe@390:

Each of the registered destructor function that has no corresponding element within the pool (namely those registered by ucx_mempool_reg_destr) is called interleaving with the element destruction, but with guarantee to the order in which they were registered (FIFO order).

universe@390:

Parameters

universe@390: universe@390: universe@390:

pool	the mempool to destroy

universe@390:

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_mempool_free()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

void ucx_mempool_free	(	UcxMempool *	pool,
		void *	ptr
	)

universe@390:

universe@390: universe@390:

Frees pooled memory.

universe@390:

Before freeing the memory, the specified destructor function (if any) is called.

universe@390:

If you specify memory, that is not pooled by the specified memory pool, the program will terminate with a call to abort().

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390:

pool	the memory pool
ptr	a pointer to the memory that shall be freed

universe@390:

See also: ucx_mempool_set_destr()

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_mempool_malloc()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

void* ucx_mempool_malloc	(	UcxMempool *	pool,
		size_t	n
	)

universe@390:

universe@390: universe@390:

Allocates pooled memory.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390:

pool	the memory pool
n	amount of memory to allocate

universe@390:

Returns: a pointer to the allocated memory

universe@390:

See also: ucx_allocator_malloc()

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_mempool_new()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

UcxMempool* ucx_mempool_new ( size_t n )

universe@390:

universe@390: universe@390:

Creates a memory pool with the specified initial size.

universe@390:

As the created memory pool automatically grows in size by factor two when trying to allocate memory on a full pool, it is recommended that you use a power of two for the initial size.

universe@390:

Parameters

universe@390: universe@390: universe@390:

n	initial pool size (should be a power of two, e.g. 16)

universe@390:

Returns: a pointer to the new memory pool

universe@390:

See also: ucx_mempool_new_default()

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_mempool_realloc()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

void* ucx_mempool_realloc	(	UcxMempool *	pool,
		void *	ptr,
		size_t	n
	)

universe@390:

universe@390: universe@390:

Reallocates pooled memory.

universe@390:

If the memory to be reallocated is not contained by the specified pool, the behavior is undefined.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390: universe@390:

pool	the memory pool
ptr	a pointer to the memory that shall be reallocated
n	the new size of the memory

universe@390:

Returns: a pointer to the new location of the memory

universe@390:

See also: ucx_allocator_realloc()

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_mempool_reg_destr()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

void ucx_mempool_reg_destr	(	UcxMempool *	pool,
		void *	ptr,
		ucx_destructor	destr
	)

universe@390:

universe@390: universe@390:

Registers a destructor function for the specified (non-pooled) memory.

universe@390:

This is useful, if you have memory that has not been allocated by a mempool, but shall be managed by a mempool.

universe@390:

This function creates an entry in the specified mempool and the memory will therefore (logically) convert to pooled memory. However, this does not cause the memory to be freed automatically!. If you want to use this function, make the memory pool free non-pooled memory, the specified destructor function must call free() by itself. But keep in mind, that you then MUST NOT use this destructor function with pooled memory (e.g. in ucx_mempool_set_destr()), as it would cause a double-free.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390: universe@390:

pool	the memory pool
ptr	data the destructor is registered for
destr	a pointer to the destructor function

universe@390:

universe@390: universe@390:

universe@390:

universe@390: universe@390:

◆ ucx_mempool_set_destr()

universe@390: universe@390:

universe@390:

universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390: universe@390:

void ucx_mempool_set_destr	(	void *	ptr,
		ucx_destructor	func
	)

universe@390:

universe@390: universe@390:

Sets a destructor function for the specified memory.

universe@390:

The destructor is automatically called when the memory is freed or the pool is destroyed. A destructor for pooled memory MUST NOT free the memory itself, as this is done by the pool. Use a destructor to free any resources managed by the pooled object.

universe@390:

The only requirement for the specified memory is, that it MUST be pooled memory by a UcxMempool or an element-compatible mempool. The pointer to the destructor function is saved in a reserved area before the actual memory.

universe@390:

Parameters

universe@390: universe@390: universe@390: universe@390:

ptr	pooled memory
func	a pointer to the destructor function

universe@390:

See also: ucx_mempool_free(); universe@390: ucx_mempool_destroy()

universe@390: universe@390:

universe@390:

universe@390: Data Structures

universe@390: Macros

universe@390: Functions

Detailed Description

Macro Definition Documentation

◆ ucx_mempool_new_default

Function Documentation

◆ ucx_mempool_calloc()

◆ ucx_mempool_chcap()

◆ ucx_mempool_destroy()

◆ ucx_mempool_free()

◆ ucx_mempool_malloc()

◆ ucx_mempool_new()

◆ ucx_mempool_realloc()

◆ ucx_mempool_reg_destr()

◆ ucx_mempool_set_destr()