mempool.h File Reference

Interface for memory pool implementations. More...

#include "common.h"
#include "allocator.h"

Go to the source code of this file.

Data Structures
struct	cx_mempool_memory_s
	A memory block in a simple memory pool. More...
struct	cx_mempool_memory2_s
	A memory block in an advanced memory pool. More...
struct	cx_mempool_foreign_memory_s
	Represents memory that is not allocated by, but registered with a pool. More...
struct	cx_mempool_s
	The basic structure of a memory pool. More...

Macros
#define	cxMempoolCreateSimple(capacity)
	Creates a basic array-based memory pool.
#define	cxMempoolCreateAdvanced(capacity)
	Creates a basic array-based memory pool.
#define	cxMempoolCreatePure(capacity)
	Creates a basic array-based memory pool.

Typedefs
typedef struct cx_mempool_s	CxMempool
	Common type for all memory pool implementations.

Enumerations
enum	cx_mempool_type { CX_MEMPOOL_TYPE_SIMPLE , CX_MEMPOOL_TYPE_ADVANCED , CX_MEMPOOL_TYPE_PURE }
	Specifies how individual blocks are allocated. More...

Functions
void	cxMempoolFree (CxMempool *pool)
	Deallocates a memory pool and frees the managed memory.
CxMempool *	cxMempoolCreate (size_t capacity, enum cx_mempool_type type)
	Creates an array-based memory pool.
void	cxMempoolGlobalDestructor (CxMempool *pool, cx_destructor_func fnc)
	Sets the global destructor for all memory blocks within the specified pool.
void	cxMempoolGlobalDestructor2 (CxMempool *pool, cx_destructor_func2 fnc, void *data)
	Sets the global destructor for all memory blocks within the specified pool.
void	cxMempoolSetDestructor (void *memory, cx_destructor_func fnc)
	Sets the destructor function for a specific allocated memory object.
void	cxMempoolSetDestructor2 (void *memory, cx_destructor_func2 fnc, void *data)
	Sets the destructor function for a specific allocated memory object.
void	cxMempoolRemoveDestructor (void *memory)
	Removes the destructor function for a specific allocated memory object.
void	cxMempoolRemoveDestructor2 (void *memory)
	Removes the destructor function for a specific allocated memory object.
int	cxMempoolRegister (CxMempool *pool, void *memory, cx_destructor_func destr)
	Registers foreign memory with this pool.
int	cxMempoolRegister2 (CxMempool *pool, void *memory, cx_destructor_func2 destr, void *data)
	Registers foreign memory with this pool.
int	cxMempoolTransfer (CxMempool *source, CxMempool *dest)
	Transfers all the memory managed by one pool to another.
int	cxMempoolTransferObject (CxMempool *source, CxMempool *dest, const void *obj)
	Transfers an object from one pool to another.

Detailed Description

Interface for memory pool implementations.

Author

Mike Becker

Olaf Wintermann

Copyright

2-Clause BSD License

Macro Definition Documentation

cxMempoolCreateAdvanced

#define cxMempoolCreateAdvanced

(

capacity

)

Value:

cxMempoolCreate(capacity, CX_MEMPOOL_TYPE_ADVANCED)

Creates a basic array-based memory pool.

Convenience macro to create a memory pool of type CX_MEMPOOL_TYPE_ADVANCED.

Parameters

capacity

(size_t) the initial capacity of the pool

Returns

(CxMempool*) the created memory pool or NULL if allocation failed

cxMempoolCreatePure

#define cxMempoolCreatePure

(

capacity

)

Value:

cxMempoolCreate(capacity, CX_MEMPOOL_TYPE_PURE)

Creates a basic array-based memory pool.

Convenience macro to create a memory pool of type CX_MEMPOOL_TYPE_PURE.

Parameters

capacity

(size_t) the initial capacity of the pool

Returns

(CxMempool*) the created memory pool or NULL if allocation failed

cxMempoolCreateSimple

#define cxMempoolCreateSimple

(

capacity

)

Value:

cxMempoolCreate(capacity, CX_MEMPOOL_TYPE_SIMPLE)

Creates a basic array-based memory pool.

Convenience macro to create a memory pool of type CX_MEMPOOL_TYPE_SIMPLE.

Parameters

capacity

(size_t) the initial capacity of the pool

Returns

(CxMempool*) the created memory pool or NULL if allocation failed

Enumeration Type Documentation

cx_mempool_type

enum cx_mempool_type

Specifies how individual blocks are allocated.

Enumerator
CX_MEMPOOL_TYPE_SIMPLE	Allows registration of cx_destructor_func for each memory block.
CX_MEMPOOL_TYPE_ADVANCED	Allows registration of cx_destructor_func2 for each memory block.
CX_MEMPOOL_TYPE_PURE	No individual destructor registration allowed. In this mode, no additional memory per block is allocated.

Function Documentation

cxMempoolCreate()

CxMempool * cxMempoolCreate	(	size_t	capacity,
		enum cx_mempool_type	type )

Creates an array-based memory pool.

The type determines how much additional memory is allocated per block to register a destructor function.

Parameters

