diff -r 92e482410453 -r d345541018fa docs/api-2.1/mempool_8h.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/api-2.1/mempool_8h.html Sat Feb 06 19:11:44 2021 +0100 @@ -0,0 +1,517 @@ + + + + + + + +ucx: /home/mike/workspace/c/ucx/src/ucx/mempool.h File Reference + + + + + + + + + +
+
+ + + + + + + +
+
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

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
+ + + + +
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()
+ +
+
+
+ +
+Generated on Thu Dec 19 2019 19:58:24 for ucx by   +doxygen + 1.8.13 +
+ +