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_CFG_USE_MEMPOOLS option must be enabled in chconf.h.

Note: Compatible with RT and NIL.

Macros
#define	_MEMORYPOOL_DATA(name, size, align, provider) {NULL, size, align, provider}
	Data part of a static memory pool initializer. More...

#define	MEMORYPOOL_DECL(name, size, align, provider) memory_pool_t name = _MEMORYPOOL_DATA(name, size, align, provider)
	Static memory pool initializer. More...

#define	_GUARDEDMEMORYPOOL_DATA(name, size, align)
	Data part of a static guarded memory pool initializer. More...

#define	GUARDEDMEMORYPOOL_DECL(name, size, align) guarded_memory_pool_t name = _GUARDEDMEMORYPOOL_DATA(name, size, align)
	Static guarded memory pool initializer. More...

Data Structures
struct	pool_header
	Memory pool free object header. More...

struct	memory_pool_t
	Memory pool descriptor. More...

struct	guarded_memory_pool_t
	Guarded memory pool descriptor. More...

Functions
void	chPoolObjectInitAligned (memory_pool_t *mp, size_t size, unsigned align, memgetfunc_t provider)
	Initializes an empty memory pool. More...

void	chPoolLoadArray (memory_pool_t mp, void p, size_t n)
	Loads a memory pool with an array of static objects. More...

void *	chPoolAllocI (memory_pool_t *mp)
	Allocates an object from a memory pool. More...

void *	chPoolAlloc (memory_pool_t *mp)
	Allocates an object from a memory pool. More...

void	chPoolFreeI (memory_pool_t mp, void objp)
	Releases an object into a memory pool. More...

void	chPoolFree (memory_pool_t mp, void objp)
	Releases an object into a memory pool. More...

void	chGuardedPoolObjectInitAligned (guarded_memory_pool_t *gmp, size_t size, unsigned align)
	Initializes an empty guarded memory pool. More...

void	chGuardedPoolLoadArray (guarded_memory_pool_t gmp, void p, size_t n)
	Loads a guarded memory pool with an array of static objects. More...

void *	chGuardedPoolAllocTimeoutS (guarded_memory_pool_t *gmp, sysinterval_t timeout)
	Allocates an object from a guarded memory pool. More...

void *	chGuardedPoolAllocTimeout (guarded_memory_pool_t *gmp, sysinterval_t timeout)
	Allocates an object from a guarded memory pool. More...

void	chGuardedPoolFree (guarded_memory_pool_t gmp, void objp)
	Releases an object into a guarded memory pool. More...

static void	chPoolObjectInit (memory_pool_t *mp, size_t size, memgetfunc_t provider)
	Initializes an empty memory pool. More...

static void	chPoolAdd (memory_pool_t mp, void objp)
	Adds an object to a memory pool. More...

static void	chPoolAddI (memory_pool_t mp, void objp)
	Adds an object to a memory pool. More...

static void	chGuardedPoolObjectInit (guarded_memory_pool_t *gmp, size_t size)
	Initializes an empty guarded memory pool. More...

static void *	chGuardedPoolAllocI (guarded_memory_pool_t *gmp)
	Allocates an object from a guarded memory pool. More...

static void	chGuardedPoolFreeI (guarded_memory_pool_t gmp, void objp)
	Releases an object into a guarded memory pool. More...

static void	chGuardedPoolFreeS (guarded_memory_pool_t gmp, void objp)
	Releases an object into a guarded memory pool. More...

static void	chGuardedPoolAdd (guarded_memory_pool_t gmp, void objp)
	Adds an object to a guarded memory pool. More...

static void	chGuardedPoolAddI (guarded_memory_pool_t gmp, void objp)
	Adds an object to a guarded memory pool. More...

static void	chGuardedPoolAddS (guarded_memory_pool_t gmp, void objp)
	Adds an object to a guarded memory pool. More...

Macro Definition Documentation

#define _MEMORYPOOL_DATA	(	name,
		size,
		align,
		provider
	)	{NULL, size, align, 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]	align	required memory alignment
[in]	provider	memory provider function for the memory pool

Definition at line 102 of file chmempools.h.

#define MEMORYPOOL_DECL	(	name,
		size,
		align,
		provider
	)	memory_pool_t name = _MEMORYPOOL_DATA(name, size, align, provider)

