FSM Reporting Facilities

The FSM Library provides a couple of reporting facilities to assist documentation generation. The FSM library can automatically generate an HTML file describing the state transitions of a given FSM. The FSM can also automatically generate an HTML file describing the execution processing as summary timing statistics. These HTML files can easily be included, linked or copied into documentation.

State Table Logic

The CFiniteStateMachine method toHTML() will generate an HTML documentation string that describes the FSM as a state table. The table gives an alphabetized list by state of each internal and external state transition for the given state. Each table row contains the state name, the event triggering the state transition, any guard conditions for the event, the ending state, and the action to be taken. The documentation will generate tables for all substate FSM as well.  For the CD player example, the following uses the toHTML method, and saves the string to the file “playerFSMLogic.html.” The first state is given in the title.

                 String html=player.toHTML();

                 html.SaveFile("playerFSMLogic.html");

 

FSM CPlayer First State = STOPPED

 

Beginning State	Event	Conditions	Ending State	Actions
PLAYING	stop		STOPPED	stopAction
PLAYING	do		PLAYING	playingActivity
PLAYING	help		PLAYING	helpActivity
PLAYING	next		PLAYING	nextPlayActivity
STOPPED	start		PLAYING	startAction

Timing

The CFiniteStateMachine method timingToHTML() will generate an HTML documentation string that describes the FSM performance by state in table format. The table contains each FSM state, and the performance statistics for average duration, worst case duration, total duration, average processing, worst case processing, and the total processing.  For the CD player example, the following uses the timingToHTML method, and saves the string to the file “playerTiming.html.”

                 String timing=player.timingToHTML();

                 timing.SaveFile("playerTiming.html");

 

FSM CPlayer Processing (in seconds)

 

State	Average Duration	Worst Case Duration	Total Elapsed Duration	Average Processing	Worst Case Processing	Total Processing
PLAYING	11.151000	33.453000	63.703000	0.000000	0.204000	4.378000
STOPPED	8.265667	24.797000	37.391000	0.000000	0.000000	0.000000

 

The duration statistic means how long was spent in a given state according to the wall clock. By wall clock, we mean that if we enter a state at 1:00PM and leave the state at 1:01PM, then the duration was 1 minute, irrespective of the fact that only 1 millisecond of processor time was required to enter, update, and leave the state. The average duration represents the average for the total wall clock time in a given state. The worst case duration gives the longest wall clock time spent in the state.  The total elapsed duration gives the total amount of wall clock time spent in the state.

The processing statistic means how much CPU processing time was used in the given state. Generally, this number may be zero because it is below the timing resolution so that it may be hard to actually determine how much CPU time was used. The resolution of the time can be 1 millisecond if the HIGH_RESOLUTION preprocessor flag is defined. Otherwise, the timer resolution may be on the order of magnitude of hundreds of milliseconds. The average processing represents the average for the CPU processing time in a given state. The worst case processing gives the CPU longest the processor required in the state.  The total elapsed processing gives the total amount of CPU processing time spent in the state. In the above table, the Sleep function times a random number was required to simulate time spent within the CPU.