How to put the debug system in good use.

How does it work.

First of all, keep in mind that some compiling options deactivate any debug output. For more information about this, see the dedicated section The debug display is made on the standard output and have been split in different part. Each part can be activated separately. Here is the list of all existing debug areas:

• Allocation information.
• Deallocation information.
• Reallocation information.
• Transition looking information.
• State work information.
• State option changes information.
• External funtion calls information.

How to use it

The debug system can be activated or deactivated using two funtions: setDbgParam and rmDbgParam. These two funtions take unsigned integer as parameter. An enum has been created to help you pass good argument to these funtions: DBG_DISP_ENUM. As you may have noticed the value of the enum cases can be combined and so the cases can be used as flags. An example will best describe how to do than words:

    StateMachine *stateMachine = allocStateMachine("MyStateMachine", "[Pref]");
    State *S_1, *S_2;
    setDbgParam(stateMachine, ALLOC_DBG | DEALLOC_DBG);                 //This will activate allocation AND deallocation debug
    S_1 = allocateState(stateMachine, "FirstState", stateMachine);      //This will make a display due to allocation debug
    rmDbgParam(stateMachine, ALLOC_DBG);                                //This will deactivate allocation debug so, at this point only deallocation debug remain active
    S_2 = allocateState2(stateMachine, "SecondState", stateMachine);    //This won't make any display as allocation debug has been turned off
    freeStateMachine(stateMachine);                                     //This will make some display due to deallocation debug

If you want to have good information from the debug system you should provide good name for any state you allocate. The state machine creation takes two argument, the second one called dbgPref is a string that will be display before any output. If you include the library in a big system it can be usefull to quickly retreive which output correspond to the state machine, this is the goal of this parameter.

Debug areas list.

Allocation information.

This option correspond the the enum case : ALLOC_DBG.

If activated, a debug display will be done each time a new state or a new transition is created.

Deallocation information.

This option correspond the the enum case : DEALLOC_DBG.

If activated, a debug display will be done during the deallocation of the state machine. Note that any unallocated state will be explicity dislayed but the history states and transitions won't trigger any display.

Reallocation information.

This option correspond the the enum case : REALLOC_DBG.

If activated, a debug display will be done each time The system have to realloc an array. It can be very usefull when you try to optimize the speed of the library. This way you can check if the space you allocate manually is enought for your state machine.

Note:

If this debug option make some display you should not try to use the library without classic checking as it will directly lead you to a segmentation fault.

Transition looking information.

This option correspond the the enum case : TRAN_LOOKING_DBG.

If activated, a debug display will be done while the system, after having received an event, try to determine if a transition should be triggered.

State work information.

This option correspond the the enum case : STATE_WORK_DBG.

If activated, a debug display will be done each time a state is entered or exited.

State option changes information.

This option correspond the the enum case : STATE_OPT_DBG.

If activated, a debug display will be done each time state become a default state.

External funtion calls information.

This option correspond the the enum case : STATE_E_WORK_DBG.

If activated, a debug display will be done during transition showing the result of the tests on enter/exit funtion call.

Next: How to carefully handle the library

Previous : Using Parallel States to Avoid a Combinatorial Explosion of States