Pool object management unit. More...

Classes
struct	Pool
	Object pool allocator structure. More...
Functions
Pool *	POOL_create (u16 size, u16 objectSize)
	Create and allocate a new object pool allocator.
void	POOL_destroy (Pool *pool)
	Release the specified object pool allocator.
void	POOL_reset (Pool *pool, bool clear)
	Reset the 'object' pool allocator.
void *	POOL_allocate (Pool *pool)
	Allocate a new 'object' from the specified object pool.
void	POOL_release (Pool pool, void object, bool maintainCoherency)
	Release an objet from the specified object pool.
u16	POOL_getFree (Pool *pool)
u16	POOL_getNumAllocated (Pool *pool)
void **	POOL_getFirst (Pool *pool)
s16	POOL_find (Pool pool, void object)

Detailed Description

Pool object management unit.

Author:: Stephane Dallongeville

Date:: 02/2022

This unit provides methods to manage dynamic object allocation.

You can use Pool object to handle dynamic allocation from a fixed set of objects.
For instance if you may need to handle dynamically bullets for your game and you want to have at max 20 bullets, you can handle it that way:

 Pool* bulletPool = POOL_create(20, sizeof(Bullet));
 ...
 // create a new bullet
 Bullet* bullet = POOL_allocate(bulletPool);
 // check if bullet was correctly created and do your stuff..
 if (bullet != NULL)
 {
    ...
 }
 ...
 // release your bullet
 POOL_release(bulletPool, bullet);

Pool object is also very useful for fast iteration over allocated objects:

 Bullet** bullets = POOL_getFirst(bulletPool);
 u16 num = POOL_getNumAllocated(bulletPool);
 while(num--)
 {
    Bullet* bullet = *bullets++;
    // do whatever you need on your bullet
    ...
 }

Function Documentation

void* POOL_allocate ( Pool * pool )

Allocate a new 'object' from the specified object pool.

Parameters:

pool	Object pool allocator

Returns:: the allocated object or NULL if an error occured (no more available object in pool or invalid pool)

See also:: POOL_release(..)

Pool* POOL_create	(	u16	size,
		u16	objectSize
	)

Create and allocate a new object pool allocator.

Parameters:

size	the capacity of the pool (in number of object)
objectSize	the size of a single object (usually you should use sizeof(Struct) here, always aligned on 2)

Returns:: the new created object pool or NULL if there is not enough memory available for that.

See also:: POOL_destroy(..); POOL_reset(..)

void POOL_destroy ( Pool * pool )

Release the specified object pool allocator.

Parameters:

pool	Object pool allocator to release

See also:: POOL_create(..)

s16 POOL_find	(	Pool *	pool,
		void *	object
	)

Returns:: the position of an object in the alloc stack or -1 if the object isn't found (useful for debug purpose mainly)

Parameters:

pool	Object pool allocator
object	Object to get slot position

void** POOL_getFirst ( Pool * pool )

Returns:: the start position of allocated objects in the alloc stack (useful to iterate over all allocated objects)

Parameters:

pool	Object pool allocator

See also:: POOL_getNumAllocated(..)

u16 POOL_getFree ( Pool * pool )

Returns:: the number of free object in the pool

Parameters:

pool	Object pool allocator

u16 POOL_getNumAllocated ( Pool * pool )

Returns:: the number of allocated object in the pool

Parameters:

pool	Object pool allocator

void POOL_release	(	Pool *	pool,
		void *	object,
		bool	maintainCoherency
	)

Release an objet from the specified object pool.

Parameters:

pool	Object pool allocator
object	Object to release
maintainCoherency	set it to TRUE if you want to keep coherency for stack iteration (see POOL_getFirst()). Set it to FALSE for faster release process if you don't require object iteration through alloc stack.

See also:: POOL_allocate(..)

void POOL_reset	(	Pool *	pool,
		bool	clear
	)

Reset the 'object' pool allocator.

Parameters:

pool	Object pool allocator to reset
clear	if set to TRUE then objects memory is cleared (initialized to 0)

Classes

Functions

Detailed Description

Function Documentation