// // ActionPlan -- collection of actions to be performed in a defined order // @deftype ActionPlan <Collection, ActionType> CREATING - (void) setDefaultOrder: aSymbol; - (void) setAutoDrop: (BOOL)autoDrop; USING - getDefaultOrder; - (BOOL) getAutoDrop; - activateIn: swarmContext; - activateIn: swarmContext : arg1; - activateIn: swarmContext : arg1 : arg2; - activateIn: swarmContext : arg1 : arg2 : arg3; - getActivities; @end
ActionPlan has only three direct subtypes: ActionGroup, Schedule, and GenericSwarm. ActionGroup imposes only a few basic constraints on the order in which component actions are executed. Schedule is a special case that imposes a linear order on groups of actions based on explicit time values. A third kind of action plan, called a Swarm, is used to combine the execution of other action plans that are started for execution under a common context.
@deftype ActionPlan <ActionType>ActionPlan is not directly creatable. One of its subtypes must be created instead. ActionPlan inherits from a single type defined in defobj called ActionType. ActionType defines optional parameters and return values for any kind of executable actions, including ordinary functions and messages. By inheriting this standard support, an ActionPlan can be executed as a single complete computation, using the same kinds of dynamic calling support provided by the ActionType supertype. (.. Currently, a version of ActionType is defined in the defobj header, but is not otherwise implemented. The support for parameter and return types currently implemented within activity itself will move instead to the underlying defobj library.)
CREATING - (void) setDefaultOrder: aSymbol; - (void) setAutoDrop: (BOOL)autoDrop; USING - getDefaultOrder; - (BOOL) getAutoDrop;
The value for DefaultOrder is a symbol that may have one of the following values:
extern id <Symbol> Concurrent, Sequential, Randomized;The Concurrent value of the DefaultOrder option indicates that can actions be run in any order (including at the same time, if hardware and software to do this is available) without no impact on the net outcome of the actions. The claim that action results are independent of their execution order gives the processing machinery explicit leeway to execute them in any order it chooses. In the current implementation on a single, serial processor, actions are always processed sequentially even if marked concurrent, because that is the only way they can be. In future versions, however, special runtime processing modes may be defined even for a serial processor, which would mix up execution order just to confirm the independence of model results.
The Sequential value for the DefaultOrder option is the default. It specifies that the actions must always be executed in the same order as they occur in the plan. This order is ordinarily the same order in which actions are first created in the plan, unless actions are explicitly added elsewhere the collection that underlies a plan. This option is always the safest to assure predictability of results, but it excludes the ability to run the actions in parallel. To better understand and document a model design, it is worth annotating action plans with an explicit indication as to whether they do or do not depend on a Sequential order.
The Randomized value for the DefaultOrder option specifies that the model results do depend on execution order, but that the order in which the actions were created or added has no special significance. Instead, the method of dealing with order dependence is to generate a random order each time a collection of same-time actions is processed. The random order will be generated from an random number generator internal to the processing machinery.
When an option like AutoDrop is used, or whenever the contents of an action plan undergo a significant amount of dynamic update, the action plan would ordinarily be intended only for a single point of use. If AutoDrop is specified, a restriction against multiple active references is enforced. An error will be raised if two activities ever attempt to process a plan with AutoDrop enabled at the same time.
- activateIn: swarmContext; - activateIn: swarmContext : arg1; - activateIn: swarmContext : arg1 : arg2; - activateIn: swarmContext : arg1 : arg2 : arg3; - getActivities;The activateIn: messages are used to initialize a process for executing the actions in an ActionPlan. This process is controlled by an object called an Activity. The activateIn messages initialize an activity to run under the execution context passed as the swarmContext argument, and return the activity object just created. If the execution context is nil, an activity is returned that allows complete execution control by the caller. Otherwise, the execution context must be either an instance of GenericSwarm or SwarmActivity. (These objects are always maintained in one-to-one association with each other, either one of the pair is equivalent to the other as a swarmContext argument.)
If a top-level activity is created (swarmContext is nil), the created activity may be processed using activity processing commands such as run, step, etc. If an activity is created to run under a swarm context, the swarm itself has responsibility for advancing the subactivity according to its requirements for synchronization and control among all its activities. Activating a plan for execution under a swarm turns over control to the swarm to execute the subactivity as a more-or-less autonomous activity.
The various forms of activateIn: messages may be used to bind defined parameters of the action plan to actual argument values. (.. Currently, parameters on action plans are not fully supported, so only the basic form of activateIn: without additional arguments should be used.)
The getActivities message returns a collection of all activity objects which have been activated to process the action plan, and have not yet been dropped.