ptolemy.actor
Interface Executable

All Known Subinterfaces:
Actor, ConditionalBranchActor, CTDynamicActor, CTEventGenerator, CTStatefulActor, CTStepSizeControlActor, CTWaveformGenerator, DDI, TMActor, TypedActor, WirelessChannel
All Known Implementing Classes:
AbstractDDI, AtomicActor, AtomicWirelessChannel, CompositeActor, CSP, CSPActor, CTBaseIntegrator, CTCompositeActor, CTPeriodicSampler, CTTriggeredSampler, Dataflow, Director, EventSource, FirstOrderHold, FSMActor, LevelCrossingDetector, SDF, ThresholdMonitor, TMCompositeFacade, TypedAtomicActor, TypedCompositeActor, ZeroOrderHold

public interface Executable

This interface defines the action methods, which determine how an object can be invoked. It should be implemented by actors and directors. In an execution of an application, the preinitialize() and initialize() methods should be invoked exactly once, followed by any number of iterations, followed by exactly one invocation of the wrapup() method. An iteration is defined to be one firing of the prefire() method, followed by any number of firings of the fire() method, followed by one firing of the postfire() method. The prefire() method returns true to indicate that firing can occur. The postfire() method returns false if no further firings should occur. The initialize(), fire() and postfire() methods may produce output data. The initialize() method runs after the topology has stabilized (all higher-order function actors have executed) and type resolution has been done. The preinitialize() method runs before these have happened.

Since:
Ptolemy II 0.2
Version:
$Id: Executable.java,v 1.55 2004/04/13 02:57:31 cxh Exp $
Author:
Mudit Goel, Edward A. Lee, Lukito Muliadi, Steve Neuendorffer
Accepted Rating:
Green (davisj)
Proposed Rating:
Green (eal)

Field Summary
static int COMPLETED
          An indicator that the iterate() method completed successfully.
static int NOT_READY
          An indicator that the iterate() method did not complete because the actor was not ready (prefire() returned false).
static int STOP_ITERATING
          An indicator that the actor does not wish to be fired again.
 
Method Summary
 void fire()
          Fire the actor.
 void initialize()
          Begin execution of the actor.
 int iterate(int count)
          Invoke a specified number of iterations of the actor.
 boolean postfire()
          This method should be invoked once per iteration, after the last invocation of fire() in that iteration.
 boolean prefire()
          This method should be invoked once per iteration, before the first invocation of fire() in that iteration.
 void preinitialize()
          This method should be invoked exactly once per execution of a model, before any of these other methods are invoked.
 void stop()
          Request that execution of this Executable stop as soon as possible.
 void stopFire()
          Request that execution of the current iteration complete.
 void terminate()
          Terminate any currently executing model with extreme prejudice.
 void wrapup()
          This method is invoked exactly once per execution of an application.
 

Field Detail

COMPLETED

public static final int COMPLETED
An indicator that the iterate() method completed successfully.

See Also:
Constant Field Values

NOT_READY

public static final int NOT_READY
An indicator that the iterate() method did not complete because the actor was not ready (prefire() returned false).

See Also:
Constant Field Values

STOP_ITERATING

public static final int STOP_ITERATING
An indicator that the actor does not wish to be fired again.

See Also:
Constant Field Values
Method Detail

fire

public void fire()
          throws IllegalActionException
Fire the actor. This may be invoked several times between invocations of prefire() and postfire(). Output data may (and normally will) be produced. Typically, the fire() method performs the computation associated with an actor. This method is not required to have bounded execution. However, after endFire() is called, this method should return in bounded time.

Throws:
IllegalActionException - If firing is not permitted.

initialize

public void initialize()
                throws IllegalActionException
Begin execution of the actor. This is invoked exactly once after the preinitialization phase. Since type resolution is done in the preinitialization phase, along with topology changes that may be requested by higher-order function actors, an actor can produce output data and schedule events in the initialize() method.

