modules/portlib/src/main/native/include/shared/hypool.h File Reference

---

Detailed Description

Pool Header.

#include "hycomp.h"
#include "hyport.h"

Data Structures
struct	HyPool
struct	HyPoolState
Functions
HY_CFUNC 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.
HY_CFUNC void VMCALL	pool_removeElement (HyPool *aPool, void *anElement)
	Deallocates an element from a pool.
HY_CFUNC UDATA VMCALL	pool_numElements (HyPool *aPool)
	Returns the number of elements in a given pool.
HY_CFUNC void *VMCALL	pool_newElement (HyPool *aPool)
	Asks for the address of a new pool element.
HY_CFUNC HyPool *VMCALL	pool_forPortLib (U_32 structSize, HyPortLibrary *portLibrary)
	Shortcut for pool_new, using the default malloc/free from the portLibrary.
HY_CFUNC void VMCALL	pool_kill (HyPool *aPool)
	Deallocates all memory associated with a pool.
HY_CFUNC void VMCALL	pool_sortFree (HyPool *aPool)
	Sorts the free list of the current pool.
HY_CFUNC void VMCALL	pool_clear (HyPool *aPool)
	Clear the contents of a pool but not delete it.
HY_CFUNC UDATA VMCALL	pool_capacity (HyPool *aPool)
	Returns the total capacity of a pool.
HY_CFUNC UDATA VMCALL	pool_ensureCapacity (HyPool *aPool, UDATA newCapacity)
	Ensures that the pool is large enough for newCapacity elements.

---

Function Documentation

HY_CFUNC UDATA VMCALL pool_capacity

(

HyPool *

aPool

)

Returns the total capacity of a pool.

Parameters:

[in]

aPool

The pool

Returns:

0 on error

numElements in aPool otherwise

HY_CFUNC void VMCALL 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

HY_CFUNC void VMCALL 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

HY_CFUNC UDATA VMCALL pool_ensureCapacity	(	HyPool *	aPool,
		UDATA	newCapacity
	)

Ensures that the pool is large enough for newCapacity elements.

This has the side effect of setting the POOL_NEVER_FREE_PUDDLES flag. Without this, the pool could shrink back down to its original size. Note that this does not take into account the number of elements already used in the pool.

Parameters:

[in]	aPool	The pool
[in]	newCapacity	The desired new-size of the pool

Returns:

0 on success

-1 on failure

HY_CFUNC HyPool* VMCALL 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

HY_CFUNC void VMCALL pool_kill

(

HyPool *

aPool

)

Deallocates all memory associated with a pool.

Parameters:

[in]

aPool

Pool to be deallocated

Returns:

none

HY_CFUNC void* VMCALL 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

HY_CFUNC UDATA VMCALL 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

HY_CFUNC void VMCALL 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

HY_CFUNC void VMCALL 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

---