RKH
rkhsma.h File Reference

Specifies the interface of the acive object (SMA state machine applications) manager. More...

#include "rkhsm.h"
#include "rkhqueue.h"
Include dependency graph for rkhsma.h:

Go to the source code of this file.

Data Structures

struct  RKH_SMAI_T
 Defines the data structure into which the collected performance information for state machine is stored. More...
 
struct  RKH_SMA_T
 Describes the SMA (active object in UML). More...
 
struct  RKHSmaVtbl
 Virtual table for the RKH_SMA_T structure. More...
 

Macros

#define RKH_SMA_ACCESS_STATE(me_)    ((RKH_SM_T *)me_)->state
 Macro for accessing to state member of state machine structure. More...
 
#define RKH_SMA_ACCESS_CONST(me_, member_)    ((RKH_SM_T *)me_)->romrkh->member_
 Macro for accessing to members of state machine structure. More...
 
#define RKH_SMA_DCLR(me_)    RKH_DCLR_PTR_TYPE(RKH_SMA_T, me_)
 This macro declares a opaque pointer to previously created state machine application (SMA aka active object) to be used as a global object. More...
 
#define RKH_SMA_DCLR_TYPE(type_, me_)    RKH_DCLR_PTR_TYPE(type_, me_)
 This macro declares a typed pointer to previously created state machine application (SMA aka active object) to be used as a global and public object. More...
 
#define RKH_SMA_ACTIVATE(me_, qSto_, qStoSize, stkSto_, stkSize_)
 Invoke the active object activation function rkh_sma_activate(). If RKH_CFG_SMA_VFUNCT_EN is set RKH_ENABLED, this operation is polymorphic, where its implementation is defined by the virtual table of the active object to activate. More...
 
#define RKH_SMA_CREATE(type, name, prio, ppty, initialState, initialAction, initialEvt)
 Declare and allocate a SMA (active object) derived from RKH_SMA_T. Also, initializes and assigns a state machine to previously declared SMA. More...
 
#define RKH_SMA_DEF_PTR(me_)    RKH_SMA_T *const me_ = (RKH_SMA_T *)&RKH_SMA_NAME(me_)
 Declare a opaque pointer pointing to an previously created active object. More...
 
#define RKH_SMA_DEF_PTR_TYPE(type, me_)    type *const me_ = (type *)&RKH_SMA_NAME(me_)
 Declare a pointer of specified type pointing to an previously created active object. More...
 
#define RKH_SMA_POST_FIFO(me_, e_, sender_)    rkh_sma_post_fifo((me_), (e_), (sender_))
 Invoke the direct event posting facility rkh_sma_post_fifo(). If RKH_CFG_SMA_VFUNCT_EN is set RKH_ENABLED, this operation is polymorphic, where its implementation is defined by the virtual table of the target active object. More...
 
#define RKH_SMA_POST_LIFO(me_, e_, sender_)    rkh_sma_post_lifo((me_), (e_), (sender_))
 Invoke the direct event posting facility rkh_sma_post_lifo(). If RKH_CFG_SMA_VFUNCT_EN is set RKH_ENABLED, this operation is polymorphic, where its implementation is defined by the virtual table of the target active object. More...
 
#define RKH_SMA_DISPATCH(me_, arg_)    rkh_sma_dispatch((me_), (arg_))
 For cooperative scheduling policy, this function is used to dispatch the event to the active object behavior (single or multiple state machines). More...
 
#define RKH_ARRAY_SMA_DCLR(_arr, _num)    extern RKH_SMA_T * const *_arr[_num]
 Declares a opaque pointer to previously created array of state machine applications SMA (a.k.a Active Object) to be used as a global object. More...
 
#define RKH_ARRAY_SMA_DCLR_TYPE(type_, array_, num_)    extern type_ * const * array_[num_]
 Declares a typed pointer to previously created array of state machine applications SMA (a.k.a Active Object) to be used as a global object. More...
 
#define RKH_ARRAY_SMA_CREATE(_arr, _num)    RKH_SMA_T * const *_arr[_num] =
 Declare and allocate an array of SMAs (a.k.a active objects) derived from RKH_SMA_T. More...
 
