RKH
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages

Files

file  rkhevt.h
 Event data type and other related macros.This header file must be included in all modules(*.c files) that use RKH.
 

Data Structures

struct  RKH_EVT_T
 Represents events without parameters. More...
 

Macros

#define RKH_ALLOC_EVT(et, e)   (et *)rkh_fwk_ae((RKH_ES_T)sizeof(et),(RKH_SIG_T)(e))
 This macro dynamically creates a new event of type et with its signal. More...
 
#define RKH_FWK_GC(e)   rkh_fwk_gc(e)
 Recycle a dynamic event. More...
 
#define RKH_FWK_RSV(e)   rkh_fwk_reserve(e)
 Reserve the dynamic event to be recycled. More...
 
#define RKH_SET_STATIC_EVENT(ev_obj, ev_sig)   MK_SET_EVT(ev_obj, ev_sig)
 This macro initialize an event e with es signal and establishes it as one static event. More...
 
#define RKH_STATIC_EVENT(ev_obj, ev_sig)   MK_EVT(ev_obj, ev_sig)
 This macro declares and initializes the event structure ev_ob with ev_sig signal number and establishes it as one static event. More...
 
#define RKH_ROM_STATIC_EVENT(ev_obj, ev_sig)   MK_ROM_EVT(ev_obj, ev_sig)
 This macro declares and initializes the event structure ev_ob with ev_sig signal number and establishes it as one static event. More...
 
#define RKH_INIT_STATIC_EVT(ev_sig)   MK_EVT_STRUCT(ev_sig)
 Initializes the attibutes of a RKH's event object structure. More...
 
#define RKH_EVT_CAST(_e)   ((RKH_EVT_T *)(_e))
 Perform cast to pointer to RKH event structure (RKH_EVT_T*).
 

Detailed Description

Macro Definition Documentation

#define RKH_ALLOC_EVT (   et,
 
)    (et *)rkh_fwk_ae((RKH_ES_T)sizeof(et),(RKH_SIG_T)(e))

This macro dynamically creates a new event of type et with its signal.

The basic policy is to allocate the event from the first pool that has a block size big enough to fit the requested event size. RKH can manage up to three event pools (e.g., small, medium, and large events, like shirt sizes). It returns a pointer to the event already cast to the event type (et*).

Parameters
[in]ettype of event
[in]eevent signal
Note
The assertions inside rkh_fwk_ae() function guarantee that the pointer is valid, so you don't need to check the pointer returned from rkh_fwk_ae(), unlike the value returned from malloc(), which you should check.
Usage
Here is an example of dynamic event allocation with the macro RKH_ALLOC_EVT():
MYEVT_T *mye = RKH_ALLOC_EVT( MYEVT_T, DATA );
mye->y = mye->x = 0;
...

Definition at line 2347 of file rkh.h.

#define RKH_FWK_GC (   e)    rkh_fwk_gc(e)

Recycle a dynamic event.

This macro 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->nref attribute.) Next, the function decrements the reference counter of the event, 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. The pool-of-origin information is stored in the e->pool member.

Parameters
[in]epointer to event to be potentially recycled.
Note
This function is internal to RKH and the user application should not call it. Instead, use RKH_FWK_GC() macro.
The garbage collector must be explicitly invoked at all appropriate contexts, when an event can become garbage (automatic garbage collection).
When setting RKH_CFG_FWK_DYN_EVT_EN = 0 the garbage collector has not effect, thus it's eliminated in compile-time.

Definition at line 2385 of file rkh.h.

#define RKH_FWK_RSV (   e)    rkh_fwk_reserve(e)

Reserve the dynamic event to be recycled.

This is the complement to RKH_FWK_GC(). It increments the reference count of a dynamic event so the event can be saved by an SMA (AO). Sometime later the SMA should manually release the event with RKH_FWK_GC().

Parameters
[in]epointer to event to be reserved.

Definition at line 2404 of file rkh.h.

#define RKH_SET_STATIC_EVENT (   ev_obj,
  ev_sig 
)    MK_SET_EVT(ev_obj, ev_sig)

This macro initialize an event e with es signal and establishes it as one static event.

Parameters
[in]ev_objname of event structure (object).
[in]ev_sigevent signal. The RKH takes this value for triggering a state transition.
See also
RKH_ROM_STATIC_EVENT() and RKH_STATIC_EVENT() macros.
Usage
typedef struct
{
rui8_t cmd;
} RPC_REQ_T;
typedef struct
{
RPC_REQ_T e;
rkhui8_t txtsz;
EADR_T dst;
EADR_T sc;
char txt[ PDU_SIZEOF_UD_ASCII ];
} REQ_SEND_SMS_T;
...
static REQ_SEND_SMS_T ev_txsm;
...
some_function( ... )
{
RKH_SET_STATIC_EVENT( &ev_txsm, REQ_SEND_SMS );
ev_txsm.e.cmd = RPC_SEND_SMS;
...
}

Definition at line 2451 of file rkh.h.

#define RKH_STATIC_EVENT (   ev_obj,
  ev_sig 
)    MK_EVT(ev_obj, ev_sig)

This macro declares and initializes the event structure ev_ob with ev_sig signal number and establishes it as one static event.

Parameters
[in]ev_objname of event structure (object).
[in]ev_sigevent signal. The RKH takes this value for triggering a state transition.
See also
RKH_SET_STATIC_EVENT() and RKH_ROM_STATIC_EVENT() macros.
Usage
...
static RKH_STATIC_EVENT( ev_udrej, UPG_DIC_REJ );
void
dm_upgdic_rej( ... )
{
...
rkh_put_fifo( drpc, &ev_udrej );
}

Definition at line 2480 of file rkh.h.

#define RKH_ROM_STATIC_EVENT (   ev_obj,
  ev_sig 
)    MK_ROM_EVT(ev_obj, ev_sig)

This macro declares and initializes the event structure ev_ob with ev_sig signal number and establishes it as one static event.

Parameters
[in]ev_objname of event structure (object).
[in]ev_sigevent signal. The RKH takes this value for triggering a state transition.
See also
RKH_SET_STATIC_EVENT() and RKH_STATIC_EVENT() macros.
Warning
The created event object is explicitly placed at ROM.
Usage
...
static RKH_ROM_STATIC_EVENT( ev_timer, RPC_TIMER_RET );
void
offhook( void )
{
...
rkh_put_fifo( qphone, &ev_timer );
}

Definition at line 2512 of file rkh.h.

#define RKH_INIT_STATIC_EVT (   ev_sig)    MK_EVT_STRUCT(ev_sig)

Initializes the attibutes of a RKH's event object structure.

Usage
typedef struct
{
rui8_t cmd;
} RPC_REQ_T;
...
static RKHROM RPC_REQ_T ev_ssreq =
{
RKH_INIT_STATIC_EVT( REQ_SEND_SMS_REQ ),
RPC_SEND_SMS_REQ
};
...
void
some_function(void)
{
RKH_SMA_POST_FIFO(drpc, RKH_EVT_CAST(&ev_ssreq), 0);
...
}

Definition at line 2545 of file rkh.h.