Re: termination test (readme first!)

[Roger M. Burkhart]

Rick,

Just a little more detail on terminating simulations.  For your question:

> Anyway, in the new swarm, the above is replaced with
> 
>    [swarmActivity run];
> 
> Thus there is no explicit place for me to do my own side
> test to stop the execution.

Manor gave the correct answer: 

> >Now, as far as stopping the simulation (another issue raised by Rick),
> >you can schedule a termination verification procedure, which internally
> >does [getTopLevelActivity() terminate] if it is OK to stop the simulation. 
> >This will cause the original [swarmActivity run] call (in main) to return.

This is an area that's changed in the new release.  The only way to stop
things now is to explictly schedule the termination test.  The test can be
either in a function (using the new createActionCall) or a message, but
must be added explicitly to the schedule at some point, or else be
included in some action you're running already.

In any case, the way you stop the whole simulation is to send the "terminate"
message to the top-level activity the original "run" message was sent to.
Thus, if the swarmActivity variable in your [swarmActivity run] above is
referenceable in the scheduled action (for example, as a global variable),
you could stop execution with the message:

  [swarmActivity terminate];

If you don't have direct reference to the original running activity (for
example, it's a local variable), you can always get it with the
getopLevelActivity() macro.  Thus, you can also use:

  [getTopLevelActivity() terminate];

The terminate message stops the entire tree of running activities, and
returns from the original run message with a status of Completed.  You
can also use it to prune off various branches of running subactivities,
which could become important when running dynamically nested swarms.
None of this is in the documentation yet, which has gotten out of date
with multiple interface changes.

We used to have a public "setBreakFunction:" message which allowed you
to set a function returning BOOL which provided another way to stop
running activities.  This message is no longer in the public interface,
though something like it is used internally in more specialized ways.
We switched our user event polling to explicit scheduling because it's
much faster than checking a break function on every action.  Scheduling
your own actions is also now the one supported way for you to terminate
things yourself.

A priority right now is to get documentation back into sync with the
release.

Roger