#define RKH_ARRAY_SMA_CREATE_TYPE(type_, array_, num_)    type_ * const * array_[num_] =
 Declare and allocate an array of SMAs (a.k.a active objects) derived from RKH_SMA_T. More...
 
#define RKH_ARRAY_SMA(_arr, _ix)   *_arr[_ix]
 Retrieves the pointer to active object from a SMA's array. More...
 
#define RKH_GET_AO_NAME(ao)   RKH_SMA_ACCESS_CONST(ao, name)
 This macro retrieves the name of an registered active object. More...
 
#define RKH_GET_SMA(_prio)    rkh_sptbl[(rui8_t)(_prio)]
 Retrieves the address of an registered active object (SMA) according to its priority. More...
 
#define RKH_GET_PRIO(_ao)    (rui8_t)(RKH_SMA_ACCESS_CONST(_ao, prio))
 Retrieves the priority number of an registered active object (SMA). More...
 

Typedefs

typedef void(* RKHActivate) (RKH_SMA_T *me, const RKH_EVT_T **qSto, RKH_QUENE_T qSize, void *stkSto, rui32_t stkSize)
  More...
 
typedef void(* RKHTask) (RKH_SMA_T *me, void *arg)
  More...
 
typedef void(* RKHPostFifo) (RKH_SMA_T *me, const RKH_EVT_T *e, const void *const sender)
  More...
 
typedef void(* RKHPostLifo) (RKH_SMA_T *me, const RKH_EVT_T *e, const void *const sender)
  More...
 

Functions

void rkh_sma_register (RKH_SMA_T *me)
 Registers a state machine application (SMA) as known as active object into the framework, which implies to store a pointer to the SMA in the priority table. More...
 
void rkh_sma_unregister (RKH_SMA_T *me)
 Removes the SMA as known as active object from the priority table, and thus from the framework, by simply replacing the link to the SMA being deleted with a NULL pointer. More...
 
void rkh_sma_ctor (RKH_SMA_T *me, const RKHSmaVtbl *vtbl)
 Initializes the virtual table of the active object instance and calls the constructor operation of its base class. More...
 
void rkh_sma_activate (RKH_SMA_T *me, const RKH_EVT_T **qSto, RKH_QUENE_T qSize, void *stkSto, rui32_t stkSize)
 Initializes and activates a previously created state machine application (SMA) as known as active object. More...
 
void rkh_sma_terminate (RKH_SMA_T *me)
 Terminate a state machine application (SMA) as known as active object. More...
 
void rkh_sma_post_fifo (RKH_SMA_T *me, const RKH_EVT_T *e, const void *const sender)
 Send an event to a state machine application (SMA) as known as active object through a queue using the FIFO policy. A message is a pointer size variable and its use is application specific. More...
 
void rkh_sma_post_lifo (RKH_SMA_T *me, const RKH_EVT_T *e, const void *const sender)
 Send an event to a state machine application (SMA) as known as active object through a queue using the LIFO policy. A message is a pointer size variable and its use is application specific. More...
 
RKH_EVT_Trkh_sma_get (RKH_SMA_T *me)
 Get an event from the event queue of an state machine application (SMA) as known as active object. The events received are pointer size variables and their use is application specific. More...
 
void rkh_sma_dispatch (RKH_SMA_T *me, void *arg)
 For cooperative scheduling policy, this function is used to dispatch the event to the active object behavior (single or multiple state machines). More...
 
void rkh_sma_defer (RKH_QUEUE_T *q, const RKH_EVT_T *e)
 Defer an event to a given separate event queue. More...
 
RKH_EVT_Trkh_sma_recall (RKH_SMA_T *me, RKH_QUEUE_T *q)
 Recall a deferred event from a given event queue. More...
 
void rkh_sma_clear_info (RKH_SMA_T *me)
 Clear performance information for a particular state machine application (SMA) as known as active object. More...
 
void rkh_sma_get_info (RKH_SMA_T *me, RKH_SMAI_T *psi)
 Retrieves performance information for a particular state machine application (SMA) as known as active object. More...
 

Variables

const RKHSmaVtbl rkhSmaVtbl
  More...
 
RKH_SMA_Trkh_sptbl [RKH_CFG_FWK_MAX_SMA]
 Priority arranged table of registered SMA. More...
 

Detailed Description

Specifies the interface of the acive object (SMA state machine applications) manager.

Definition in file rkhsma.h.

Macro Definition Documentation

◆ RKH_SMA_ACCESS_STATE

#define RKH_SMA_ACCESS_STATE (   me_)     ((RKH_SM_T *)me_)->state

Macro for accessing to state member of state machine structure.

Parameters
[in]me_Pointer to object of state machine.

Definition at line 87 of file rkhsma.h.

◆ RKH_SMA_ACCESS_CONST

#define RKH_SMA_ACCESS_CONST (   me_,
  member_ 
)     ((RKH_SM_T *)me_)->romrkh->member_

Macro for accessing to members of state machine structure.

Parameters
[in]me_Pointer to object of state machine.
[in]member_Member of state machine structure.

Definition at line 98 of file rkhsma.h.

◆ RKH_SMA_DCLR

#define RKH_SMA_DCLR (   me_)     RKH_DCLR_PTR_TYPE(RKH_SMA_T, me_)

This macro declares a opaque pointer to previously created state machine application (SMA aka active object) to be used as a global object.

This global pointer represent the active object in the application. These pointers are "opaque" because they cannot access the whole active object structure, but only the part inherited from the RKH_SMA_T structure. The power of an "opaque" pointer is that it allows to completely hide the definition of the active object structure and make it inaccessible to the rest of the application, thus strengthening the encapsulation concept.

Parameters
[in]me_pointer to previously created state machine application.
Note
Generally, this macro is used in the SMA's header file.
See also
RKH_SMA_CREATE().
Usage
// my.h: state-machine application's header file
#define RKH_SMA_DCLR(me_)
This macro declares a opaque pointer to previously created state machine application (SMA aka active ...
Definition: rkhsma.h:139

Definition at line 139 of file rkhsma.h.

◆ RKH_SMA_DCLR_TYPE

#define RKH_SMA_DCLR_TYPE (   type_,
  me_ 
)     RKH_DCLR_PTR_TYPE(type_, me_)

This macro declares a typed pointer to previously created state machine application (SMA aka active object) to be used as a global and public object.

Parameters
[in]type_Data type of the state machine application. Could be derived from RKH_SMA_T. The pointer could be used to publish the internals of the class of the state machine.
[in]me_pointer to previously created state machine application.
Note
Generally, this macro is used in the SMA's header file.
See also
RKH_SMA_CREATE(), RKH_SMA_DCLR().
Usage
// my.h: state-machine application's header file
RKH_SMA_DCLR_TYPE(Blinky, blinky);
#define RKH_SMA_DCLR_TYPE(type_, me_)
This macro declares a typed pointer to previously created state machine application (SMA aka active o...
Definition: rkhsma.h:168

Definition at line 168 of file rkhsma.h.

◆ RKH_SMA_CREATE

#define RKH_SMA_CREATE (   type,
  name,
  prio,
  ppty,
  initialState,
  initialAction,
  initialEvt 
)
Value:
static RKH_SM_CONST_CREATE(name, prio, ppty, initialState, \
initialAction, initialEvt); \
static type RKH_SMA_NAME(name) = MKSMA(&RKH_SM_CONST_NAME(name), \
initialState)
#define RKH_SM_CONST_CREATE(name, prio, ppty, initialState, initialAction, initialEvt)
Allocates and then initializes the constant part (in ROM) of the state machine.
Definition: rkhsm.h:1442

Declare and allocate a SMA (active object) derived from RKH_SMA_T. Also, initializes and assigns a state machine to previously declared SMA.

In the UML specification, every state machine has a top state (the abstract root of every state machine hierarchy), which contains all the other elements of the entire state machine. RKH provides the top state using the macro RKH_SMA_CREATE(). Frequently, RKH_SMA_CREATE() is used within state-machine's module (.c file), thus the structure definition is in fact entirely encapsulated in its module and is inaccessible to the rest of the application. However, use RKH_SMA_DEF_PTR() or RKH_SMA_DEF_PTR_TYPE() macros to define a opaque pointer or typed pointer to that state machine application structure, respectively. Also, use the RKH_SMA_DCLR() macro to declare it to be for the rest of application code. RKH_SMA_T is not intended to be instantiated directly, but rather serves as the base structure for derivation of state machines in the application code. The following example illustrates how to derive an state machine from RKH_SMA_T. Please note that the RKH_SMA_T member sm is defined as the FIRST member of the derived structure.

Parameters
[in]typeData type of the SMA. Could be derived from RKH_SMA_T.
[in]nameName of state machine application. Also, it represents the top state of state diagram.
[in]prioState machine application priority. A unique priority number must be assigned to each SMA from 0 to RKH_LOWEST_PRIO. The lower the number, the higher the priority.
[in]pptyState machine properties. The available properties are enumerated in RKH_HPPTY_T enumeration in the rkh.h file.
[in]initialStatePointer to initial state. This state could be defined either composite or basic (not pseudo-state).
[in]initialActionPointer to initialization action (optional). The function prototype is defined as RKH_TRN_ACT_T. This argument is optional, thus it could be declared as NULL.
[in]initialEvtThis parameter is now deprecated and not recommended for new designs. It remains supported for backwards compatibility.
See also
RKH_SM_CONST_CREATE(), RKH_SM_GET_CONST(), RKH_SM_GET_CONST(), RKH_SMA_DEF_PTR(), RKH_SMA_DEF_PTR_TYPE()
Usage
...within state-machine application's module
typedef struct
{
RKH_SMA_T ao; // base structure
rui8_t x; // private member
rui8_t y; // private member
} MYSM_T;
// static instance of SMA object
RKH_SMA_CREATE(MYSM_T, my, 0, HCAL, &S1, my_iaction, &my_ievent);

Definition at line 348 of file rkhsma.h.

◆ RKH_SMA_DEF_PTR

#define RKH_SMA_DEF_PTR (   me_)     RKH_SMA_T *const me_ = (RKH_SMA_T *)&RKH_SMA_NAME(me_)

Declare a opaque pointer pointing to an previously created active object.

Parameters
[in]me_Name of state machine application.
See also
RKH_SMA_DCLR()

Definition at line 390 of file rkhsma.h.

◆ RKH_SMA_DEF_PTR_TYPE

#define RKH_SMA_DEF_PTR_TYPE (   type,
  me_ 
)     type *const me_ = (type *)&RKH_SMA_NAME(me_)

Declare a pointer of specified type pointing to an previously created active object.

The pointer could be used to hide (opaque) or to publish the internals of the class of the active object.

Parameters
[in]typeData type of the state machine application. Could be derived from RKH_SMA_T.
[in]me_Name of state machine application.
See also
RKH_SMA_DCLR()

Definition at line 407 of file rkhsma.h.

◆ RKH_ARRAY_SMA_DCLR

#define RKH_ARRAY_SMA_DCLR (   _arr,
  _num 
)     extern RKH_SMA_T * const *_arr[_num]

Declares a opaque pointer to previously created array of state machine applications SMA (a.k.a Active Object) to be used as a global object.

Parameters
[in]_arrpointer to previously created array of state machine applications. To do that is recommended to use the macro RKH_ARRAY_SMA_CREATE().
[in]_numsize of array [in active objects].
Note
Generally, this macro is used in the SMA's header file.
See also
RKH_SMA_CREATE().
Usage
// cli.h: state-machine application's header file
#define NUM_CLIENTS 4
typedef struct
{
RKH_SMA_T me; // base structure
RKH_TMR_T cli_utmr; // usage time
RKH_TMR_T cli_rtmr; // waiting request time
} CLI_T; // Active Object derived from RKH_SMA_T structure
RKH_ARRAY_SMA_DCLR( clis, NUM_CLIENTS );
#define RKH_ARRAY_SMA_DCLR(_arr, _num)
Declares a opaque pointer to previously created array of state machine applications SMA (a....
Definition: rkhsma.h:561
Describes the SMA (active object in UML).
Definition: rkhsma.h:772
Defines the data structure used to maintain information that allows the timer-handling facility to up...
Definition: rkhtmr.h:315

Definition at line 561 of file rkhsma.h.

◆ RKH_ARRAY_SMA_DCLR_TYPE

#define RKH_ARRAY_SMA_DCLR_TYPE (   type_,
  array_,
  num_ 
)     extern type_ * const * array_[num_]

Declares a typed pointer to previously created array of state machine applications SMA (a.k.a Active Object) to be used as a global object.

Parameters
[in]type_data type of active object.
[in]array_pointer to previously created array of state machine applications. To do that is recommended to use the macro RKH_ARRAY_SMA_CREATE_TYPE().
[in]num_size of array [in active objects].
Note
Generally, this macro is used in the SMA's header file.
See also
RKH_SMA_CREATE().
Usage
// cli.h: state-machine application's header file
#define NUM_CLIENTS 4
typedef struct
{
RKH_SMA_T me; // base structure
RKH_TMR_T cli_utmr; // usage time
RKH_TMR_T cli_rtmr; // waiting request time
} CLI_T; // Active Object derived from RKH_SMA_T structure
RKH_ARRAY_SMA_DCLR_TYPE(CLI_T, clis, NUM_CLIENTS);
#define RKH_ARRAY_SMA_DCLR_TYPE(type_, array_, num_)
Declares a typed pointer to previously created array of state machine applications SMA (a....
Definition: rkhsma.h:596

Definition at line 596 of file rkhsma.h.

◆ RKH_ARRAY_SMA_CREATE

#define RKH_ARRAY_SMA_CREATE (   _arr,
  _num 
)     RKH_SMA_T * const *_arr[_num] =

Declare and allocate an array of SMAs (a.k.a active objects) derived from RKH_SMA_T.

Parameters
[in]_arrname of SMA's array.
[in]_numsize of array [in active objects].
Usage
// Defines SMAs (a.k.a Active Objects)
RKH_SMA_CREATE( CLI_T, cli0, 1, HCAL, &cli_idle, cli_init, NULL );
RKH_SMA_CREATE( CLI_T, cli1, 2, HCAL, &cli_idle, cli_init, NULL );
RKH_SMA_CREATE( CLI_T, cli2, 3, HCAL, &cli_idle, cli_init, NULL );
RKH_SMA_CREATE( CLI_T, cli3, 4, HCAL, &cli_idle, cli_init, NULL );
RKH_ARRAY_SMA_CREATE( clis, NUM_CLIENTS )
{
&cli0, &cli1, &cli2, &cli3
};
@ HCAL
Definition: rkhsm.h:1611
#define RKH_ARRAY_SMA_CREATE(_arr, _num)
Declare and allocate an array of SMAs (a.k.a active objects) derived from RKH_SMA_T.
Definition: rkhsma.h:622
#define RKH_SMA_CREATE(type, name, prio, ppty, initialState, initialAction, initialEvt)
Declare and allocate a SMA (active object) derived from RKH_SMA_T. Also, initializes and assigns a st...
Definition: rkhsma.h:348

Definition at line 622 of file rkhsma.h.

◆ RKH_ARRAY_SMA_CREATE_TYPE

#define RKH_ARRAY_SMA_CREATE_TYPE (   type_,
  array_,
  num_ 
)     type_ * const * array_[num_] =

Declare and allocate an array of SMAs (a.k.a active objects) derived from RKH_SMA_T.

Parameters
[in]type_data type of active object.
[in]array_name of SMA's array.
[in]num_size of array [in active objects].
Usage
// Defines SMAs (a.k.a Active Objects)
RKH_SMA_CREATE(CLI_T, cli0, 1, HCAL, &cli_idle, cli_init, NULL);
RKH_SMA_CREATE(CLI_T, cli1, 2, HCAL, &cli_idle, cli_init, NULL);
RKH_SMA_CREATE(CLI_T, cli2, 3, HCAL, &cli_idle, cli_init, NULL);
RKH_SMA_CREATE(CLI_T, cli3, 4, HCAL, &cli_idle, cli_init, NULL);
RKH_ARRAY_SMA_CREATE(CLI_T, clis, NUM_CLIENTS)
{
&cli0, &cli1, &cli2, &cli3
};

Definition at line 649 of file rkhsma.h.

◆ RKH_ARRAY_SMA

