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.

Collaboration diagram for Memory Pools:

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

Macros
#define	__MEMORYPOOL_DATA(name, size, align, provider)
	Data part of a static memory pool initializer.
#define	MEMORYPOOL_DECL(name, size, align, provider)
	Static memory pool initializer.
#define	__GUARDEDMEMORYPOOL_DATA(name, size, align)
	Data part of a static guarded memory pool initializer.
#define	GUARDEDMEMORYPOOL_DECL(name, size, align)
	Static guarded memory pool initializer.

Functions
void	chPoolObjectInitAligned (memory_pool_t *mp, size_t size, unsigned align, memgetfunc_t provider)
	Initializes an empty memory pool.
void	chPoolLoadArray (memory_pool_t mp, void p, size_t n)
	Loads a memory pool with an array of static objects.
void *	chPoolAllocI (memory_pool_t *mp)
	Allocates an object from a memory pool.
void *	chPoolAlloc (memory_pool_t *mp)
	Allocates an object from a memory pool.
void	chPoolFreeI (memory_pool_t mp, void objp)
	Releases an object into a memory pool.
void	chPoolFree (memory_pool_t mp, void objp)
	Releases an object into a memory pool.
void	chGuardedPoolObjectInitAligned (guarded_memory_pool_t *gmp, size_t size, unsigned align)
	Initializes an empty guarded memory pool.
void	chGuardedPoolLoadArray (guarded_memory_pool_t gmp, void p, size_t n)
	Loads a guarded memory pool with an array of static objects.
void *	chGuardedPoolAllocTimeoutS (guarded_memory_pool_t *gmp, sysinterval_t timeout)
	Allocates an object from a guarded memory pool.
void *	chGuardedPoolAllocTimeout (guarded_memory_pool_t *gmp, sysinterval_t timeout)
	Allocates an object from a guarded memory pool.
void	chGuardedPoolFree (guarded_memory_pool_t gmp, void objp)
	Releases an object into a guarded memory pool.
static void	chPoolObjectInit (memory_pool_t *mp, size_t size, memgetfunc_t provider)
	Initializes an empty memory pool.
static void	chPoolAdd (memory_pool_t mp, void objp)
	Adds an object to a memory pool.
static void	chPoolAddI (memory_pool_t mp, void objp)
	Adds an object to a memory pool.
static void	chGuardedPoolObjectInit (guarded_memory_pool_t *gmp, size_t size)
	Initializes an empty guarded memory pool.
static cnt_t	chGuardedPoolGetCounterI (guarded_memory_pool_t *gmp)
	Gets the count of objects in a guarded memory pool.
static void *	chGuardedPoolAllocI (guarded_memory_pool_t *gmp)
	Allocates an object from a guarded memory pool.
static void	chGuardedPoolFreeI (guarded_memory_pool_t gmp, void objp)
	Releases an object into a guarded memory pool.
static void	chGuardedPoolFreeS (guarded_memory_pool_t gmp, void objp)
	Releases an object into a guarded memory pool.
static void	chGuardedPoolAdd (guarded_memory_pool_t gmp, void objp)
	Adds an object to a guarded memory pool.
static void	chGuardedPoolAddI (guarded_memory_pool_t gmp, void objp)
	Adds an object to a guarded memory pool.
static void	chGuardedPoolAddS (guarded_memory_pool_t gmp, void objp)
	Adds an object to a guarded memory pool.

Macro Definition Documentation

◆ __MEMORYPOOL_DATA

#define __MEMORYPOOL_DATA	(	name,
		size,
		align,
		provider )

Value:

{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 98 of file chmempools.h.

◆ MEMORYPOOL_DECL

#define MEMORYPOOL_DECL	(	name,
		size,
		align,
		provider )

Value:

memory_pool_t name = __MEMORYPOOL_DATA(name, size, align, provider)

__MEMORYPOOL_DATA

#define __MEMORYPOOL_DATA(name, size, align, provider)

Data part of a static memory pool initializer.

Definition chmempools.h:98

memory_pool_t

Memory pool descriptor.

Definition chmempools.h:64

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 112 of file chmempools.h.

◆ __GUARDEDMEMORYPOOL_DATA

#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 125 of file chmempools.h.

◆ GUARDEDMEMORYPOOL_DECL

#define GUARDEDMEMORYPOOL_DECL	(	name,
		size,
		align )

Value:

guarded_memory_pool_t name = __GUARDEDMEMORYPOOL_DATA(name, size, align)

__GUARDEDMEMORYPOOL_DATA

#define __GUARDEDMEMORYPOOL_DATA(name, size, align)

Data part of a static guarded memory pool initializer.

Definition chmempools.h:125

guarded_memory_pool_t

Guarded memory pool descriptor.

Definition chmempools.h:77

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 139 of file chmempools.h.

Function Documentation

◆ chPoolObjectInitAligned()

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:: Object or module nitializer function.

Definition at line 77 of file chmempools.c.

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

Referenced by chGuardedPoolObjectInitAligned(), and chPoolObjectInit().

◆ chPoolLoadArray()

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 106 of file chmempools.c.

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

Here is the call graph for this function:

◆ chPoolAllocI()

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 129 of file chmempools.c.

References memory_pool_t::align, chDbgAssert, chDbgCheck, chDbgCheckClassI, MEM_IS_ALIGNED, memory_pool_t::next, pool_header::next, memory_pool_t::object_size, and memory_pool_t::provider.

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

