ucx
UAP Common Extensions
Data Structures | Macros | Functions
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

UcxMempoolucx_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
poolthe memory pool
nelemamount of elements to allocate
elsizeamount 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
poolthe pool to resize
newcapthe 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
poolthe 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
poolthe memory pool
ptra 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
poolthe memory pool
namount 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
ninitial 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
poolthe memory pool
ptra pointer to the memory that shall be reallocated
nthe 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
poolthe memory pool
ptrdata the destructor is registered for
destra 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
ptrpooled memory
funca pointer to the destructor function
See also
ucx_mempool_free()
ucx_mempool_destroy()