modules/portlib/src/main/native/pool/shared/pool.c File Reference

---

Detailed Description

Pool primitives (creation, iteration, deletion, etc.

)

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "hypool.h"

Functions
HyPool *VMCALL	pool_new (U_32 structSize, U_32 minNumberElements, U_32 elementAlignment, UDATA poolFlags, void *(VMCALL *memAlloc)(void *, U_32), void(VMCALL *memFree)(void *, void *), void *userData)
void VMCALL	pool_kill (HyPool *aPool)
	Deallocates all memory associated with a pool.
void *VMCALL	pool_newElement (HyPool *aPool)
	Asks for the address of a new pool element.
void VMCALL	pool_removeElement (HyPool *aPool, void *anElement)
	Deallocates an element from a pool.
void VMCALL	pool_do (HyPool *aPool, void(*aFunction)(void *anElement, void *userData), void *userData)
	Calls a user provided function for each element in the list.
UDATA VMCALL	pool_numElements (HyPool *aPool)
	Returns the number of elements in a given pool.
void *VMCALL	pool_startDo (HyPool *aPool, pool_state *lastHandle)
void *VMCALL	pool_nextDo (pool_state *lastHandle)
void VMCALL	pool_sortFree (HyPool *aPool)
	Sorts the free list of the current pool.
HyPool *VMCALL	pool_forPortLib (U_32 structSize, HyPortLibrary *portLibrary)
	Shortcut for pool_new, using the default malloc/free from the portLibrary.
void VMCALL	pool_clear (HyPool *aPool)
	Clear the contents of a pool but not delete it.

---

Function Documentation

pool_clear

(

HyPool *

aPool

)

Clear the contents of a pool but not delete it.

Note:

Make no assumptions about the contents of the pool after invoking this method (it currently does not zero the memory)

Parameters:

[in]

aPool

The pool to clear

Returns:

none

pool_do	(	HyPool *	aPool,
		void(*)(void *anElement, void *userData)	aFunction,
		void *	userData
	)

Calls a user provided function for each element in the list.

Parameters:

[in]	aPool	The pool to "do" things to
[in]	aFunction	Pointer to function which will "do" things to the elements of aPool
[in]	userData	Pointer to data to be passed to "do" function, along with each pool-element

Returns:

none

See also:

pool_startDo, pool_nextDo

pool_forPortLib	(	U_32	structSize,
		HyPortLibrary *	portLibrary
	)

Shortcut for pool_new, using the default malloc/free from the portLibrary.

Parameters:

[in]	structSize	size of pool-element
[in]	portLibrary

Returns:

pointer to a Pool

See also:

pool_new

pool_kill

(

HyPool *

aPool

)

Deallocates all memory associated with a pool.

Parameters:

[in]

aPool

Pool to be deallocated

Returns:

none

pool_new	(	U_32	structSize,
		U_32	minNumberElements,
		U_32	elementAlignment,
		UDATA	poolFlags,
		void *	(VMCALL *memAlloc)(void *, U_32),
		void(VMCALL *memFree)(void *, void *)	,
		void *	userData
	)

pool_new

Returns a handle to a variable sized pool of structures. This handle should be passed into all other pool functions.

Parameters:

[in]	structSize	Size of the pool-elements
[in]	minNumberElements	If zero, will default to 1
[in]	elementAlignment	If zero will default to MIN_GRANULARITY
[in]	poolFlags
[in]	memAlloc	Allocate function pointer
[in]	memFree	Free function pointer
[in]	userData

Returns:

pointer to a new pool

pool_newElement

(

HyPool *

aPool

)

Asks for the address of a new pool element.

If it succeeds, the address returned will have space for one element of the correct structure size. The contents of the element are undefined. If the current pool is full, a new one will be grafted onto the end of the pool chain and memory from there will be used.

Parameters:

[in]

aPool

Returns:

NULL on error

pointer to a new element otherwise

pool_nextDo

(

pool_state *

lastHandle

)

pool_nextDo

Continue an iteration based on state passed in by lastHandle. It is safe to stop an iteration midway through.

Parameters:

[in]

lastHandle

pointer for current iteration state

Returns:

NULL nothing more to be done

pointer to next element to be processed otherwise

See also:

pool_do, pool_startDo

pool_numElements

(

HyPool *

aPool

)

Returns the number of elements in a given pool.

Parameters:

[in]

aPool

Returns:

0 on error

the number of elements in the pool otherwise

pool_removeElement	(	HyPool *	aPool,
		void *	anElement
	)

Deallocates an element from a pool.

It is safe to call pool_removeElement() while looping over the pool with pool_startDo / pool_nextDo on the element returned by those calls. This is because the free element is always inserted at either the head of the free list or before the nextFree element in the pool_state.

Parameters:

[in]	aPool
[in]	anElement	Pointer to the element to be removed

Returns:

none

pool_sortFree

(

HyPool *

aPool

)

Sorts the free list of the current pool.

(ie: does not follow nextPool pointers...) This is a O(n) most of the time.

Parameters:

[in]

aPool

The pool to be sorted

Returns:

none

pool_startDo	(	HyPool *	aPool,
		pool_state *	lastHandle
	)

pool_startDo

Start of an iteration set that will return when code is to be executed. This is based strongly on pool_sortFreeAndIterateUsed. Pass in a pointer to an empty pool_state and it will be filled in.

Parameters:

[in]	aPool	The pool to "do" things to
[in]	lastHandle

Returns:

NULL

pointer to element otherwise

See also:

pool_do, pool_nextDo

---