A different approach to state machines – part 3

Last time we applied some code size optimization to our state machine implementation. In this part we improve the maintainability (and arguably readability) of the code. The code size won in the previous post came at the expense of some extra lines of source code in the form of the guard and effect handlers. Luckily, there exists a little-known pre-processor trick that can help us here: ‘X Macros’. In essence an X Macro is a function-like macro with another function-like macro as argument. The replacement token list is a list of ‘calls’ to the function-like macro with one or more ‘regular’ parameters. Are you still with me? Ok, let’s see an example:

#define EFFECTS( FUN )       \
    FUN( SetDefaultOnLevel ) \
    FUN( TurnOff )           \
    FUN( DimUp )             \
    FUN( DimDown )           \
    FUN( StopDimming )

// add 'e' prefix to the effect name
#define ENUM_ITEM( item ) e##item,

// create a function prototype from the effect name with prefix 'handle'
#define PROTOTYPE_ITEM( item ) static void handle##item(void);

// create a case statement for effect in which the corresponding function
// is called
#define CASE_ITEM( item ) case e##item : handle##item(); break;

// effects enumeration
enum {
    EFFECTS( ENUM_ITEM )
};

// effects function prototypes
EFFECTS( PROTOTYPE_ITEM )

// effect handler implementation
static void effectHandler(uint8_t effect) {
    switch( effect ) {
        EFFECTS( CASE_ITEM )
        default :
            break;
    }
}

Which expands to (layout adjusted for clarity):

// effects enumeration
enum {
    eSetDefaultOnLevel,
    eTurnOff          ,
    eDimUp            ,
    eDimDown          ,
    eStopDimming      , // I love how C99 allows this!
};

// effects function prototypes
static void handleSetDefaultOnLevel(void);
static void handleTurnOff(void);
static void handleDimUp(void);
static void handleDimDown(void);
static void handleStopDimming(void);

// effect handler implementation
static void effectHandler(uint8_t effect) {
    switch( effect ) {
        case eSetDefaultOnLevel : handleSetDefaultOnLevel(); break;
        case eTurnOff           : handleTurnOff()          ; break;
        case eDimUp             : handleDimUp()            ; break;
        case eDimDown           : handleDimDown()          ; break;
        case eStopDimming       : handleStopDimming()      ; break;
        default :
            break;
    }
}

The ENUM_ITEM, PROTOTYPE_ITEM and CASE_ITEM macros can be factored out in a separate file, which can be reused for multiple state machines. Note how we only need to add one line to the effects macro to add an effect, versus adding an enumeration, a function prototype and a case statement! The lines of code could be further reduced by factoring out the standard implementation of the effectHandler function, but I prefer to leave some clues about what is going on with all these macros. I feel their usage in this specific case pays off. Just make sure you do not go overboard with nasty pre-processor tricks; they can be notoriously hard to read and debug. The complete sources can be downloaded from statemachine_part3.zip