◆ chPoolAlloc()

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 161 of file chmempools.c.

References chPoolAllocI(), chSysLock, and chSysUnlock.

Referenced by chThdCreateFromMemoryPool(), and dyn_create_object_pool().

Here is the call graph for this function:

◆ chPoolFreeI()

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 183 of file chmempools.c.

References memory_pool_t::align, chDbgCheck, chDbgCheckClassI, MEM_IS_ALIGNED, memory_pool_t::next, and pool_header::next.

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

◆ chPoolFree()

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 207 of file chmempools.c.

References chPoolFreeI(), chSysLock, and chSysUnlock.

Referenced by chPoolAdd(), chThdRelease(), and dyn_release_object_pool().

Here is the call graph for this function:

◆ chGuardedPoolObjectInitAligned()

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:: Object or module nitializer function.

Definition at line 226 of file chmempools.c.

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

Referenced by chFifoObjectInitAligned(), and chGuardedPoolObjectInit().

Here is the call graph for this function:

◆ chGuardedPoolLoadArray()

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 247 of file chmempools.c.

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

Referenced by chFifoObjectInitAligned(), and chJobObjectInit().

Here is the call graph for this function:

◆ chGuardedPoolAllocTimeoutS()

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 275 of file chmempools.c.

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

Referenced by chFifoTakeObjectTimeoutS(), chGuardedPoolAllocTimeout(), and chJobGetTimeoutS().

Here is the call graph for this function:

◆ chGuardedPoolAllocTimeout()

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 302 of file chmempools.c.

References chGuardedPoolAllocTimeoutS(), chSysLock, and chSysUnlock.

Referenced by chFifoTakeObjectTimeout(), chJobGet(), and chJobGetTimeout().

Here is the call graph for this function:

◆ chGuardedPoolFree()

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 325 of file chmempools.c.

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

Referenced by chFifoReturnObject(), chGuardedPoolAdd(), chJobDispatch(), and chJobDispatchTimeout().

Here is the call graph for this function:

◆ chPoolObjectInit()

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:: Object or module nitializer function.

Definition at line 189 of file chmempools.h.

References chPoolObjectInitAligned(), and PORT_NATURAL_ALIGN.

Referenced by __factory_init().

Here is the call graph for this function:

◆ chPoolAdd()

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 210 of file chmempools.h.

References chPoolFree().

Referenced by chPoolLoadArray().

Here is the call graph for this function:

◆ chPoolAddI()

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 229 of file chmempools.h.

References chPoolFreeI().

Here is the call graph for this function:

◆ chGuardedPoolObjectInit()

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:: Object or module nitializer function.

Definition at line 245 of file chmempools.h.

References chGuardedPoolObjectInitAligned(), and PORT_NATURAL_ALIGN.

Referenced by chJobObjectInit().

Here is the call graph for this function:

◆ chGuardedPoolGetCounterI()

cnt_t chGuardedPoolGetCounterI ( guarded_memory_pool_t * gmp )

inlinestatic

Gets the count of objects in 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 counter of the guard semaphore.

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 260 of file chmempools.h.

References chSemGetCounterI, and guarded_memory_pool_t::sem.

◆ chGuardedPoolAllocI()

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 275 of file chmempools.h.

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

Referenced by chFifoTakeObjectI(), and chJobGetI().

Here is the call graph for this function:

◆ chGuardedPoolFreeI()

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 302 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:

◆ chGuardedPoolFreeS()

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 320 of file chmempools.h.

References chGuardedPoolFreeI(), and chSchRescheduleS().

Referenced by chFifoReturnObjectS(), and chGuardedPoolAddS().

Here is the call graph for this function:

◆ chGuardedPoolAdd()

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 340 of file chmempools.h.

References chGuardedPoolFree().

Referenced by chGuardedPoolLoadArray().

Here is the call graph for this function:

◆ chGuardedPoolAddI()

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 359 of file chmempools.h.

References chGuardedPoolFreeI().

Here is the call graph for this function:

◆ chGuardedPoolAddS()

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 378 of file chmempools.h.

References chGuardedPoolFreeS().

Here is the call graph for this function:

Detailed Description

Operation mode

Data Structures

Macros

Functions

Macro Definition Documentation

◆ __MEMORYPOOL_DATA

◆ MEMORYPOOL_DECL

◆ __GUARDEDMEMORYPOOL_DATA

◆ GUARDEDMEMORYPOOL_DECL

Function Documentation

◆ chPoolObjectInitAligned()

◆ chPoolLoadArray()

◆ chPoolAllocI()

◆ chPoolAlloc()

◆ chPoolFreeI()

◆ chPoolFree()

◆ chGuardedPoolObjectInitAligned()

◆ chGuardedPoolLoadArray()

◆ chGuardedPoolAllocTimeoutS()

◆ chGuardedPoolAllocTimeout()

◆ chGuardedPoolFree()

◆ chPoolObjectInit()

◆ chPoolAdd()

◆ chPoolAddI()

◆ chGuardedPoolObjectInit()

◆ chGuardedPoolGetCounterI()

◆ chGuardedPoolAllocI()

◆ chGuardedPoolFreeI()

◆ chGuardedPoolFreeS()

◆ chGuardedPoolAdd()

◆ chGuardedPoolAddI()

◆ chGuardedPoolAddS()