QP/C  6.0.2
qmpool.h File Reference

QP native, platform-independent memory pool QMPool interface. More...

Go to the source code of this file.

Data Structures

struct  QMPool
 Native QF Memory Pool. More...
 

Macros

#define QF_MPOOL_SIZ_SIZE   2
 macro to override the default ::QMPoolSize size. More...
 
#define QF_MPOOL_CTR_SIZE   2
 macro to override the default ::QMPoolCtr size. More...
 
#define QF_MPOOL_EL(evType_)   struct { void *sto_[((sizeof(evType_) - 1U)/sizeof(void*)) + 1U]; }
 Memory pool element to allocate correctly aligned storage for QMPool class. More...
 

Typedefs

typedef uint16_t QMPoolSize
 
typedef uint16_t QMPoolCtr
 

Functions

void QMPool_init (QMPool *const me, void *const poolSto, uint_fast32_t poolSize, uint_fast16_t blockSize)
 Initializes the native QF memory pool. More...
 
void * QMPool_get (QMPool *const me, uint_fast16_t const margin)
 Obtains a memory block from a memory pool. More...
 
void QMPool_put (QMPool *const me, void *b)
 Recycles a memory block back to a memory pool. More...
 

Detailed Description

QP native, platform-independent memory pool QMPool interface.

Definition in file qmpool.h.


Data Structure Documentation

◆ QMPool

struct QMPool

Native QF Memory Pool.

Description
A fixed block-size memory pool is a very fast and efficient data structure for dynamic allocation of fixed block-size chunks of memory. A memory pool offers fast and deterministic allocation and recycling of memory blocks and is not subject to fragmenation.

The QMPool class describes the native QF memory pool, which can be used as the event pool for dynamic event allocation, or as a fast, deterministic fixed block-size heap for any other objects in your application.
Note
QMPool contains only data members for managing a memory pool, but does not contain the pool storage, which must be provided externally during the pool initialization.
The native QF event pool is configured by defining the macro QF_EPOOL_TYPE_ as QMPool in the specific QF port header file.

Definition at line 118 of file qmpool.h.

Data Fields
void *volatile free_head The head of the linked list of free blocks.
void * start the original start this pool
void * end the last memory block managed by this memory pool
QMPoolSize blockSize maximum block size (in bytes)
QMPoolCtr nTot total number of blocks
QMPoolCtr volatile nFree number of free blocks remaining
QMPoolCtr nMin minimum number of free blocks ever present in this pool
Description
this attribute remembers the low watermark of the pool, which provides a valuable information for sizing event pools.
See also
QF_getPoolMin().

Macro Definition Documentation

◆ QF_MPOOL_SIZ_SIZE

#define QF_MPOOL_SIZ_SIZE   2

macro to override the default ::QMPoolSize size.

Valid values 1, 2, or 4; default 2

Definition at line 48 of file qmpool.h.

◆ QF_MPOOL_CTR_SIZE

#define QF_MPOOL_CTR_SIZE   2

macro to override the default ::QMPoolCtr size.

Valid values 1, 2, or 4; default 2

Definition at line 75 of file qmpool.h.

◆ QF_MPOOL_EL

#define QF_MPOOL_EL (   evType_)    struct { void *sto_[((sizeof(evType_) - 1U)/sizeof(void*)) + 1U]; }

Memory pool element to allocate correctly aligned storage for QMPool class.

Parameters
[in]evType_event type (name of the subclass of QEvt)

Definition at line 165 of file qmpool.h.

Function Documentation

◆ QMPool_init()

void QMPool_init ( QMPool *const  me,
void *const  poolSto,
uint_fast32_t  poolSize,
uint_fast16_t  blockSize 
)

Initializes the native QF memory pool.

