RKH
Active objects

Related to underlying OS/RTOS. More...

Functions

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...
 

Detailed Description

Related to underlying OS/RTOS.

Function Documentation

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.

A state machine application (SMA) is declared with the RKH_SMA_T data type and is defined with the rkh_sma_activate() service.

Parameters
[in]mepointer to previously created state machine application.
[in]qStobase address of the event storage area. A message storage area is declared as an array of pointers to RKH events.
[in]qSizesize of the storage event area [in number of entries].
[in]stkStostarting address of the stack's memory area.
[in]stkSizesize of stack memory area [in bytes].
Note
Platform-dependent function. All RKH ports must be defined in the RKH port file to a particular platform. However, only the ports to the external OS/RTOS usually need some code to bolt the framework to the external OS/RTOS.
Usage
Implementation example for x86, linux emulator of simple cooperative scheduler non-preemptive.
void
rkh_sma_activate(RKH_SMA_T *sma, const RKH_EVT_T **qs, RKH_RQNE_T qsize,
void *stks, rui32_t stksize)
{
(void)stks;
(void)stksize;
rkh_rq_init(&sma->equeue, (const void **)qs, qsize, sma);
RKH_TR_SMA_ACT(sma, RKH_GET_PRIO(sma), qsize);
}
void rkh_sma_terminate ( RKH_SMA_T me)

Terminate a state machine application (SMA) as known as active object.

A state machine application may call this service to terminate itself. Once terminated, the state machine application must be re-created in order for it to execute again.

Parameters
[in]mepointer to previously created state machine application.
Note
Platform-dependent function. All RKH ports must be defined in the RKH port file to a particular platform. However, only the ports to the external OS/RTOS usually need some code to bolt the framework to the external OS/RTOS.
Usage
Implementation example for x86, linux emulator of simple cooperative scheduler non-preemptive.
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.

Parameters
[in]mepointer to previously created state machine application.
[in]eactual event sent to the state machine application.
[in]senderpointer to the sender object. It is not necessarily a pointer to an active object. In fact, if RKH_SMA_POST_FIFO() is called from an interrupt or other context, it can create a unique object just to unambiguously identify the publisher of the event.
Note
This function is internal to RKH and the user application should not call it. Instead, use RKH_SMA_POST_FIFO() macro.
For memory efficiency and best performance the SMA's event queue, STORE ONLY POINTERS to events, not the whole event objects. The assertion inside it guarantee that the pointer is valid, so is not necessary to check the pointer returned from rkh_sma_post_fifo().
Platform-dependent function. All RKH ports must be defined in the RKH port file to a particular platform. However, only the ports to the external OS/RTOS usually need some code to bolt the framework to the external OS/RTOS.
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.

Parameters
[in]mepointer to previously created state machine application.
[in]eactual event sent to the state machine application.
[in]senderpointer to the sender object. It is not necessarily a pointer to an active object. In fact, if RKH_SMA_POST_FIFO() is called from an interrupt or other context, it can create a unique object just to unambiguously identify the publisher of the event.
Note
This function is internal to RKH and the user application should not call it. Instead, use RKH_SMA_POST_LIFO() macro.
For memory efficiency and best performance the SMA's event queue, STORE ONLY POINTERS to events, not the whole event objects. The assertion inside it guarantee that the pointer is valid, so is not necessary to check the pointer returned from rkh_sma_post_lifo().
Platform-dependent function. All RKH ports must be defined in the RKH port file to a particular platform. However, only the ports to the external OS/RTOS usually need some code to bolt the framework to the external OS/RTOS.
RKH_EVT_T* rkh_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.

Parameters
[in]mepointer to previously created state machine application.
Returns
A non-NULL pointer indicates that a event pointer was available, otherwise a NULL pointer.
Note
Platform-dependent function. All RKH ports must be defined in the RKH port file to a particular platform. However, only the ports to the external OS/RTOS usually need some code to bolt the framework to the external OS/RTOS. Depending on the underlying OS or kernel, if no event is present at the queue, the function will block the current thread until an event is received.