QMPool Class Reference

Native QF Memory Pool. More...

#include "qmpool.h"

Public Member Functions
void	QMPool_init (QMPool *const me, void *const poolSto, uint_fast32_t poolSize, uint_fast16_t blockSize)
void *	QMPool_get (QMPool *const me, uint_fast16_t const margin, uint_fast8_t const qs_id)
void	QMPool_put (QMPool *const me, void *const b, uint_fast8_t const qs_id)

Private Attributes
void *	start
void *	end
void *volatile	free_head
QMPoolSize	blockSize
QMPoolCtr	nTot
QMPoolCtr volatile	nFree
QMPoolCtr	nMin

Detailed 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 136 of file qmpool.h.

Member 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

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]	me	current instance pointer (see oop)
[in]	poolSto	pointer to the memory buffer for pool storage
[in]	poolSize	size of the storage buffer in bytes
[in]	blockSize	fixed-size of the memory blocks in bytes

Precondition qf_mem:100

• the memory block must be valid
• the poolSize must fit at least one free block
• the blockSize must not be too close to the top of the dynamic range

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.

Traceability

• DVR-QP-MC3-R11_05
• DVR-QP-MC3-R17_08

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_init(&myMemPool1,
            memPoolSto1,
            sizeof(memPoolSto1),
            10U);  /* memory blocks of 10 bytes each */
 
QMPool myMemPool2; /* memory pool object #2 (global) */
static uint8_t memPoolSto2[1024]; /* storage for a memory pool #2 */
QMPool_init(&myMemPool2,
            memPoolSto2,
            sizeof(memPoolSto2),
            25U);  /* memory blocks of 25 bytes each */

QMPool_get()

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

Obtains a memory block from a memory pool.

The function allocates a memory block from the pool and returns a pointer to the block back to the caller.

Parameters

[in,out]	me	current instance pointer (see oop)
[in]	margin	the minimum number of unused blocks still available in the pool after the allocation.
[in]	qs_id	QS-id of this state machine (for QS local filter)

Returns

A pointer to a memory block or NULL if no more blocks are available in the memory pool.

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()

Traceability

• DVR-QP-MC3-R18_03
• DVR-QP-MC3-R11_05
• DVR-QP-MC3-R18_03

Usage

The following example illustrates how to use QMPool_get():

void *block = QMpool_get(&myMemPool2, 5U); /* non-asserting version */
if (block != (void *)0) { /* allocation succeeded? */
   ~ ~ ~
}
 
~ ~ ~
QMPool_put(&myMemPool2, block);

Invariant

The pool is not empty, so the next free-block pointer, so the next free block must be in range.

Definition at line 117 of file qf_mem.c.

QMPool_put()

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

Recycles a memory block back to a memory pool.

Recycle a memory block to the fixed block-size memory pool.

Parameters

[in,out]	me	current instance pointer (see oop)
[in]	b	pointer to the memory block that is being recycled
[in]	qs_id	QS-id of this state machine (for QS local filter)

Precondition qf_mem:200

• the number of free blocks cannot exceed the total # blocks
• the block pointer must be in range for this pool.

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()

Traceability

• DVR-QP-MC3-R11_05
• DVR-QP-MC3-R18_03

Usage

The following example illustrates how to use QMPool_put():

void *block = QMpool_get(&myMemPool2, 5U); /* non-asserting version */
if (block != (void *)0) { /* allocation succeeded? */
   ~ ~ ~
}
 
~ ~ ~
QMPool_put(&myMemPool2, block);

Definition at line 192 of file qf_mem.c.

Member Data Documentation

start

void* start

private

start of the memory managed by this memory pool

Definition at line 142 of file qmpool.h.

end

void* end

private

end of the memory managed by this memory pool

Definition at line 147 of file qmpool.h.

free_head

void* volatile free_head

private

head of linked list of free blocks

Definition at line 152 of file qmpool.h.

blockSize

QMPoolSize blockSize

private

maximum block size (in bytes)

Definition at line 157 of file qmpool.h.

nTot

QMPoolCtr nTot

private

total number of blocks

Definition at line 162 of file qmpool.h.

nFree

QMPoolCtr volatile nFree

private

number of free blocks remaining

Definition at line 167 of file qmpool.h.

nMin

QMPoolCtr nMin

private

minimum number of free blocks ever present in this pool

this attribute remembers the low watermark of the pool, which provides a valuable information for sizing event pools.

See also

QF_getPoolMin().

Definition at line 177 of file qmpool.h.

---

The documentation for this class was generated from the following files:

• qmpool.h
• qf_mem.c