Static memory pool initializer.

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]	align	required memory alignment
[in]	provider	memory provider function for the memory pool or `NULL` if the pool is not allowed to grow automatically

Definition at line 116 of file chmempools.h.

#define _GUARDEDMEMORYPOOL_DATA	(	name,
		size,
		align
	)

Value:

{                        \
  _SEMAPHORE_DATA(name.sem, (cnt_t)0),                                      \
  _MEMORYPOOL_DATA(NULL, size, align, NULL)                                 \
}

Data part of a static guarded 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]	align	required memory alignment

Definition at line 129 of file chmempools.h.

#define GUARDEDMEMORYPOOL_DECL	(	name,
		size,
		align
	)	guarded_memory_pool_t name = _GUARDEDMEMORYPOOL_DATA(name, size, align)

Static guarded memory pool initializer.

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

Parameters

[in]	name	the name of the guarded memory pool variable
[in]	size	size of the memory pool contained objects
[in]	align	required memory alignment

Definition at line 143 of file chmempools.h.

Function Documentation

void chPoolObjectInitAligned	(	memory_pool_t *	mp,
		size_t	size,
		unsigned	align,
		memgetfunc_t	provider
	)

Initializes an empty memory pool.

Parameters

[out]	mp	pointer to a `memory_pool_t` 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]	align	required memory alignment
[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 77 of file chmempools.c.

References memory_pool_t::align, chDbgCheck, memory_pool_t::next, memory_pool_t::object_size, and memory_pool_t::provider.

Referenced by chGuardedPoolObjectInitAligned(), and chPoolObjectInit().

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

Loads a memory pool with an array of static objects.

Precondition: The memory pool must already be initialized.; The array elements must be of the right size for the specified memory pool.; The array elements size must be a multiple of the alignment requirement for the pool.

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

Parameters

[in]	mp	pointer to a `memory_pool_t` 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 103 of file chmempools.c.

References chDbgCheck, chPoolAdd(), and memory_pool_t::object_size.

Here is the call graph for this function:

void * chPoolAllocI ( memory_pool_t * mp )

Allocates an object from a memory pool.

Precondition: The memory pool must already be initialized.

Parameters

[in] mp pointer to a memory_pool_t 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 126 of file chmempools.c.

References memory_pool_t::align, chDbgCheck, chDbgCheckClassI(), pool_header::next, memory_pool_t::next, memory_pool_t::object_size, and memory_pool_t::provider.

Referenced by chGuardedPoolAllocI(), chGuardedPoolAllocTimeoutS(), and chPoolAlloc().

Here is the call graph for this function:

void * chPoolAlloc ( memory_pool_t * mp )

Allocates an object from a memory pool.

Precondition: The memory pool must already be initialized.

Parameters

[in] mp pointer to a memory_pool_t 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 155 of file chmempools.c.

References chPoolAllocI(), chSysLock(), and chSysUnlock().

Referenced by chThdCreateFromMemoryPool().

Here is the call graph for this function:

void chPoolFreeI	(	memory_pool_t *	mp,
		void *	objp
	)

Releases an object into a memory pool.

Precondition: The memory pool must already be initialized.; The freed object must be of the right size for the specified memory pool.; The added object must be properly aligned.

Parameters

[in]	mp	pointer to a `memory_pool_t` 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 177 of file chmempools.c.

References memory_pool_t::align, chDbgAssert, chDbgCheck, chDbgCheckClassI(), MEM_ALIGN_MASK, pool_header::next, and memory_pool_t::next.

Referenced by chGuardedPoolFreeI(), chPoolAddI(), and chPoolFree().

Here is the call graph for this function:

void chPoolFree	(	memory_pool_t *	mp,
		void *	objp
	)

Releases an object into a memory pool.

Precondition: The memory pool must already be initialized.; The freed object must be of the right size for the specified memory pool.; The added object must be properly aligned.

Parameters

[in]	mp	pointer to a `memory_pool_t` 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 202 of file chmempools.c.

References chPoolFreeI(), chSysLock(), and chSysUnlock().

Referenced by chPoolAdd(), and chThdRelease().

Here is the call graph for this function:

void chGuardedPoolObjectInitAligned	(	guarded_memory_pool_t *	gmp,
		size_t	size,
		unsigned	align
	)

Initializes an empty guarded memory pool.

Parameters

[out]	gmp	pointer to a `guarded_memory_pool_t` structure
[in]	size	the size of the objects contained in this guarded memory pool, the minimum accepted size is the size of a pointer to void.
[in]	align	required memory alignment

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

Definition at line 221 of file chmempools.c.

References chPoolObjectInitAligned(), chSemObjectInit(), guarded_memory_pool_t::pool, and guarded_memory_pool_t::sem.

Referenced by chFifoObjectInit(), and chGuardedPoolObjectInit().

Here is the call graph for this function:

void chGuardedPoolLoadArray	(	guarded_memory_pool_t *	gmp,
		void *	p,
		size_t	n
	)

Loads a guarded memory pool with an array of static objects.

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

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

Parameters

[in]	gmp	pointer to a `guarded_memory_pool_t` 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 242 of file chmempools.c.

References chDbgCheck, chGuardedPoolAdd(), memory_pool_t::object_size, and guarded_memory_pool_t::pool.

Referenced by chFifoObjectInit().

Here is the call graph for this function:

void * chGuardedPoolAllocTimeoutS	(	guarded_memory_pool_t *	gmp,
		sysinterval_t	timeout
	)

Allocates an object from a guarded memory pool.

Precondition: The guarded memory pool must already be initialized.

Parameters

[in]	gmp	pointer to a `guarded_memory_pool_t` structure
[in]	timeout	the number of ticks before the operation timeouts, the following special values are allowed: TIME_IMMEDIATE immediate timeout. TIME_INFINITE no timeout.

Returns: The pointer to the allocated object.

Return values

NULL	if the operation timed out.

Function Class:: This is an S-Class API, this function can be invoked from within a system lock zone by threads only.

Definition at line 270 of file chmempools.c.

References chPoolAllocI(), chSemWaitTimeoutS(), MSG_OK, guarded_memory_pool_t::pool, and guarded_memory_pool_t::sem.

Referenced by chFifoTakeObjectTimeoutS(), and chGuardedPoolAllocTimeout().

Here is the call graph for this function:

void * chGuardedPoolAllocTimeout	(	guarded_memory_pool_t *	gmp,
		sysinterval_t	timeout
	)

Allocates an object from a guarded memory pool.

Precondition: The guarded memory pool must already be initialized.

Parameters

[in]	gmp	pointer to a `guarded_memory_pool_t` structure
[in]	timeout	the number of ticks before the operation timeouts, the following special values are allowed: TIME_IMMEDIATE immediate timeout. TIME_INFINITE no timeout.

Returns: The pointer to the allocated object.

Return values

NULL	if the operation timed out.

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

Definition at line 297 of file chmempools.c.

References chGuardedPoolAllocTimeoutS(), chSysLock(), and chSysUnlock().

Referenced by chFifoTakeObjectTimeout().

Here is the call graph for this function:

void chGuardedPoolFree	(	guarded_memory_pool_t *	gmp,
		void *	objp
	)

Releases an object into a guarded memory pool.

Precondition: The guarded memory pool must already be initialized.; The freed object must be of the right size for the specified guarded memory pool.; The added object must be properly aligned.

Parameters

[in]	gmp	pointer to a `guarded_memory_pool_t` 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 320 of file chmempools.c.

References chGuardedPoolFreeI(), chSchRescheduleS(), chSysLock(), and chSysUnlock().

Referenced by chFifoReturnObject(), and chGuardedPoolAdd().

Here is the call graph for this function:

static void chPoolObjectInit	(	memory_pool_t *	mp,
		size_t	size,
		memgetfunc_t	provider
	)

inlinestatic

Initializes an empty memory pool.

Parameters

[out]	mp	pointer to a `memory_pool_t` 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 193 of file chmempools.h.

References chPoolObjectInitAligned().

Referenced by _factory_init().

Here is the call graph for this function:

static void chPoolAdd	(	memory_pool_t *	mp,
		void *	objp
	)

inlinestatic

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 properly aligned.

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

Parameters

[in]	mp	pointer to a `memory_pool_t` 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 214 of file chmempools.h.

References chPoolFree().

Referenced by chPoolLoadArray().

Here is the call graph for this function:

static void chPoolAddI	(	memory_pool_t *	mp,
		void *	objp
	)

inlinestatic

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 properly aligned.

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

Parameters

[in]	mp	pointer to a `memory_pool_t` 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 233 of file chmempools.h.

References chPoolFreeI().

Here is the call graph for this function:

static void chGuardedPoolObjectInit	(	guarded_memory_pool_t *	gmp,
		size_t	size
	)

inlinestatic

Initializes an empty guarded memory pool.

Parameters

[out]	gmp	pointer to a `guarded_memory_pool_t` structure
[in]	size	the size of the objects contained in this guarded memory pool, the minimum accepted size is the size of a pointer to void.

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

Definition at line 249 of file chmempools.h.

References chGuardedPoolObjectInitAligned().

Here is the call graph for this function:

static void* chGuardedPoolAllocI ( guarded_memory_pool_t * gmp )

inlinestatic

Allocates an object from a guarded memory pool.

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

Parameters

[in] gmp pointer to a guarded_memory_pool_t structure

Returns: The pointer to the allocated object.

Return values

NULL	if the 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 265 of file chmempools.h.

References chDbgAssert, chPoolAllocI(), chSemFastWaitI(), chSemGetCounterI(), guarded_memory_pool_t::pool, and guarded_memory_pool_t::sem.

Referenced by chFifoTakeObjectI().

Here is the call graph for this function:

static void chGuardedPoolFreeI	(	guarded_memory_pool_t *	gmp,
		void *	objp
	)

inlinestatic

Releases an object into a guarded memory pool.

Precondition: The guarded memory pool must already be initialized.; The freed object must be of the right size for the specified guarded memory pool.; The added object must be properly aligned.

Parameters

[in]	gmp	pointer to a `guarded_memory_pool_t` 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 289 of file chmempools.h.

References chPoolFreeI(), chSemSignalI(), guarded_memory_pool_t::pool, and guarded_memory_pool_t::sem.

Referenced by chFifoReturnObjectI(), chGuardedPoolAddI(), chGuardedPoolFree(), and chGuardedPoolFreeS().

Here is the call graph for this function:

static void chGuardedPoolFreeS	(	guarded_memory_pool_t *	gmp,
		void *	objp
	)

inlinestatic

Releases an object into a guarded memory pool.

Precondition: The guarded memory pool must already be initialized.; The freed object must be of the right size for the specified guarded memory pool.; The added object must be properly aligned.

Parameters

[in]	gmp	pointer to a `guarded_memory_pool_t` structure
[in]	objp	the pointer to the object to be released

Function Class:: This is an S-Class API, this function can be invoked from within a system lock zone by threads only.

Definition at line 307 of file chmempools.h.

References chGuardedPoolFreeI(), and chSchRescheduleS().

Referenced by chFifoReturnObjectS(), and chGuardedPoolAddS().

Here is the call graph for this function:

static void chGuardedPoolAdd	(	guarded_memory_pool_t *	gmp,
		void *	objp
	)

inlinestatic

Adds an object to a guarded memory pool.

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

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

Parameters

[in]	gmp	pointer to a `guarded_memory_pool_t` 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 327 of file chmempools.h.

References chGuardedPoolFree().

Referenced by chGuardedPoolLoadArray().

Here is the call graph for this function:

static void chGuardedPoolAddI	(	guarded_memory_pool_t *	gmp,
		void *	objp
	)

inlinestatic

Adds an object to a guarded memory pool.

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

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

Parameters

[in]	gmp	pointer to a `guarded_memory_pool_t` 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 346 of file chmempools.h.

References chGuardedPoolFreeI().

Here is the call graph for this function:

static void chGuardedPoolAddS	(	guarded_memory_pool_t *	gmp,
		void *	objp
	)

inlinestatic

Adds an object to a guarded memory pool.

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

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

Parameters

[in]	gmp	pointer to a `guarded_memory_pool_t` structure
[in]	objp	the pointer to the object to be added

Function Class:: This is an S-Class API, this function can be invoked from within a system lock zone by threads only.

Definition at line 365 of file chmempools.h.

References chGuardedPoolFreeS().

Here is the call graph for this function:

Detailed Description

Operation mode

Macros

Data Structures

Functions

Macro Definition Documentation

Function Documentation