ChibiOS/NIL  3.2.2
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 cnt_t chGuardedPoolGetCounterI (guarded_memory_pool_t *gmp)
 Gets the count of objects in a 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]namethe name of the memory pool variable
[in]sizesize of the memory pool contained objects
[in]alignrequired memory alignment
[in]providermemory provider function for the memory pool

Definition at line 98 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]namethe name of the memory pool variable
[in]sizesize of the memory pool contained objects
[in]alignrequired memory alignment
[in]providermemory 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.

#define _GUARDEDMEMORYPOOL_DATA (   name,
  size,
  align 
)
Value:
{ \
_SEMAPHORE_DATA(name.sem, (cnt_t)0), \
_MEMORYPOOL_DATA(NULL, size, align, NULL) \
}
#define _MEMORYPOOL_DATA(name, size, align, provider)
Data part of a static memory pool initializer.
Definition: chmempools.h:98
#define _SEMAPHORE_DATA(name, n)
Data part of a static semaphore initializer.
Definition: ch.h:1071

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]namethe name of the memory pool variable
[in]sizesize of the memory pool contained objects
[in]alignrequired memory alignment

Definition at line 125 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]namethe name of the guarded memory pool variable
[in]sizesize of the memory pool contained objects
[in]alignrequired memory alignment

Definition at line 139 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]mppointer to a memory_pool_t structure
[in]sizethe size of the objects contained in this memory pool, the minimum accepted size is the size of a pointer to void.
[in]alignrequired memory alignment
[in]providermemory 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, MEM_IS_VALID_ALIGNMENT, 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]mppointer to a memory_pool_t structure
[in]ppointer to the array first element
[in]nnumber 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:

void * chPoolAllocI ( memory_pool_t mp)

Allocates an object from a memory pool.

Precondition
The memory pool must already be initialized.
Parameters
[in]mppointer to a memory_pool_t structure
Returns
The pointer to the allocated object.
Return values
NULLif 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, 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]mppointer to a memory_pool_t structure
Returns
The pointer to the allocated object.
Return values
NULLif 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.

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]mppointer to a memory_pool_t structure
[in]objpthe 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, 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]mppointer to a memory_pool_t structure
[in]objpthe 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().

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]gmppointer to a guarded_memory_pool_t structure
[in]sizethe size of the objects contained in this guarded memory pool, the minimum accepted size is the size of a pointer to void.
[in]alignrequired memory alignment
Function Class:Initializer, this function just initializes an object and can be invoked before the kernel is initialized.

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:

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]gmppointer to a guarded_memory_pool_t structure
[in]ppointer to the array first element
[in]nnumber 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().

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]gmppointer to a guarded_memory_pool_t structure
[in]timeoutthe 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
NULLif 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(), 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]gmppointer to a guarded_memory_pool_t structure
[in]timeoutthe 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
NULLif 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().

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]gmppointer to a guarded_memory_pool_t structure
[in]objpthe 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(), 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]mppointer to a memory_pool_t structure
[in]sizethe size of the objects contained in this memory pool, the minimum accepted size is the size of a pointer to void.
[in]providermemory 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 189 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]mppointer to a memory_pool_t structure
[in]objpthe 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:

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]mppointer to a memory_pool_t structure
[in]objpthe 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:

static void chGuardedPoolObjectInit ( guarded_memory_pool_t gmp,
size_t  size 
)
inlinestatic

Initializes an empty guarded memory pool.

Parameters
[out]gmppointer to a guarded_memory_pool_t structure
[in]sizethe 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 245 of file chmempools.h.

References chGuardedPoolObjectInitAligned().

Here is the call graph for this function:

static 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]gmppointer to a guarded_memory_pool_t structure
Returns
The number of objects.
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.

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]gmppointer to a guarded_memory_pool_t structure
Returns
The pointer to the allocated object.
Return values
NULLif 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 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]gmppointer to a guarded_memory_pool_t structure
[in]objpthe 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 299 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]gmppointer to a guarded_memory_pool_t structure
[in]objpthe 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 317 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]gmppointer to a guarded_memory_pool_t structure
[in]objpthe 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 337 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]gmppointer to a guarded_memory_pool_t structure
[in]objpthe 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 356 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]gmppointer to a guarded_memory_pool_t structure
[in]objpthe 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 375 of file chmempools.h.

References chGuardedPoolFreeS().

Here is the call graph for this function: