Collaboration diagram for Memory Pools:

Detailed Description

Memory Pools related APIs and services.

Operation mode

The Memory Pools APIs allow to allocate/free fixed size objects in constant time and reliably without memory fragmentation problems.
Memory Pools do not enforce any alignment constraint on the contained object however the objects must be properly aligned to contain a pointer to void.

Precondition:: In order to use the memory pools APIs the CH_USE_MEMPOOLS option must be enabled in chconf.h.

Data Structures
struct	pool_header
	Memory pool free object header. More...
struct	MemoryPool
	Memory pool descriptor. More...
Functions
void	chPoolInit (MemoryPool *mp, size_t size, memgetfunc_t provider)
	Initializes an empty memory pool.
void	chPoolLoadArray (MemoryPool mp, void p, size_t n)
	Loads a memory pool with an array of static objects.
void *	chPoolAllocI (MemoryPool *mp)
	Allocates an object from a memory pool.
void *	chPoolAlloc (MemoryPool *mp)
	Allocates an object from a memory pool.
void	chPoolFreeI (MemoryPool mp, void objp)
	Releases an object into a memory pool.
void	chPoolFree (MemoryPool mp, void objp)
	Releases an object into a memory pool.
Macro Functions
#define	chPoolAdd(mp, objp) chPoolFree(mp, objp)
	Adds an object to a memory pool.
#define	chPoolAddI(mp, objp) chPoolFreeI(mp, objp)
	Adds an object to a memory pool.
Defines
#define	_MEMORYPOOL_DATA(name, size, provider) {NULL, size, provider}
	Data part of a static memory pool initializer.
#define	MEMORYPOOL_DECL(name, size, provider) MemoryPool name = _MEMORYPOOL_DATA(name, size, provider)
	Static memory pool initializer in hungry mode.

Function Documentation

void chPoolInit	(	MemoryPool *	mp,
		size_t	size,
		memgetfunc_t	provider
	)

Initializes an empty memory pool.

Note:: The size is internally aligned to be a multiple of the stkalign_t type size.

Parameters:

[out]	mp	pointer to a `MemoryPool` structure
[in]	size	the size of the objects contained in this memory pool, the minimum accepted size is the size of a pointer to void.
[in]	provider	memory provider function for the memory pool or `NULL` if the pool is not allowed to grow automatically

Function Class:: Initializer, this function just initializes an object and can be invoked before the kernel is initialized.

Definition at line 57 of file chmempools.c.

References chDbgCheck, MemoryPool::mp_next, MemoryPool::mp_object_size, and MemoryPool::mp_provider.

void chPoolLoadArray	(	MemoryPool *	mp,
		void *	p,
		size_t	n
	)

Loads a memory pool with an array of static objects.

Precondition:: The memory pool must be already been initialized.; The array elements must be of the right size for the specified memory pool.

Postcondition:: The memory pool contains the elements of the input array.

Parameters:

[in]	mp	pointer to a `MemoryPool` structure
[in]	p	pointer to the array first element
[in]	n	number of elements in the array

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 79 of file chmempools.c.

References chDbgCheck, chPoolAdd, and MemoryPool::mp_object_size.

void * chPoolAllocI ( MemoryPool * mp )

Allocates an object from a memory pool.

Precondition:: The memory pool must be already been initialized.

Parameters:

[in] mp pointer to a MemoryPool structure

Returns:: The pointer to the allocated object.

Return values:

NULL	if pool is empty.

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 100 of file chmempools.c.

References chDbgCheck, chDbgCheckClassI(), MemoryPool::mp_next, MemoryPool::mp_object_size, MemoryPool::mp_provider, and pool_header::ph_next.

Referenced by chPoolAlloc().

Here is the call graph for this function:

void * chPoolAlloc ( MemoryPool * mp )

Allocates an object from a memory pool.

Precondition:: The memory pool must be already been initialized.

Parameters:

[in] mp pointer to a MemoryPool structure

Returns:: The pointer to the allocated object.

Return values:

NULL	if pool is empty.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 123 of file chmempools.c.

References chPoolAllocI(), chSysLock, and chSysUnlock.

Referenced by chThdCreateFromMemoryPool().

Here is the call graph for this function:

void chPoolFreeI	(	MemoryPool *	mp,
		void *	objp
	)

Releases an object into a memory pool.

Precondition:: The memory pool must be already been initialized.; The freed object must be of the right size for the specified memory pool.; The object must be properly aligned to contain a pointer to void.

Parameters:

[in]	mp	pointer to a `MemoryPool` structure
[in]	objp	the pointer to the object to be released

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 144 of file chmempools.c.

References chDbgCheck, chDbgCheckClassI(), MemoryPool::mp_next, and pool_header::ph_next.

Referenced by chPoolFree().

Here is the call graph for this function:

void chPoolFree	(	MemoryPool *	mp,
		void *	objp
	)

Releases an object into a memory pool.

Precondition:: The memory pool must be already been initialized.; The freed object must be of the right size for the specified memory pool.; The object must be properly aligned to contain a pointer to void.

Parameters:

[in]	mp	pointer to a `MemoryPool` structure
[in]	objp	the pointer to the object to be released

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 166 of file chmempools.c.

References chPoolFreeI(), chSysLock, and chSysUnlock.

Referenced by chThdRelease().

Here is the call graph for this function:

Define Documentation

#define _MEMORYPOOL_DATA	(	name,
		size,
		provider
	)	{NULL, size, provider}

Data part of a static memory pool initializer.

This macro should be used when statically initializing a memory pool that is part of a bigger structure.

Parameters:

[in]	name	the name of the memory pool variable
[in]	size	size of the memory pool contained objects
[in]	provider	memory provider function for the memory pool

Definition at line 62 of file chmempools.h.

#define MEMORYPOOL_DECL	(	name,
		size,
		provider
	)	MemoryPool name = _MEMORYPOOL_DATA(name, size, provider)

Static memory pool initializer in hungry mode.

Statically initialized memory pools require no explicit initialization using chPoolInit().

Parameters:

[in]	name	the name of the memory pool variable
[in]	size	size of the memory pool contained objects
[in]	provider	memory provider function for the memory pool or `NULL` if the pool is not allowed to grow automatically

Definition at line 75 of file chmempools.h.

#define chPoolAdd	(	mp,
		objp
	)	chPoolFree(mp, objp)

Adds an object to a memory pool.

Precondition:: The memory pool must be already been initialized.; The added object must be of the right size for the specified memory pool.; The added object must be memory aligned to the size of stkalign_t type.

Note:: This function is just an alias for chPoolFree() and has been added for clarity.

Parameters:

[in]	mp	pointer to a `MemoryPool` structure
[in]	objp	the pointer to the object to be added

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 97 of file chmempools.h.

Referenced by chPoolLoadArray().

#define chPoolAddI	(	mp,
		objp
	)	chPoolFreeI(mp, objp)

Adds an object to a memory pool.

Precondition:: The memory pool must be already been initialized.; The added object must be of the right size for the specified memory pool.; The added object must be memory aligned to the size of stkalign_t type.

Note:: This function is just an alias for chPoolFree() and has been added for clarity.

Parameters:

[in]	mp	pointer to a `MemoryPool` structure
[in]	objp	the pointer to the object to be added

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 114 of file chmempools.h.

Detailed Description

Operation mode

Data Structures

Functions

Macro Functions

Defines

Function Documentation

Define Documentation