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

Detailed Description

Related to underlying OS/RTOS.

Function Documentation

rkh_sma_activate()

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]	me	pointer to previously created state machine application.
[in]	qSto	base address of the event storage area. A message storage area is declared as an array of pointers to RKH events.
[in]	qSize	size of the storage event area [in number of entries].
[in]	stkSto	starting address of the stack's memory area.
[in]	stkSize	size 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_SR_ALLOC();
 
    rkh_rq_init(&sma->equeue, (const void **)qs, qsize, sma);
    rkh_sma_register(sma);
    rkh_sm_init((RKH_SM_T *)sma);
    RKH_TR_SMA_ACT(sma, RKH_GET_PRIO(sma), qsize);
}

rkh_sma_terminate()

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]

me

pointer 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_terminate(RKH_SMA_T *sma)
{
    RKH_SR_ALLOC();
 
    rkh_sma_unregister(sma);
    RKH_TR_SMA_TERM(sma, RKH_GET_PRIO(sma));
}

rkh_sma_post_fifo()

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]	me	pointer to previously created state machine application.
[in]	e	actual event sent to the state machine application.
[in]	sender	pointer 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.

rkh_sma_post_lifo()

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]	me	pointer to previously created state machine application.
[in]	e	actual event sent to the state machine application.
[in]	sender	pointer 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_sma_get()

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]

me

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