#define RKH_ARRAY_SMA (   _arr,
  _ix 
)    *_arr[_ix]

Retrieves the pointer to active object from a SMA's array.

Parameters
[in]_arrname of SMA's array.
[in]_ixindex (position in the array).
Usage
#define NUM_CLIENTS 4
#define CLI( _clino ) RKH_ARRAY_SMA( clis, _clino )
#define CLI0 CLI(0)
#define CLI1 CLI(1)
#define CLI2 CLI(2)
#define CLI3 CLI(3)
typedef struct
{
RKH_SMA_T me; // base structure
RKH_TMR_T cli_utmr; // usage time
RKH_TMR_T cli_rtmr; // waiting request time
} CLI_T; // Active Object derived from RKH_SMA_T structure
RKH_ARRAY_SMA_DCLR( clis, NUM_CLIENTS );

Definition at line 679 of file rkhsma.h.

◆ RKH_GET_AO_NAME

#define RKH_GET_AO_NAME (   ao)    RKH_SMA_ACCESS_CONST(ao, name)

This macro retrieves the name of an registered active object.

Parameters
[in]aopointer to previously created active object.
Returns
Name of active object.

Definition at line 691 of file rkhsma.h.

◆ RKH_GET_SMA

#define RKH_GET_SMA (   _prio)     rkh_sptbl[(rui8_t)(_prio)]

Retrieves the address of an registered active object (SMA) according to its priority.

Parameters
[in]_prioregistered active object (SMA) priority.
Returns
pointer to previously registered active object (SMA).

Definition at line 704 of file rkhsma.h.

◆ RKH_GET_PRIO

#define RKH_GET_PRIO (   _ao)     (rui8_t)(RKH_SMA_ACCESS_CONST(_ao, prio))

Retrieves the priority number of an registered active object (SMA).

Parameters
[in]_aopointer to previously registered active object (SMA).

Definition at line 713 of file rkhsma.h.

Typedef Documentation

◆ RKHActivate

typedef void(* RKHActivate) (RKH_SMA_T *me, const RKH_EVT_T **qSto, RKH_QUENE_T qSize, void *stkSto, rui32_t stkSize)

Virtual function to activate the active object (thread)

See also
RKH_SMA_ACTIVATE()

Definition at line 856 of file rkhsma.h.

◆ RKHTask

typedef void(* RKHTask) (RKH_SMA_T *me, void *arg)

Frequently, the active object has its own task processing loop, also as known as thread of control, that waits for the signal to be posted, and when it is, loops to remove and process all events that are currently queued.

For cooperative scheduling policy, this function is used to dispatch the event to the active object behavior (single or multiple state machines).

Definition at line 861 of file rkhsma.h.

◆ RKHPostFifo

typedef void(* RKHPostFifo) (RKH_SMA_T *me, const RKH_EVT_T *e, const void *const sender)

Virtual function to asynchronously post (FIFO) an event to an AO

See also
RKH_SMA_POST_FIFO()

Definition at line 865 of file rkhsma.h.

◆ RKHPostLifo

typedef void(* RKHPostLifo) (RKH_SMA_T *me, const RKH_EVT_T *e, const void *const sender)

Virtual function to asynchronously post (LIFO) an event to an AO

See also
RKH_SMA_POST_LIFO()

Definition at line 873 of file rkhsma.h.

Function Documentation

◆ rkh_sma_register()

void rkh_sma_register ( RKH_SMA_T me)

Registers a state machine application (SMA) as known as active object into the framework, which implies to store a pointer to the SMA in the priority table.

Parameters
[in]mepointer to previously created state machine application.

◆ rkh_sma_unregister()

void rkh_sma_unregister ( RKH_SMA_T me)

Removes the SMA as known as active object from the priority table, and thus from the framework, by simply replacing the link to the SMA being deleted with a NULL pointer.

Parameters
[in]mepointer to previously created state machine application.

◆ rkh_sma_ctor()

void rkh_sma_ctor ( RKH_SMA_T me,
const RKHSmaVtbl vtbl 
)

Initializes the virtual table of the active object instance and calls the constructor operation of its base class.

