mempool.h File Reference

Memory pool implementation. More...

#include "ucx.h"
#include "allocator.h"
#include <stddef.h>

Go to the source code of this file.

Data Structures
struct	UcxMempool
	UCX mempool structure. More...

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

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

Detailed Description

Memory pool implementation.

Author

Mike Becker

Olaf Wintermann

Macro Definition Documentation

ucx_mempool_new_default

#define ucx_mempool_new_default

(

)

ucx_mempool_new(16)

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

Function Documentation

ucx_mempool_calloc()

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

Allocates a pooled memory array.

The content of the allocated memory is set to zero.

Parameters

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

Returns

a pointer to the allocated memory

See also

ucx_allocator_calloc()

ucx_mempool_chcap()

int ucx_mempool_chcap	(	UcxMempool *	pool,
		size_t	newcap
	)

Resizes a memory pool.

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

Parameters

pool	the pool to resize
newcap	the new capacity

Returns

zero on success or non-zero on failure

ucx_mempool_destroy()

void ucx_mempool_destroy

(

UcxMempool *

pool

)

Destroys a memory pool.

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

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

Parameters

pool	the mempool to destroy

ucx_mempool_free()

void ucx_mempool_free	(	UcxMempool *	pool,
		void *	ptr
	)

Frees pooled memory.

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

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

Parameters

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

See also

ucx_mempool_set_destr()

ucx_mempool_malloc()

void* ucx_mempool_malloc	(	UcxMempool *	pool,
		size_t	n
	)

Allocates pooled memory.

Parameters

pool	the memory pool
n	amount of memory to allocate

Returns

a pointer to the allocated memory

See also

ucx_allocator_malloc()

ucx_mempool_new()

UcxMempool* ucx_mempool_new

(

size_t

n

)

Creates a memory pool with the specified initial size.

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.

Parameters

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

Returns

a pointer to the new memory pool

See also

ucx_mempool_new_default()

ucx_mempool_realloc()

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

Reallocates pooled memory.

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

Parameters

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

Returns

a pointer to the new location of the memory

See also

ucx_allocator_realloc()

ucx_mempool_reg_destr()

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

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

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

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.

Parameters

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

ucx_mempool_set_destr()

void ucx_mempool_set_destr	(	void *	ptr,
		ucx_destructor	func
	)

Sets a destructor function for the specified memory.

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.

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.

Parameters

ptr	pooled memory
func	a pointer to the destructor function

See also

ucx_mempool_free()

ucx_mempool_destroy()