One of the key benefits developing a MiceOnABeam model for a script is that the script's architecture not only becomes clearer to understand, but is actually represented by concrete design components that are automatically translated to LSL code. In other words, the model is the implementation!
This enables the development of a whole range of features that can operate at the level of the model itself and provide higher-level insights into the design than would otherwise be available through a similar analysis of a script coded directly.
The Performance Analysis feature, introduced in MiceOnABeam v1.0, is an initial step in this direction. This feature allows you to identify model components whose execution times will be monitored, and for which statistics will be gathered and output.
There are four types of model components that can be selected for monitoring:
For each component type you can select (via Performance Analysis Options), all components (All), no components (None), or just specific (Specify) instances of the component type to be monitored.
When All is selected for a component, code is automatically inserted at the start and end of the corresponding code segment of each instance of that component type to record it's elapsed execution time. Note however that Events are handled differently in that execution times are for the entire event handler, regardless of the state the script model was in when the event occurred.
If the Specify option is selected for State Entry/Exit, State Functions and Transitions, the compiler directives #stats and #endstats must be used to identify the particular model component to be monitored. These directives must be inserted into the corresponding LSL code segment of the component to define a group of LSL statements whose execution time will be tracked.
The following example shows how performance measurements can be gathered for a particular section of LSL code within a script model.
integer len = llGetListLength(vectorList);
#stats // Measure execution time starting from this point.
for (element = 0; element<len; element++)
#endstats // Measure execution time till this point.
If the Specify option is selected for Events, then the events to be monitored are selected directly within the Event List of the Performance Analysis Options.
The following three statistics can be selected (via Performance Analysis Options) to be output for each selected model component:
- Count: The number of times the component's code segment has been executed.
- Total Time: The total cumulative execution time (in seconds) of the component's code segment.
- Average Time: The average execution time (in seconds) of the component's code segment.
The results of the statistics gathering can be output in any of the following four ways:
- Calling the built-in global function REPORT_PERFORMANCE(): Outputs the current values of the execution timings for all selected model components.
- Each Time Option: When selected, each time a model component is executed at run-time, it's current statistics are output.
- On Final State Option: When selected, the function REPORT_PERFORMANCE() is automatically called whenever the script model transitions to a Final State.
- On Terminate Point Option: When selected, the function REPORT_PERFORMANCE() is automatically called whenever the script model transitions to a Terminate Point.
►Note that transitions will be identified in performance reports by an identifier composed of it's name and the name of it's source state (or modeling component).
- Performance analysis statistics are output to the Trace Output channel selected within the Code Generation Options of the program Options menu.
- Performance measurements will not be taken for empty State Entry/Exit and Transition code segments.
- Timing values for a monitored event are not saved until the event occurrence has been completely processed and so the timing values for an event occurrence that results in a call to REPORT_PERFORMANCE() will not be included in that report.
- Keep in mind that enabling Performance Analysis can increase script memory significantly. The feature is meant to be used only during the development stage when creating scripts and should not be enabled for the final product. See Generate LSL (Optimized).