Instantiating the state machine (and defining the top state)

Prev: Getting started with RKH
Next: Instantiating the composite states

A state machine application (SMA) a.k.a active object, is defined with the RKH_SMA_CREATE() macro and declared with the RKH_SMA_DCLR() macro. Frequently, each state machine application is encapsulated inside a dedicated source file (.c file), from which the RKH_SMA_CREATE() macro is used, thus the structure definition is in fact entirely encapsulated in its module and is inaccessible to the rest of the application. However, as a general rule, the SMA must be declared inside a header file (.h file) by means of RKH_SMA_DCLR() macro. This macro declares a opaque pointer to SMA to be used as a global object. This global pointer represent the state machine in the application. The state machine pointers are "opaque" because they cannot access the whole state machine 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 state machine structure and make it inaccessible to the rest of the application.

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(). requently, 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 the RKH_SMA_DCLR() macro to declare a "opaque" pointer to that state machine application structure to be used in the rest of the application but hiding the proper definition. 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 Figure 2 highlights the top state and its relevant aspects. Also, shows its implementation using the RKH framework.

Figure 2 - Top state of state machine my

Defining the state machine

    /*  In my.c: active object implementation file */
(1) RKH_SMA_CREATE( 
(2)                 MySm, 
(4)                 my, 
(5)                 0, 
(6)                 HCAL, 
(7)                 &S1, 
(8)                 my_init, 
(9)                 NULL);

Declaring the state machine

    /* In my.c: active object implementation file */
    typedef struct MySm MySm;
    ...
 
    struct MySm
    {
        RKH_SMA_T sma;  /* base structure */
        rui8_t x;       /* private member */
        rui8_t y;       /* private member */
(10)};                  /* SMA derived from RKH_SMA_T structure */

    /* In my.h: active object implementation file */
(11)RKH_SMA_DCLR(my);

Explanation

• (1) Declares and allocates a SMA (a.k.a active object) derived from RKH_SMA_T.
• (2) As said before, MySm represents the SMA object struture.
• (4) my is the name of SMA. Also, it represents the top state of state diagram.
• (5) 0 is the SMA 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.
• (6) the my state machine is defined as a hierarchical state machine. The available property options are enumerated in RKH_HPPTY_T enumeration in the rkh.h file.
• (7) S1 is the initial state.
• (8) the my_init() function defines the topmost initial transition in the my state machine. The function prototype is defined as RKH_TRN_ACT_T. This argument is (optional), thus it could be declared as NULL.
• (9) not used.
• (10)The MySm defines the SMA object structure my. On the other hand, almost every SMA must also store other "extended-state" information. You supply this additional information by means of data members enlisted after the base structure member sm. Please note that the RKH_SMA_T member sm is defined as the FIRST member of the derived struct. 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.
• (11)Declares a opaque pointer to my SMA to be used as a global object.

Prev: Getting started with RKH
Next: Instantiating the composite states