capacity	the initial capacity of the pool (an implementation default if zero)
type	the type of memory pool

Returns

the created memory pool or NULL if allocation failed

cxMempoolFree()

void cxMempoolFree

(

CxMempool *

pool

)

Deallocates a memory pool and frees the managed memory.

Parameters

pool	the memory pool to free

cxMempoolGlobalDestructor()

void cxMempoolGlobalDestructor	(	CxMempool *	pool,
		cx_destructor_func	fnc )

Sets the global destructor for all memory blocks within the specified pool.

Parameters

pool	the memory pool
fnc	the destructor that shall be applied to all memory blocks

cxMempoolGlobalDestructor2()

void cxMempoolGlobalDestructor2	(	CxMempool *	pool,
		cx_destructor_func2	fnc,
		void *	data )

Sets the global destructor for all memory blocks within the specified pool.

Parameters

pool	the memory pool
fnc	the destructor that shall be applied to all memory blocks
data	additional data for the destructor function

cxMempoolRegister()

int cxMempoolRegister	(	CxMempool *	pool,
		void *	memory,
		cx_destructor_func	destr )

Registers foreign memory with this pool.

The destructor, in contrast to memory allocated by the pool, MUST free the memory. This function can be used with any pool of any type, since destructors for registered memory are entirely independent of the pool's memory management.

The destructor for the registered memory will be called after all pooled items have been freed.

Parameters

pool	the pool
memory	the object to register (MUST NOT be already allocated in the pool)
destr	the destructor function

Return values

zero	success
non-zero	failure

cxMempoolRegister2()

int cxMempoolRegister2	(	CxMempool *	pool,
		void *	memory,
		cx_destructor_func2	destr,
		void *	data )

Registers foreign memory with this pool.

The destructor, in contrast to memory allocated by the pool, MUST free the memory. This function can be used with any pool of any type, since destructors for registered memory are entirely independent of the pool's memory management.

The destructor for the registered memory will be called after all pooled items have been freed.

Attention

The data pointer MUST NOT be NULL. If you wish to register a destructor without additional data, use cxMempoolRegister().

Parameters

pool	the pool
memory	the object to register (MUST NOT be already allocated in the pool)
destr	the destructor function
data	additional data for the destructor function

Return values

zero	success
non-zero	failure

cxMempoolRemoveDestructor()

void cxMempoolRemoveDestructor

(

void *

memory

)

Removes the destructor function for a specific allocated memory object.

If the type of memory pool is not CX_MEMPOOL_TYPE_SIMPLE, the behavior is undefined. If the memory is not managed by a UCX memory pool, the behavior is undefined.

Parameters

memory

the object allocated in the pool

cxMempoolRemoveDestructor2()

void cxMempoolRemoveDestructor2

(

void *

memory

)

Removes the destructor function for a specific allocated memory object.

If the type of memory pool is not CX_MEMPOOL_TYPE_ADVANCED, the behavior is undefined. If the memory is not managed by a UCX memory pool, the behavior is undefined.

Parameters

memory

the object allocated in the pool

cxMempoolSetDestructor()

void cxMempoolSetDestructor	(	void *	memory,
		cx_destructor_func	fnc )

Sets the destructor function for a specific allocated memory object.

If the type of memory pool is not CX_MEMPOOL_TYPE_SIMPLE, the behavior is undefined. If the memory is not managed by a UCX memory pool, the behavior is undefined. The destructor MUST NOT free the memory.

Parameters

memory	the object allocated in the pool
fnc	the destructor function

cxMempoolSetDestructor2()

void cxMempoolSetDestructor2	(	void *	memory,
		cx_destructor_func2	fnc,
		void *	data )

Sets the destructor function for a specific allocated memory object.

If the type of memory pool is not CX_MEMPOOL_TYPE_ADVANCED, the behavior is undefined. If the memory is not managed by a UCX memory pool, the behavior is undefined. The destructor MUST NOT free the memory.

Parameters

memory	the object allocated in the pool
fnc	the destructor function
data	additional data for the destructor function

cxMempoolTransfer()

int cxMempoolTransfer	(	CxMempool *	source,
		CxMempool *	dest )

Transfers all the memory managed by one pool to another.

The allocator of the source pool will also be transferred and registered with the destination pool and stays valid, as long as the destination pool is not destroyed.

The source pool will get a completely new allocator and can be reused or destroyed afterward.

This function fails when the destination pool has a different type than the source pool.

Parameters

source	the pool to move the memory from
dest	the pool where to transfer the memory to

Return values

zero	success
non-zero	allocation failure or incompatible pools

cxMempoolTransferObject()

int cxMempoolTransferObject	(	CxMempool *	source,
		CxMempool *	dest,
		const void *	obj )

Transfers an object from one pool to another.

This function fails when the destination pool has a different type than the source pool.

Attention

If the object maintains a reference to the pool's allocator, you must make sure to update that reference to the allocator of the destination pool.

Parameters

source	the pool to move the memory from
dest	the pool where to transfer the memory to
obj	pointer to the object that shall be transferred

Return values

zero	success
non-zero	failure, or the object was not found in the source pool, or the pools are incompatible