Description
Initialize a fixed block-size memory pool by providing it with the pool memory to manage, size of this memory, and the block size.
Parameters
[in,out]mepointer (see Object Orientation)
[in]poolStopointer to the memory buffer for pool storage
[in]poolSizesize of the storage buffer in bytes
[in]blockSizefixed-size of the memory blocks in bytes
Attention
The caller of QMPool::init() must make sure that the poolSto pointer is properly aligned. In particular, it must be possible to efficiently store a pointer at the location pointed to by poolSto. Internally, the QMPool_init() function rounds up the block size blockSize so that it can fit an integer number of pointers. This is done to achieve proper alignment of the blocks within the pool.
Note
Due to the rounding of block size the actual capacity of the pool might be less than (poolSize / blockSize). You can check the capacity of the pool by calling the QF_getPoolMin() function.
This function is not protected by a critical section, because it is intended to be called only during the initialization of the system, when interrupts are not allowed yet.
Many QF ports use memory pools to implement the event pools.
Usage
The following example illustrates how to invoke QMPool_init():
QMPool myMemPool1; /* memory pool object #1 (global) */
static uint8_t memPoolSto1[512]; /* storage for a memory pool #1 */
QMPool myMemPool2; /* memory pool object #2 (global) */
static uint8_t memPoolSto2[1024]; /* storage for a memory pool #2 */
QMPool_init(&myMemPool1,
memPoolSto1,
sizeof(memPoolSto1),
10U); /* memory blocks of 10 bytes each */
QMPool_init(&myMemPool2,
memPoolSto2,
sizeof(memPoolSto2),
25U); /* memory blocks of 25 bytes each */
Precondition
The memory block must be valid and the poolSize must fit at least one free block and the blockSize must not be too close to the top of the dynamic range

Definition at line 85 of file qf_mem.c.

◆ QMPool_get()

void* QMPool_get ( QMPool *const  me,
uint_fast16_t const  margin 
)

Obtains a memory block from a memory pool.

Description
The function allocates a memory block from the pool and returns a pointer to the block back to the caller.
Parameters
[in,out]mepointer (see Object Orientation)
[in]marginthe minimum number of unused blocks still available in the pool after the allocation.
Note
This function can be called from any task level or ISR level.
The memory pool me must be initialized before any events can be requested from it. Also, the QMPool_get() function uses internally a QF critical section, so you should be careful not to call it from within a critical section when nesting of critical section is not supported.
Attention
An allocated block must be later returned back to the same pool from which it has been allocated.
See also
QMPool_put()
Usage
The following example illustrates how to use QMPool_get():
void *block1 = QMPool_get(&myMemPool1, 0U); /* asserts on empty pool */
/* block1 is guaranteed to be not NULL */
~ ~ ~
QMPool_put(&myMemPool1, block1);
void *block2 = QMpool_get(&myMemPool2, 5U); /* non-asserting version */
if (block2 != (void *)0) { /* allocation succeeded? */
~ ~ ~
}
~ ~ ~
QMPool_put(&myMemPool2, block2);

Definition at line 210 of file qf_mem.c.

◆ QMPool_put()

void QMPool_put ( QMPool *const  me,
void *  b 
)

Recycles a memory block back to a memory pool.

Description
Recycle a memory block to the fixed block-size memory pool.
Parameters
[in,out]mepointer (see Object Orientation)
[in]bpointer to the memory block that is being recycled
Attention
The recycled block must be allocated from the same memory pool to which it is returned.
Note
This function can be called from any task level or ISR level.
See also
QMPool_get()
Usage
The following example illustrates how to use QMPool_put():
void *block1 = QMPool_get(&myMemPool1, 0U); /* asserts on empty pool */
/* block1 is guaranteed to be not NULL */
~ ~ ~
QMPool_put(&myMemPool1, block1);
void *block2 = QMpool_get(&myMemPool2, 5U); /* non-asserting version */
if (block2 != (void *)0) { /* allocation succeeded? */
~ ~ ~
}
~ ~ ~
QMPool_put(&myMemPool2, block2);
Precondition
# free blocks cannot exceed the total # blocks and the block pointer must be from this pool.

Definition at line 160 of file qf_mem.c.