QMPool implementatin (Memory Pool) More...

#include "qf_port.h"
#include "qf_pkg.h"
#include "qassert.h"
#include "qs_port.h"

Include dependency graph for qf_mem.c:

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_put (QMPool const me, void b)
	Recycles a memory block back to a memory pool. More...

void *	QMPool_get (QMPool *const me, uint_fast16_t const margin)
	Obtains a memory block from a memory pool. More...

uint_fast16_t	QF_getPoolMin (uint_fast8_t const poolId)
	Obtain the minimum of free entries of the given event pool. More...

Detailed Description

QMPool implementatin (Memory Pool)

Definition in file qf_mem.c.

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]	me	pointer (see Object Orientation)
[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

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 88 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]	me	pointer (see Object Orientation)
[in]	b	pointer 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 159 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]	me	pointer (see Object Orientation)
[in]	margin	the 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 211 of file qf_mem.c.

◆ QF_getPoolMin()

uint_fast16_t QF_getPoolMin ( uint_fast8_t const poolId )

Obtain the minimum of free entries of the given event pool.

Description: This function obtains the minimum number of free blocks in the given event pool since this pool has been initialized by a call to QF_poolInit().

Parameters

[in] poolId event pool ID in the range 1..QF_maxPool_, where QF_maxPool_ is the number of event pools initialized with the function QF_poolInit().

Returns: the minimum number of unused blocks in the given event pool.

Precondition: the poolId must be in range

Definition at line 290 of file qf_mem.c.

Functions

Detailed Description

Function Documentation

◆ QMPool_init()

◆ QMPool_put()

◆ QMPool_get()

◆ QF_getPoolMin()