Script - Version 1.0 February 1998

Runtime scripting for Swarm objects

by Benedikt Stefansson benedikt@ucla.edu


Synopsis

//
// Script - a runtime scripter for Swarm objects
//
SETTING
-           setFile: (char *) aFileName;
-           logEvents: (char *) aLogName;
-           buildActions: (id) m; 
-           activateIn: (id) swarmContext;


Description

The Script class is used to read and execute messages to objects in a Swarm simulation at runtime. This class runs as a sub-swarm in a top-level Swarm, usually the ModelSwarm. It uses probes and the activity library, in addition to it's own internal probe-like objects, to schedule events according to a script, which allows us to alter the models behavior in a deterministic fashion without recompiling the application.

The Script object executes method calls to objects, and in order to do so it must be able to retrieve a pointer to the object. It does so in two ways:

Using Script

The format for a script is as follows:

target || getMethod time method arg1 ... argN

Scripts must begin and end with the @begin,@end statements, which must be at the beginning of a line. You can also put in comments, both at the beginning of a script and inbetween lines of commands, starting with a "#". Here is an example script:

# A comment
@begin
model 2 printX:Y: 1 2
model 4 printX:Y: 2 4
model 6 printX:Y: 3 6
model 8 shockMarketTo: -1
# Another comment 
model 10 ping 
getMarket 20 setAlpha: 70
getMarket 30 setAlpha: 50
getMarket 40 setAlpha: 70
@end

In this example the first 5 lines tell the Script object to call the ModelSwarm and exectute three different methods, at time steps 2,4,6,8 and 10. The first method is printX:Y: which takes two arguments, and will be executed at time steps 2,4 and 6. The second method is shockMarketTo: which takes one argument and will be executed at timestep 8. The third method is ping which takes no argument and will be executed at time step 10.

The other three messages all go to an object that the ModelSwarm has access to. We retrieve the pointer to that object by calling the getMarket method. It gets three messages, at timesteps 20,30 and 40. The method name used is setAlpha: and it takes one argument.

Creating and activating a Script object

Script executes as a subswarm in a top-level Swarm, such as the ModelSwarm. You should think of it as a schedule, and create it along with the other schedules in the Swarm. Here is an example of how we enable a script called filename:

  script=[Script create: [self getZone]];
  [script setFile: "filename"];
  [script buildActions: self];

Where you activate the Swarm's schedules, also put this line:

  [script activateIn: self];

And the activity library will take care of merging the different schedules into the right order.

If you would like to log the events that the script executes put this line before the line [script buildActions: self] above (the name filename.log can of course be any arbitrary string):

  [script logEvents: "filename.log"];

Some caveats

This class is fairly extensively debugged, and should output some helpful error messages if your script has problems. The only known bug at this point is that when you create and drop Scripts as parts of a subswarm, such as in the simpleExperBug example from the tutorial, occasionally the probeLibrary seems to generate a damaged probe to the ModelSwarm. The author is studying the problem.


Benedikt Stefansson <benedikt@ucla.edu>
Last modified: Thu Feb 5 23:20:50 PST 1998