QP/C  5.9.8
qf_dyn.c File Reference

Dynamic event management. More...

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

Go to the source code of this file.

Macros

#define QP_IMPL   /* this is QP implementation */
 

Functions

void QF_poolInit (void *const poolSto, uint_fast32_t const poolSize, uint_fast16_t const evtSize)
 Event pool initialization for dynamic allocation of events. More...
 
QEvtQF_newX_ (uint_fast16_t const evtSize, uint_fast16_t const margin, enum_t const sig)
 Internal QF implementation of the dynamic event allocator. More...
 
void QF_gc (QEvt const *const e)
 Recycle a dynamic event. More...
 
QEvt const * QF_newRef_ (QEvt const *const e, QEvt const *const evtRef)
 Internal QF implementation of the event reference creator. More...
 
uint_fast16_t QF_poolGetMaxBlockSize (void)
 Obtain the block size of any registered event pools. More...
 

Variables

QF_EPOOL_TYPE_ QF_pool_ [QF_MAX_EPOOL]
 allocate event pools
 
uint_fast8_t QF_maxPool_
 

of initialized event pools


 

Detailed Description

Dynamic event management.

Definition in file qf_dyn.c.

Function Documentation

◆ QF_poolInit()

void QF_poolInit ( void *const  poolSto,
uint_fast32_t const  poolSize,
uint_fast16_t const  evtSize 
)

Event pool initialization for dynamic allocation of events.

Description
This function initializes one event pool at a time and must be called exactly once for each event pool before the pool can be used.
Parameters
[in]poolStopointer to the storage for the event pool
[in]poolSizesize of the storage for the pool in bytes
[in]evtSizethe block-size of the pool in bytes, which determines the maximum size of events that can be allocated from the pool.
Attention
You might initialize many event pools by making many consecutive calls to the QF_poolInit() function. However, for the simplicity of the internal implementation, you must initialize event pools in the ascending order of the event size.

Many RTOSes provide fixed block-size heaps, a.k.a. memory pools that can be adapted for QF event pools. In case such support is missing, QF provides a native QF event pool implementation. The macro QF_EPOOL_TYPE_ determines the type of event pool used by a particular QF port. See structure QMPool for more information.

Note
The actual number of events available in the pool might be actually less than (poolSize / evtSize) due to the internal alignment of the blocks that the pool might perform. You can always check the capacity of the pool by calling QF_getPoolMin().
The dynamic allocation of events is optional, meaning that you might choose not to use dynamic events. In that case calling QF_poolInit() and using up memory for the memory blocks is unnecessary.
See also
QF initialization example for QF_init()
Precondition
cannot exceed the number of available memory pools
please initialize event pools in ascending order of evtSize:

Definition at line 112 of file qf_dyn.c.

◆ QF_newX_()

QEvt* QF_newX_ ( uint_fast16_t const  evtSize,
uint_fast16_t const  margin,
enum_t const  sig 
)

Internal QF implementation of the dynamic event allocator.

Description
Allocates an event dynamically from one of the QF event pools.
Parameters
[in]evtSizethe size (in bytes) of the event to allocate
[in]marginthe number of un-allocated events still available in a given event pool after the allocation completes. The special value QF_NO_MARGIN means that this function will assert if allocation fails.
[in]sigthe signal to be assigned to the allocated event
Returns
pointer to the newly allocated event. This pointer can be NULL only if margin!=0 and the event cannot be allocated with the specified margin still available in the given pool.
Note
The internal QF function QF_newX_() raises an assertion when the margin parameter is QF_NO_MARGIN and allocation of the event turns out to be impossible due to event pool depletion, or incorrect (too big) size of the requested event.
The application code should not call this function directly. The only allowed use is thorough the macros Q_NEW() or Q_NEW_X().

Definition at line 152 of file qf_dyn.c.

◆ QF_gc()

void QF_gc ( QEvt const *const  e)

Recycle a dynamic event.

Description
This function implements a simple garbage collector for the dynamic events. Only dynamic events are candidates for recycling. (A dynamic event is one that is allocated from an event pool, which is determined as non-zero e->poolId_ attribute.) Next, the function decrements the reference counter of the event (e->refCtr_), and recycles the event only if the counter drops to zero (meaning that no more references are outstanding for this event). The dynamic event is recycled by returning it to the pool from which it was originally allocated.
Parameters
[in]epointer to the event to recycle
Note
QF invokes the garbage collector at all appropriate contexts, when an event can become garbage (automatic garbage collection), so the application code should have no need to call QF_gc() directly. The QF_gc() function is exposed only for special cases when your application sends dynamic events to the "raw" thread-safe queues (see QEQueue). Such queues are processed outside of QF and the automatic garbage collection is NOT performed for these events. In this case you need to call QF_gc() explicitly.

Definition at line 217 of file qf_dyn.c.

◆ QF_newRef_()

QEvt const* QF_newRef_ ( QEvt const *const  e,
QEvt const *const  evtRef 
)

Internal QF implementation of the event reference creator.

Description
Creates and returns a new reference to the current event e
Parameters
[in]epointer to the current event
[in]evtRefthe event reference
Returns
the newly created reference to the event e
Note
The application code should not call this function directly. The only allowed use is thorough the macro Q_NEW_REF().
Precondition
the event must be dynamic and the provided event reference must not be already in use

Definition at line 270 of file qf_dyn.c.

◆ QF_poolGetMaxBlockSize()

uint_fast16_t QF_poolGetMaxBlockSize ( void  )

Obtain the block size of any registered event pools.

Description
Obtain the block size of any registered event pools

Definition at line 291 of file qf_dyn.c.