pool.h File Reference

Pool object management unit. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

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

POOL_allocate()

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_create()

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(..)

POOL_destroy()

void POOL_destroy

(

Pool *

pool

)

Release the specified object pool allocator.

Parameters

pool	Object pool allocator to release

See also

POOL_create(..)

POOL_find()

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

POOL_getFirst()

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(..)

POOL_getFree()

u16 POOL_getFree

(

Pool *

pool

)

Returns

the number of free object in the pool

Parameters

pool	Object pool allocator

POOL_getNumAllocated()

u16 POOL_getNumAllocated

(

Pool *

pool

)

Returns

the number of allocated object in the pool

Parameters

pool	Object pool allocator

POOL_release()

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(..)

POOL_reset()

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)

Here is the call graph for this function: