4.3.5 Snapshot

Snapshot is a powerful utility for model debugging and testing. SVM is able to snapshot a model during its simulation (but not execution). The state of the model that need to be stored (specified by the model designer), including its variables, is snapshot as a text file or a string. The snapshot contains enough information for a restore operation, which puts the model into its previous state so that simulation can restart at exactly that point. The snapshot is usually saved in a .snp file in the same directory as the model's. The file name of the snapshot file is the same as the text file of the model, with its postfix changed.

A snapshot request is a special event to SVM. This request may be sent from the model that is being simulated, or by the user from the user interface (for example, the default graphical interface of SVM provides a ``snapshot'' button). Function eventhandler.snap_to_file(filename) accepts a string parameter filename as the snapshot file name (usually ending with .snp), and schedules a snapshot right after the current event is handled. SVM assigns the highest priority to this request. The snapshot is taken before other scheduled events are handled, if any.

A model may also request a snapshot in the memory, and roll back to it at a later time. Pre-defined macro [SNAPSHOTREQ(time)] requests a snapshot (with the highest priority) and labels it with time (an arbitrary but increasing integer that uniquely identifies a snapshot). Macro [SNAPSHOTRET(time)] is used to retrieve a snapshot taken previously, and roll the model back to it. In this way, the model is able to interact with the simulator at run-time.

The designers may customize snapshotting in their models. Descriptors BEFORESNAPSHOT, AFTERSNAPSHOT, SNAPSHOT and RESTORE are dedicated for snapshot purpose.

• The SNAPSHOT descriptor specifies the variables (or objects) that need to be recorded in a snapshot. Each variable is written on a single line under the descriptor.

• The BEFORESNAPSHOT descriptor specifies a piece of arbitrary Python code to be executed immediately before a snapshot is taken. It usually is used to synchronize different parts of a model, because a snapshot can be requested at any time during a simulation, even when the model is in an unstable state. For example, if the model uses a native library that requires extra threads, the code under BEFORESNAPSHOT may synchronize those threads to ensure that all the variables are stable and meaningful. Similar to initializer and finalizer, the code here may contain function definitions, loops and other action-language-specific control structures.

• The AFTERSNAPSHOT descriptor is similar to the BEFORESNAPSHOT descriptor, except that the code specified under it is executed immediately after a snapshot is taken.

• the RESTORE descriptor is used to specify a piece of code that is executed after a snapshot is restored. For example, in Table 4.17, the code under the RESTORE descriptor starts playing (initially the CD is stopped) at time cd.time, whose value is restored by SVM, if the CD was playing at the time when the snapshot was taken.

Table 4.17: An example of the textual representation of a snapshot/restore description

In the example in Table 4.17, suppose cd is the instance of a CD-Rom controller that plays CD music. Its time attribute is constantly updated when the CD is playing, which indicates the current time in a track. To enable snapshotting during the playing, the designer may include such a description segment in his/her model. Its SNAPSHOT descriptor tells SVM that cd.time and cd.playing_before_snapshot (variables as attributes of the cd instance) need to be recorded in a snapshot. The code under BEFORESNAPSHOT pauses the playing so that the time attribute is not changed during the snapshot operation. When the snapshot operation is finished, the code under AFTERSNAPSHOT resumes the playing, if it is paused previously by the code under BEFORESNAPSHOT.

This model enables the user to play CD music, snapshot at any time during the playing and save the recorded state in a .snp file. Later when the user runs the .snp file with SVM, the variables specified under the SNAPSHOT descriptor are restored, and the code under the RESTORE descriptor is executed, which starts playing at exactly the recorded time.