Throws:
IllegalActionException - If execution is not permitted.

iterate

public int iterate(int count)
            throws IllegalActionException
Invoke a specified number of iterations of the actor. An iteration is equivalent to invoking prefire(), fire(), and postfire(), in that order. In an iteration, if prefire() returns true, then fire() will be called once, followed by postfire(). Otherwise, if prefire() returns false, fire() and postfire() are not invoked, and this method returns NOT_READY. If postfire() returns false, then no more iterations are invoked, and this method returns STOP_ITERATING. Otherwise, it returns COMPLETED.

An implementation of this method is not required to actually invoke prefire(), fire(), and postfire(). An implementation of this method must, however, perform the equivalent operations.

Parameters:
count - The number of iterations to perform.
Returns:
NOT_READY, STOP_ITERATING, or COMPLETED.
Throws:
IllegalActionException - If iterating is not permitted, or if prefire(), fire(), or postfire() throw it.

postfire

public boolean postfire()
                 throws IllegalActionException
This method should be invoked once per iteration, after the last invocation of fire() in that iteration. It may produce output data. It returns true if the execution can proceed into the next iteration, false if the actor does not wish to be fired again. This method typically wraps up an iteration, which may involve updating local state. In an opaque, non-atomic entity, it may also transfer output data. The execution of this method is bounded.

Returns:
True if the execution can continue.
Throws:
IllegalActionException - If postfiring is not permitted.

prefire

public boolean prefire()
                throws IllegalActionException
This method should be invoked once per iteration, before the first invocation of fire() in that iteration. It returns true if the iteration can proceed (the fire() method can be invoked). Thus this method will typically check preconditions for an iteration, if there are any. In an opaque, non-atomic entity, it may move data into an inner subsystem. The execution of this method is bounded.

Returns:
True if the iteration can proceed.
Throws:
IllegalActionException - If prefiring is not permitted.

preinitialize

public void preinitialize()
                   throws IllegalActionException
This method should be invoked exactly once per execution of a model, before any of these other methods are invoked. For actors, this is invoked prior to type resolution and may trigger changes in the topology, changes in the type constraints.

Throws:
IllegalActionException - If initializing is not permitted.

stop

public void stop()
Request that execution of this Executable stop as soon as possible. An implementation of this method should pass on the request to any contained executable objects. An implementation should also return false from postfire() to indicate to the caller that no further execution of this Executable is appropriate. After this method is called, the executable object should not be fired again. The stopFire() method, by contrast, requests that the current iteration be completed, but not that the entire execution be stopped. I.e., the Executable may be fired again after stopFire() is called.


stopFire

public void stopFire()
Request that execution of the current iteration complete. If an iteration is always a finite computation (the usual case), i.e. the fire() method always returns in finite time, then nothing needs to be done in this method, except possibly to pass on the request to any contained executable objects. This method is used to request that an unbounded computation suspend, returning control to the caller. Thus, if the fire() method does not normally return in finite time, then this method is used to request that it return. It should suspend execution in such a way that if the fire() method is called again, execution will resume at the point where it was suspended. However, it should not assume the fire() method will be called again. It is possible that the wrapup() method will be called next.


terminate

public void terminate()
Terminate any currently executing model with extreme prejudice. This method is not intended to be used as a normal route of stopping execution. To normally stop execution, call the finish() method instead. This method should be called only when execution fails to terminate by normal means due to certain kinds of programming errors (infinite loops, threading errors, etc.).

After this method completes, all resources in use should be released and any sub-threads should be killed. However, a consistent state is not guaranteed. The topology should probably be recreated before attempting any further operations. This method should not be synchronized because it must happen as soon as possible, no matter what.


wrapup

public void wrapup()
            throws IllegalActionException
This method is invoked exactly once per execution of an application. None of the other action methods should be be invoked after it. It finalizes an execution, typically closing files, displaying final results, etc. When this method is called, no further execution should occur.

Throws:
IllegalActionException - If wrapup is not permitted.