Pool

Files
file	afw_pool.h
	Adaptive Framework memory pool support header.

Data Structures
struct	afw_pool_cleanup_s
	Struct for registered cleanup functions. More...

Macros
#define	afw_pool_calloc_type(instance, type, xctx)    (type *) afw_pool_calloc(instance, sizeof(type), xctx)
	Macro to allocate cleared memory to hold type in pool. More...
#define	afw_pool_malloc_type(instance, type, xctx)    (type *) afw_pool_malloc(instance, sizeof(type), xctx)
	Macro to allocate uncleared memory to hold type in pool. More...

Typedefs
typedef struct afw_pool_cleanup_s	afw_pool_cleanup_t
	Typedef for registered cleanup functions.

Functions
const afw_pool_t *	afw_pool_create (const afw_pool_t *parent, afw_xctx_t *xctx)
	Create a new pool. More...
const afw_pool_t *	afw_pool_create_debug (const afw_pool_t *parent, afw_xctx_t *xctx, const afw_utf8_z_t *source_z)
	Debug version of create a new pool. More...
const afw_pool_t *	afw_pool_create_multithreaded (const afw_pool_t *parent, afw_xctx_t *xctx)
	Create a new multithreaded pool. More...
const afw_pool_t *	afw_pool_create_multithreaded_debug (const afw_pool_t *parent, afw_xctx_t *xctx, const afw_utf8_z_t *source_z)
	Debug version of create a new multithreaded pool. More...

Detailed Description

Pool support

Macro Definition Documentation

afw_pool_calloc_type

#define afw_pool_calloc_type	(		instance,
			type,
			xctx
	)		(type *) afw_pool_calloc(instance, sizeof(type), xctx)

Macro to allocate cleared memory to hold type in pool.

Parameters

instance	of pool.
type	to allocate.
xctx	of caller.

Returns

pointer to memory allocated cast to pointer of type.

This is a helper macro to call afw_pool_calloc() to allocate memory for a specified type and cast the return pointer to a pointer to that type.

Definition at line 167 of file afw_pool.h.

afw_pool_malloc_type

#define afw_pool_malloc_type	(		instance,
			type,
			xctx
	)		(type *) afw_pool_malloc(instance, sizeof(type), xctx)

Macro to allocate uncleared memory to hold type in pool.

Parameters

instance	of pool.
type	to allocate.
xctx	of caller.

Returns

pointer to memory allocated cast to pointer of type.

This is a helper macro to call afw_pool_malloc() to allocate memory for a specified type and cast the return pointer to a pointer to that type.

Definition at line 182 of file afw_pool.h.

Function Documentation

afw_pool_create()

const afw_pool_t* afw_pool_create	(	const afw_pool_t *	parent,
		afw_xctx_t *	xctx
	)

Create a new pool.

Parameters

parent	of new pool.
xctx	of caller.

Returns

new pool.

A pool created with this function is either thread specific or a multithreaded pool depending on the parent.

If the parent is a thread specific pool, the created pool will also be thread specific. Thread specific pools are single threaded and no locking is allowed. If any of the pool functions are called from other than the specific thread, an error is thrown.

If the parent is a multithread pool, the created pool will also be a multithreaded pool. Calls to lock function will be directed to the nearest ancestor pool that was created with afw_pool_create_multithreaded() or the base pool for the environment.

Definition at line 159 of file afw_pool_singlethreaded.c.

afw_pool_create_debug()

const afw_pool_t* afw_pool_create_debug	(	const afw_pool_t *	parent,
		afw_xctx_t *	xctx,
		const afw_utf8_z_t *	source_z
	)

Debug version of create a new pool.

Parameters

parent	of new pool.
xctx	of caller.
source_z	file:line where function called.

Returns

new pool.

See also

afw_pool_create()

Definition at line 183 of file afw_pool_singlethreaded.c.

afw_pool_create_multithreaded()

const afw_pool_t* afw_pool_create_multithreaded	(	const afw_pool_t *	parent,
		afw_xctx_t *	xctx
	)

Create a new multithreaded pool.

Parameters

parent	of new pool or NULL.
xctx	of caller.

Returns

new pool.

The parent specified must be a multithreaded pool. If NULL is specified, the base pool for the environment is used.

Use paired afw_pool_lock_read()/afw_pool_unlock_read() and afw_pool_lock_write()/afw_pool_unlock_write() as appropriate. Insure this happens using AFW_TRY/AFW_FINALLY.

For example:

afw_pool_lock_write(p); AFW_TRY { ... code that updates things in pool. AFW_CATCH_UNHANDLED { AFW_MARK_UNHANDLED; } AFW_FINALLY { afw_pool_unlock_write(p); } AFW_ENDTRY;

There are helper macros to do this. See:

AFW_POOL_LOCK_READ AFW_POOL_UNLOCK_READ AFW_POOL_LOCK_WRITE AFW_POOL_UNLOCK_WRITE

It is the responsibility of the caller to obtain locks before passing a pool as a parameter to a function unless clearly documented otherwise.

Definition at line 197 of file afw_pool_multithreaded.c.

afw_pool_create_multithreaded_debug()

const afw_pool_t* afw_pool_create_multithreaded_debug	(	const afw_pool_t *	parent,
		afw_xctx_t *	xctx,
		const afw_utf8_z_t *	source_z
	)

Debug version of create a new multithreaded pool.

Parameters

parent	of new pool or NULL.
xctx	of caller.
source_z	file:line where function called.

Returns

new pool.

See also

afw_pool_create_multithreaded()

Definition at line 222 of file afw_pool_multithreaded.c.