Native QF Memory Pool. More...

#include "qmpool.h"

Public Member Functions
void	QMPool_init (QMPool const me, void const poolSto, uint_fast32_t const poolSize, uint_fast16_t const blockSize)
	Initializes the native QF memory pool.

void *	QMPool_get (QMPool *const me, uint_fast16_t const margin, uint_fast8_t const qsId)
	Obtain a memory block from a memory pool.

void	QMPool_put (QMPool const me, void const block, uint_fast8_t const qsId)
	Recycles a memory block back to a memory pool.

Private Attributes
QFreeBlock *	start
	Start of the memory managed by this memory pool.

QFreeBlock *	end
	End of the memory managed by this memory pool.

QFreeBlock *volatile	free_head
	Head of linked list of free memory blocks.

QMPoolSize	blockSize
	Memory block size [bytes] held by this fixed-size pool.

QMPoolCtr	nTot
	Total number of memory blocks in this pool.

QMPoolCtr volatile	nFree
	Number of free memory blocks remaining in the pool at this point.

QMPoolCtr	nMin
	Minimum number of free blocks ever present in this pool.

uintptr_t	free_head_dis

QMPoolCtr	nFree_dis

Detailed Description

Native QF Memory Pool.

Details: 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 fragmentation.

The QMPool class describes the native QF memory pool, which can be used as the event pool for mutable 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.

Definition at line 90 of file qmpool.h.

Member Function Documentation

◆ QMPool_init()

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

Initializes the native QF memory pool.

Details: 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 uses a potentially long critical section, because it is intended to be called only during the initialization of the system, when timing is not critical.; Many QF ports use memory pools to implement the event pools.

Backward Traceability

DVR_QP_MC4_R11_05 : Rule 11.5(Advisory): A conversion should not be performed from pointer to void into pointer to object

◆ QMPool_get()

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

Obtain a memory block from a memory pool.

Details: 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]	qsId	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.

Backward Traceability

DVR_QP_MC4_R18_03 : Rule 18.3(Required): The relation operators shall not be applied to objects of pointer type except where they point into the same array
DVR_QP_MC4_R11_05 : Rule 11.5(Advisory): A conversion should not be performed from pointer to void into pointer to object

Definition at line 131 of file qf_mem.c.

◆ QMPool_put()

void QMPool_put	(	QMPool *const	me,
		void *const	block,
		uint_fast8_t const	qsId )

Recycles a memory block back to a memory pool.

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

Parameters

[in,out]	me	current instance pointer (see oop)
[in]	block	pointer to the memory block that is being recycled
[in]	qsId	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.

Backward Traceability

DVR_QP_MC4_R11_05 : Rule 11.5(Advisory): A conversion should not be performed from pointer to void into pointer to object
DVR_QP_MC4_R18_03 : Rule 18.3(Required): The relation operators shall not be applied to objects of pointer type except where they point into the same array

Definition at line 229 of file qf_mem.c.

Member Data Documentation

◆ start

QFreeBlock* start

private

Start of the memory managed by this memory pool.

Definition at line 94 of file qmpool.h.

◆ end

QFreeBlock* end

private

End of the memory managed by this memory pool.

Definition at line 97 of file qmpool.h.

◆ free_head

QFreeBlock* volatile free_head

private

Head of linked list of free memory blocks.

Definition at line 100 of file qmpool.h.

◆ blockSize

QMPoolSize blockSize

private

Memory block size [bytes] held by this fixed-size pool.

Definition at line 103 of file qmpool.h.

◆ nTot

QMPoolCtr nTot

private

Total number of memory blocks in this pool.

Definition at line 106 of file qmpool.h.

◆ nFree

QMPoolCtr volatile nFree

private

Number of free memory blocks remaining in the pool at this point.

Definition at line 109 of file qmpool.h.

◆ nMin

QMPoolCtr nMin

private

Minimum number of free blocks ever present in this pool.

Details: 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 113 of file qmpool.h.

◆ free_head_dis

uintptr_t free_head_dis

private

Definition at line 118 of file qmpool.h.

◆ nFree_dis

QMPoolCtr nFree_dis

private

Definition at line 123 of file qmpool.h.

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

Public Member Functions

Private Attributes

Detailed Description

Member Function Documentation

◆ QMPool_init()

◆ QMPool_get()

◆ QMPool_put()

Member Data Documentation

◆ start

◆ end

◆ free_head

◆ blockSize

◆ nTot

◆ nFree

◆ nMin

◆ free_head_dis

◆ nFree_dis