Parameters
[in]mepointer to previously created state machine application.
[in]vtblpointer to virtual table. Define it as null to use the default virtual table, rkhSmaVtbl.
Note
The initializer assumes that memory has previously been allocated for the object (either statically or dynamically).

◆ rkh_sma_defer()

void rkh_sma_defer ( RKH_QUEUE_T q,
const RKH_EVT_T e 
)

Defer an event to a given separate event queue.

Event deferral comes in very handy when an event arrives in a particularly inconvenient moment but can be deferred for some later time, when the system is in a much better position to handle the event. RKH supports very efficient event deferring and recalling mechanisms. This function is part of the event deferral mechanism. An SMA uses this function to defer an event e to the event queue q. RKH correctly accounts for another outstanding reference to the event and will not recycle the event at the end of the RTC step. Later, the SMA might recall one event at a time from the event queue by means of rkh_sma_recall() function.

Parameters
[in]qpointer to previously created queue.
[in]epointer to event.
Note
For memory efficiency and best performance the deferred event queue, STORE ONLY POINTERS to events, not the whole event objects. An SMA can use multiple event queues to defer events of different kinds. The assertion inside it guarantee that operation is valid, so is not necessary to check the value returned from it.
Usage
static RKH_QUEUE_T qurc;
static RKH_EVT_T *qurc_sto[ MAX_SIZEOF_QURC ];
rkh_queue_init( &qurc, qurc_sto, MAX_SIZEOF_QURC, NULL );
...
void
ring( const struct rkh_t *me, RKH_EVT_T *pe )
{
(void)me; // argument not used
rkh_sma_defer( &qurc, pe ); // defer event
}
void rkh_queue_init(RKH_QUEUE_T *q, const void **sstart, RKH_QUENE_T ssize, void *sma)
Initializes the previously allocated queue data structure RKH_QUEUE_T.
void rkh_sma_defer(RKH_QUEUE_T *q, const RKH_EVT_T *e)
Defer an event to a given separate event queue.
Represents events without parameters.
Definition: rkhevt.h:170
Defines the data structure used to maintain information about the queue.
Definition: rkhqueue.h:170

◆ rkh_sma_recall()

RKH_EVT_T* rkh_sma_recall ( RKH_SMA_T me,
RKH_QUEUE_T q 
)

Recall a deferred event from a given event queue.

This function is part of the event deferral support. An SMA uses this function to recall a deferred event from a given event queue. Recalling an event means that it is removed from the deferred event queue q and posted (LIFO) to the event queue of the me state machine application.

Note
For memory efficiency and best performance the destination event queue, STORE ONLY POINTERS to events, not the whole event objects.
Returns
The pointer to the recalled event to the caller, or NULL if no event has been recalled.
Usage
void
exit_rx_manager( const struct rkh_t *me )
{
rkh_sma_recall( me, &qurc );
}
RKH_EVT_T * rkh_sma_recall(RKH_SMA_T *me, RKH_QUEUE_T *q)
Recall a deferred event from a given event queue.

◆ rkh_sma_clear_info()

void rkh_sma_clear_info ( RKH_SMA_T me)

Clear performance information for a particular state machine application (SMA) as known as active object.

Parameters
[in]mepointer to previously created state machine application.
Note
This function is optional, thus it could be eliminated in compile-time with RKH_CFG_SMA_GET_INFO_EN = 0.

◆ rkh_sma_get_info()

void rkh_sma_get_info ( RKH_SMA_T me,
RKH_SMAI_T psi 
)

Retrieves performance information for a particular state machine application (SMA) as known as active object.

The user application must allocate an RKH_SMAI_T data structure used to receive data. The performance information is available during run-time for each of the RKH services. This can be useful in determining whether the application is performing properly, as well as helping to optimize the application. This information provides a "snapshot" a particular instant in time, i.e., when the service is invoked.

Parameters
[in]mepointer to previously created state machine application.
[in]psipointer to the buffer into which the performance information will be copied by reference.
Note
See RKH_SMAI_T structure for more information. This function is optional, thus it could be eliminated in compile-time with RKH_CFG_SMA_GET_INFO_EN = 0.

Variable Documentation

◆ rkhSmaVtbl

const RKHSmaVtbl rkhSmaVtbl
extern

Default virtual table for the RKH_SMA_T structure