Package ptolemy.actor

Class Director

  • All Implemented Interfaces:
    java.lang.Cloneable, Executable, Initializable, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    Direct Known Subclasses:
    CADirector, CaseDirector, CIDirector, CompositeOptimizer.OptimizerDirector, CompositeOptimizerUsingGradient.OptimizerDirector, CoroutineDirector, DDFDirector, DEDirector, DistributedDirector, DoNothingDirector, FSMDirector, MetroIIDirector, MetroIISystemCDirector, PetriNetDirector, ProcessDirector, PteraDirector, SequencedModelDirector, StaticSchedulingDirector, SysMLSequentialDirector, TesterDirector, TMDirector, TransformationRule.TransformationDirector
    public class Director
extends Attribute
implements Executable
    A Director governs the execution within a CompositeActor. A composite actor that contains a director is said to be opaque, and the execution model within the composite actor is determined by the contained director. This director is called the local director of a composite actor. A composite actor is also aware of the director of its container, which is referred to as its executive director. A director may also be contained by a CompositeEntity that is not a CompositeActor, in which case it acts like any other entity within that composite.

    A top-level composite actor is generally associated with a manager as well as a local director. The Manager has overall responsibility for executing the application, and is often associated with a GUI. Top-level composite actors have no executive director and getExecutiveDirector() will return null.

    A local director is responsible for invoking the actors contained by the composite. If there is no local director, then the executive director is given the responsibility. The getDirector() method of CompositeActor, therefore, returns the local director, if there is one, and otherwise returns the executive director. Thus, it returns whichever director is responsible for executing the contained actors, or null if there is none. Whatever it returns is called simply the director (vs. local director or executive director).

    A director implements the action methods (preinitialize(), initialize(), prefire(), fire(), postfire(), iterate(), and wrapup()). In this base class, default implementations are provided that may or may not be useful in specific domains. In general, these methods will perform domain-dependent actions, and then call the respective methods in all contained actors.

    The director also provides methods to optimize the iteration portion of an execution. This is done by setting the workspace to be read-only during an iteration. In this base class, the default implementation results in a read/write workspace. Derived classes (e.g. domain specific directors) should override the _writeAccessRequired() method to report that write access is not required. If none of the directors in a simulation require write access, then it is safe to set the workspace to be read-only, which will result in faster execution.

    Since:
    Ptolemy II 0.2
    Version:
    $Id$
    Author:
    Mudit Goel, Edward A. Lee, Lukito Muliadi, Steve Neuendorffer, John Reekie
    Pt.AcceptedRating:
    Yellow (neuendor)
    Pt.ProposedRating:
    Green (eal)

    • Field Detail

      • localClock

        public LocalClock localClock
        The clock that keeps track of current time of the model.

      • startTime

        public Parameter startTime
        The local time of model when this director is initialized. By default, this is blank, which indicates that the start time is the current time of the enclosing director when initialize() is invoked, or 0.0 if there is no enclosing director. This can be set to a double value to explicitly specify a start time. Note that if startTime is given a value that is different from the start time of the enclosing director, then local time may be ahead of or behind environment time during execution. Also note that some directors do not advance time (including PN and Rendezvous, for example), in which case, local time remains at the start time value throughout the execution.

      • stopTime

        public Parameter stopTime
        The stop time of the model. By default, this is blank, which means that no stop time is specified. If a stop time is specified, it must be a double, and when local time meets or exceeds the stop time, then postfire() returns false.

      • _actorsFinishedExecution

        protected java.util.Set _actorsFinishedExecution
        Set of actors that have returned false from postfire(), indicating that they do not wish to be iterated again.

      • _aspectForActor

        protected java.util.HashMap<NamedObj,​ActorExecutionAspect> _aspectForActor
        Contains a map of actors and the ExecutionAspect that is specified for the actor.

      • _aspectsPresent

        protected boolean _aspectsPresent
        True if any of the directed actors specifies a ExecutionAspect in the parameters and this ExecutionAspect exists on this or a hierarchy level above (i.e. has not been deleted).

      • _defaultMicrostep

        protected int _defaultMicrostep
        The director's default microstep.

      • _executionAspects

        protected java.util.List<ActorExecutionAspect> _executionAspects
        ExecutionAspects in the container of this director.

      • _finishRequested

        protected boolean _finishRequested
        Indicator that finish() has been called.

      • _initializables

        protected transient java.util.Set<Initializable> _initializables
        Set of objects whose (pre)initialize() and wrapup() methods should be slaved to these.

      • _nextScheduleTime

        protected java.util.HashMap<ActorExecutionAspect,​Time> _nextScheduleTime
        Next time the aspect wants to be executed.

      • _tokenSentToCommunicationAspect

        protected boolean _tokenSentToCommunicationAspect
        Flag set to true if a token has been sent to a communication aspect by any port/receiver where the aspect is enabled.

      • _stopRequested

        protected boolean _stopRequested
        Indicator that a stop has been requested by a call to stop().

      • _zeroTime

        protected Time _zeroTime
        Time with value 0.0.

    • Constructor Detail

      • Director

        public Director​(CompositeEntity container,
                java.lang.String name)
         throws IllegalActionException,
                NameDuplicationException
        Construct a director in the given container with the given name. The container argument must not be null, or a NullPointerException will be thrown. If the name argument is null, then the name is set to the empty string. Increment the version number of the workspace.
        Parameters:
        container - The container.
        name - The name of this director.
        Throws:
        IllegalActionException - If the name has a period in it, or the director is not compatible with the specified container, or if the time resolution parameter is malformed.
        NameDuplicationException - If the container already contains an entity with the specified name.

    • Method Detail

      • clone

        public java.lang.Object clone​(Workspace workspace)
                       throws java.lang.CloneNotSupportedException
        Clone the object into the specified workspace. The new object is not added to the directory of that workspace (you must do this yourself if you want it there).
        Overrides:
        clone in class Attribute
        Parameters:
        workspace - The workspace for the cloned object.
        Returns:
        The new Attribute.
        Throws:
        java.lang.CloneNotSupportedException - Not thrown in this base class
        See Also:
        NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

      • createSchedule

        public void createSchedule()
                    throws IllegalActionException
        Create the schedule for this director, if necessary. In this base class nothing is done.
        Throws:
        IllegalActionException - If the schedule can't be created.

      • delayDependency

        public Dependency delayDependency​(double delay)
        Return a boolean dependency representing a model-time delay of the specified amount. This base clear returns BooleanDependency.OTIMES_IDENTITY, which indicates a delay but does not quantify the delay.
        Parameters:
        delay - A non-negative delay.
        Returns:
        A boolean dependency representing a delay.

      • elapsedTimeSinceStart

        public long elapsedTimeSinceStart()
        Return the elapsed time (in milliseconds) since the start of execution of the model. The start of execution is defined to be the time after preinitialize() and initialize() has been called for all components, and before any component has been iterated. This method delegates to the manager so that the start time is consistent among all directors in a model.
        Returns:
        The time in milliseconds since the start of execution of the model.

      • finish

        public void finish()
        Request that after the current iteration finishes postfire() returns false, indicating to the environment that no more iterations should be invoked. To support domains where actor firings do not necessarily terminate, such as PN, you may wish to call stopFire() as well to request that those actors complete their firings.

      • fire

        public void fire()
          throws IllegalActionException
        Iterate all the deeply contained actors of the container of this director exactly once. This method is not functional, since an iteration of the deeply contained actors may change state in their postfire() method. The actors are iterated in the order that they appear on the list returned by deepEntityList(), which is normally the order in which they were created.

        This method is not synchronized on the workspace, so the caller should be.

        In this base class, an attempt is made to fire each actor exactly once, in the order they were created. Prefire is called once, and if prefire returns true, then fire is called once, followed by postfire. The return value from postfire is ignored. If the container is not an instance of CompositeActor, however, then this method does nothing.

        Specified by:
        fire in interface Executable
        Throws:
        IllegalActionException - If any called method of one of the associated actors throws it.

      • fireAt

        @Deprecated
public void fireAt​(Actor actor,
                   double time)
            throws IllegalActionException
        Deprecated.
        Instead of using double as time argument, use a time object instead. As of Ptolemy 4.1, replaced by fireAt(Actor, Time)
        Request a firing of the given actor at the given absolute time. This method is only intended to be called from within main simulation thread. Actors that create their own asynchronous threads should used the fireAtCurrentTime() method to schedule firings. This method calls fireAt(Actor, Time) method.
        Parameters:
        actor - The actor scheduled to be fired.
        time - The scheduled time.
        Throws:
        IllegalActionException - If the operation is not permissible (e.g. the given time is in the past).

      • fireAt

        public Time fireAt​(Actor actor,
                   Time time)
            throws IllegalActionException
        Request a firing of the given actor at the given model time. This base class ignores the request and returns a Time with value equal to the current time, unless this director is embedded within a model (and has an executive director), in which case, this base class requests that the executive director fire the container of this director at the requested time, adjusted by the current offset and drift of the local clock. It does this by delegating to fireContainerAt(Time, int) with the microstep argument set to 1.

        The intent of this method is to request a firing of the actor at the specified time, but this implementation does not assure that. In particular, if there is no executive director, it completely ignores the request. If there is an executive director, then it is not required to do the firing at the specified time. In particular, derived classes may override this method and modify the time of the firing, for example to prevent attempts to fire an actor in the past.

        Derived classes should override this method to return the time at which they expect to fire the specified actor. It is up to the actor to throw an exception if it is not acceptable for the time to differ from the requested time.

        Note that it is not correct behavior for a director to override this method to simply fire the specified actor. The actor needs to be fired as part of the regular execution cycle of that director, and that needs to occur after this method has returned.

        Note to authors of subclasses: Usually you should not override this method, but rather override fireAt(Actor, Time, int). However, we cannot make this method final because occasionally a domain will change the default starting microstep. E.g., DE does this.

        Parameters:
        actor - The actor scheduled to be fired.
        time - The requested time.
        Returns:
        An instance of Time with the current time value, or if there is an executive director, the time at which the container of this director will next be fired in response to this request.
        Throws:
        IllegalActionException - If there is an executive director and it throws it. Derived classes may choose to throw this exception for other reasons.
        See Also:
        fireAtCurrentTime(Actor)

      • fireAt

        public Time fireAt​(Actor actor,
                   Time time,
                   int microstep)
            throws IllegalActionException
        Request a firing of the given actor at the given model time with the given microstep. This method behaves exactly like fireAt(Actor, Time), except that it also passes up to the executive director the microstep, if there is one. This default implementation just delegates to fireContainerAt(Time, int)
        Parameters:
        actor - The actor scheduled to be fired.
        time - The requested time.
        microstep - The requested microstep.
        Returns:
        An instance of Time with the current time value, or if there is an executive director, the time at which the container of this director will next be fired in response to this request.
        Throws:
        IllegalActionException - If there is an executive director and it throws it. Derived classes may choose to throw this exception for other reasons.
        See Also:
        fireAtCurrentTime(Actor), fireContainerAt(Time)

      • fireAtCurrentTime

        public Time fireAtCurrentTime​(Actor actor)
                       throws IllegalActionException
        Request a firing of the given actor at the current model time or later. This base class simply calls fireAt(actor, getModelTime()) and returns whatever that returns. Note that fireAt() will modify the requested time if it happens to be in the past by the time it is to be posted on the event queue, which is exactly what we want. Note that the returned time may not match the value returned by getModelTime() prior to this call.

        Note that it is not correct behavior for a director to override this method to simply fire the specified actor. The actor needs to be fired as part of the regular execution cycle of that director, and that needs to occur after this method has returned.

        Parameters:
        actor - The actor to be fired.
        Returns:
        The time at which the specified actor will be fired, which in this case is whatever fireAt() returns.
        Throws:
        IllegalActionException - If this method is called before the model is running.
        See Also:
        fireAt(Actor, Time)

      • fireContainerAt

        public Time fireContainerAt​(Time time)
                     throws IllegalActionException
        Request a firing of the container of this director at the specified time and throw an exception if the executive director does not agree to do it at the requested time. If there is no executive director (this director is at the top level), then ignore the request. This is a convenience method provided because several directors need it. The requested microstep will be zero.
        Parameters:
        time - The requested time.
        Returns:
        The time that the executive director indicates it will fire this director, or an instance of Time with value equal to current time if there is no executive director.
        Throws:
        IllegalActionException - If the director does not agree to fire the actor at the specified time, or if there is no director.

      • fireContainerAt

        public Time fireContainerAt​(Time time,
                            int microstep)
                     throws IllegalActionException
        Request a firing of the container of this director at the specified time, adjusted by the current offset and drift of the local clock, and the specified microstep. Throw an exception if the executive director does not agree to do it at the requested time. If there is no executive director (this director is at the top level), then ignore the request and return a Time with value equal to the current time. The microstep argument is used by directors that implement SuperdenseTimeDirector.
        Parameters:
        time - The requested time.
        microstep - The requested microstep.
        Returns:
        The time that the executive director indicates it will fire this director, or an instance of Time with value equal to current time if there is no executive director.
        Throws:
        IllegalActionException - If the director does not agree to fire the actor at the specified time, or if there is no director.

      • scheduleContainedActors

        public boolean scheduleContainedActors()
                                throws IllegalActionException
        Return true if the next actor in the model governed by this director can be scheduled. The base class always returns true, but derived classes might override this.
        Returns:
        True if next actor to be fired can be scheduled.
        Throws:
        IllegalActionException - not thrown here.

      • getCausalityInterface

        public CausalityInterface getCausalityInterface()
        Return a causality interface for the composite actor that contains this director. This base class returns an instance of CausalityInterfaceForComposites, but subclasses may override this to return a domain-specific causality interface.
        Returns:
        A representation of the dependencies between input ports and output ports of the container.

      • getCurrentTime

        @Deprecated
public double getCurrentTime()
        Deprecated.
        As of Ptolemy II 4.1, replaced by getModelTime()
        Return the current time value of the model being executed by this director. This time can be set with the setCurrentTime method. In this base class, time never increases, and there are no restrictions on valid times.
        Returns:
        The current time value.
        See Also:
        setCurrentTime(double)

      • getDeadline

        public Time getDeadline​(NamedObj actor,
                        Time timestamp)
                 throws IllegalActionException
        Compute the deadline for an actor firing. In this base class, the deadline is set to the maximum value.
        Parameters:
        actor - The actor.
        timestamp - The timestamp of the event that triggered the firing.
        Returns:
        The deadline.
        Throws:
        IllegalActionException - Thrown in subclasses.

      • getEnvironmentTime

        public Time getEnvironmentTime()
        Get current environment time. This is the current time of the enclosing executive director, if there is one, and null otherwise.
        Returns:
        Environment time or null if the associated director is the top level director.

      • getGlobalTime

        public Time getGlobalTime()
                   throws IllegalActionException
        Return the global time for this model. The global time is defined to be the value returned by the @link{#getModelTime()} method of the top-level director in the model.
        Returns:
        The time of the top-level director in the model.
        Throws:
        IllegalActionException - If the top level is not an Actor.

      • getModelNextIterationTime

        public Time getModelNextIterationTime()
                               throws IllegalActionException
        Return the next time of interest in the model being executed by this director or the director of any enclosing model up the hierarchy. If this director is at the top level, then this default implementation simply returns the current time, since this director does not advance time. If this director is not at the top level, then return whatever the enclosing director returns.

        This method is useful for domains that perform speculative execution (such as CT). Such a domain in a hierarchical model (i.e. CT inside DE) uses this method to determine how far into the future to execute.

        Derived classes should override this method to provide an appropriate value, if possible. For example, the DEDirector class returns the time value of the next event in the event queue.

        Returns:
        The time of the next iteration.
        Throws:
        IllegalActionException - If time objects cannot be created.
        See Also:
        getModelTime()

      • getModelStartTime

        public final Time getModelStartTime()
                             throws IllegalActionException
        Return the start time parameter value, if it has been explicitly set. Otherwise, return the current time of the enclosing director, if there is one, and return a Time with value 0.0 otherwise.
        Returns:
        the start time parameter value.
        Throws:
        IllegalActionException - If the executive director throws it.

      • getModelStopTime

        public final Time getModelStopTime()
        Return the stop time parameter value, if it has been set, and otherwise, return a time with value Double.POSITIVE_INFINITY.
        Returns:
        the stop time parameter value.

      • getModelTime

        public Time getModelTime()
        Return the current time object of the model being executed by this director. This time can be set with the setModelTime method. In this base class, time never increases, and there are no restrictions on valid times.
        Returns:
        The current time.
        See Also:
        setModelTime(Time)

      • getNextIterationTime

        @Deprecated
public double getNextIterationTime()
                            throws IllegalActionException
        Deprecated.
        As of Ptolemy II 4.1, replaced by getModelNextIterationTime()
        Return the next time of interest in the model being executed by this director. This method is useful for domains that perform speculative execution (such as CT). Such a domain in a hierarchical model (i.e. CT inside DE) uses this method to determine how far into the future to execute.

        In this base class, we return the current time. Derived classes should override this method to provide an appropriate value, if possible.

        Note that this method is not made abstract to facilitate the use of the test suite.

        Returns:
        The time of the next iteration.
        Throws:
        IllegalActionException - If Time objects cannot be created.

      • getStartTime

        @Deprecated
public double getStartTime()
                    throws IllegalActionException
        Deprecated.
        As of Ptolemy II 4.1, replaced by getModelStartTime()
        Get the start time of the model. This base class returns a Time object with 0.0 as the value of the start time. Subclasses need to override this method to get a different start time. For example, CT director and DE director use the value of the startTime parameter to specify the real start time.
        Returns:
        The start time of the model.
        Throws:
        IllegalActionException - If the specified start time is invalid.

      • getStopTime

        @Deprecated
public double getStopTime()
                   throws IllegalActionException
        Deprecated.
        As of Ptolemy II 4.1, replaced by getModelStopTime()
        Get the stop time of the model. This base class returns a new Time object with Double.MAX_VALUE as the value of the stop time. Subclasses need to override this method to get a different stop time. For example, CT director and DE director use the value of the stopTime parameter to specify the real stop time.
        Returns:
        The stop time of the model.
        Throws:
        IllegalActionException - If the specified stop time is invalid.

      • getTimeResolution

        public final double getTimeResolution()
        Get the time resolution of the model. The time resolution is the value of the timeResolution parameter. This is the smallest time unit for the model.
        Returns:
        The time resolution of the model.
        See Also:
        setTimeResolution(double)

      • implementsStrictActorSemantics

        public boolean implementsStrictActorSemantics()
        Return true if this director assumes and exports the strict actor semantics, as described in this paper:

        A. Goderis, C. Brooks, I. Altintas, E. A. Lee, and C. Goble, "Heterogeneous Composition of Models of Computation," EECS Department, University of California, Berkeley, Tech. Rep. UCB/EECS-2007-139, Nov. 2007. http://www.eecs.berkeley.edu/Pubs/TechRpts/2007/EECS-2007-139.html

        In particular, a director that implements this interface guarantees that it will not invoke the postfire() method of an actor until all its inputs are known at the current tag. Moreover, it it will only do so in its own postfire() method, and in its prefire() and fire() methods, it does not change its own state. Thus, such a director can be used within a model of computation that has a fixed-point semantics, such as SRDirector and ContinuousDirector. This base class returns false.

        Returns:
        True if the director assumes and exports strict actor semantics.

      • initialize

        public void initialize()
                throws IllegalActionException
        Initialize the model controlled by this director. Set the current time to the start time or the current time of the executive director, and then invoke the initialize() method of this director on each actor that is controlled by this director. If the container is not an instance of CompositeActor, do nothing. This method should typically be invoked once per execution, after the preinitialization phase, but before any iteration. It may be invoked in the middle of an execution, if reinitialization is desired. Since type resolution has been completed and the current time is set, the initialize() method of a contained actor may produce output or schedule events. If stop() is called during this methods execution, then stop initializing actors immediately. This method is not synchronized on the workspace, so the caller should be.
        Specified by:
        initialize in interface Initializable
        Throws:
        IllegalActionException - If the initialize() method of one of the associated actors throws it.

      • initialize

        public void initialize​(Actor actor)
                throws IllegalActionException
        Initialize the given actor. This method is generally called by the initialize() method of the director, and by the manager whenever an actor is added to an executing model as a mutation. This method will generally perform domain-specific initialization on the specified actor and call its initialize() method. In this base class, only the actor's initialize() method of the actor is called and no domain-specific initialization is performed. Typical actions a director might perform include starting threads to execute the actor or checking to see whether the actor can be managed by this director. For example, a time-based domain (such as CT) might reject sequence based actors.
        Parameters:
        actor - The actor that is to be initialized.
        Throws:
        IllegalActionException - If the actor is not acceptable to the domain. Not thrown in this base class.

      • resumeActor

        public void resumeActor​(NamedObj actor)
                 throws IllegalActionException
        Resume the execution of an actor that was previously blocked because it didn't have all the resources it needed for execution. This method is called by ActorExecutionAspect actors. In this base class, the implementation is empty. Derived directors should override this method to handle resuming of actor execution.
        Parameters:
        actor - The actor that resumes execution.
        Throws:
        IllegalActionException - Not thrown here but in derived classes.

      • invalidateResolvedTypes

        public void invalidateResolvedTypes()
        Indicate that resolved types in the model may no longer be valid. This will force type resolution to be redone on the next iteration. This method simply defers to the manager, notifying it. If there is no container, or the container is not an instance of CompositeActor, or if it has no manager, do nothing.

      • invalidateSchedule

        public void invalidateSchedule()
        Indicate that a schedule for the model may no longer be valid, if there is a schedule. This method should be called when topology changes are made, or for that matter when any change that may invalidate the schedule is made. In this base class, the method does nothing. In derived classes, it will cause any static schedule information to be recalculated in the prefire method of the director.

      • isEmbedded

        public final boolean isEmbedded()
        Return true if this director is embedded inside an opaque composite actor contained by another composite actor. Note that some classes, such as RunCompositeActor, may return false even if they are actually embedded, but they want to be treated as if they were not.
        Returns:
        True if this directory is embedded inside an opaque composite actor contained by another composite actor.
        See Also:
        setEmbedded(boolean)

      • isFireFunctional

        public boolean isFireFunctional()
        Return false. This director iterates actors in its fire() method, which includes an invocation of their postfire() methods, so its fire method changes the state of the model.
        Specified by:
        isFireFunctional in interface Executable
        Returns:
        False.

      • isStrict

        public boolean isStrict()
                 throws IllegalActionException
        Return true. The transferInputs() method does not check whether the inputs are known before calling hasToken(), and consequently will throw an exception if inputs are not known. Thus, this director requires that inputs be known in order to be able to iterate. Derived classes that can tolerate unknown inputs should override this method to return false.
        Specified by:
        isStrict in interface Executable
        Returns:
        True.
        Throws:
        IllegalActionException - Thrown by subclass.

      • isStopRequested

        public boolean isStopRequested()
        Return true if stop has been requested.
        Returns:
        True if stop() has been called.
        See Also:
        stop()

      • iterate

        public int iterate​(int count)
            throws IllegalActionException
        Invoke a specified number of iterations of this director. 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. Also, if the stop() is called during this execution, then immediately stop iterating and return STOP_ITERATING.

        This base class method actually invokes prefire(), fire(), and postfire(), as described above, but a derived class may override the method to execute more efficient code.

        Specified by:
        iterate in interface Executable
        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.

      • mutexLockObject

        public java.lang.Object mutexLockObject()
        Return the object to use to obtain a mutex lock on this director. This base class returns this director itself, but subclasses may return something else.
        Returns:
        An object to use to obtain a lock on this director.

      • newReceiver

        public Receiver newReceiver()
        Return a new receiver of a type compatible with this director. In this base class, this returns an instance of Mailbox.
        Returns:
        A new Mailbox.

      • notifyTokenSentToCommunicationAspect

        public void notifyTokenSentToCommunicationAspect()
        Notify this director that a token was sent to a communication aspect. Some directors need to perform specific actions but the base class just sets a boolean flag.

      • postfire

        public boolean postfire()
                 throws IllegalActionException
        Return true if the director wishes to be scheduled for another iteration. This method is called by the container of this director to see whether the director wishes to execute anymore. It should not, in general, call postfire() on the contained actors.

        In this base class, return the false if stop() has been called since preinitialize(), and true otherwise. Derived classes that override this method need to respect this semantics. The protected variable _stopRequested indicates whether stop() has been called.

        Specified by:
        postfire in interface Executable
        Returns:
        True to continue execution, and false otherwise.
        Throws:
        IllegalActionException - Not thrown in this base class.

      • prefire

        public boolean prefire()
                throws IllegalActionException
        Return true if the director is ready to fire. This method is called by the container of this director to determine whether the director is ready to execute. It does not call prefire() on the contained actors. If this director is not at the top level of the hierarchy, then this base class synchronizes to environment time, making any necessary adjustments for drift or offset of the local clock.

        In this base class, assume that the director is always ready to be fired, and so return true. Domain directors should probably override this method to provide domain-specific behavior. However, they should call super.prefire() if they wish to propagate time as done here.

        Specified by:
        prefire in interface Executable
        Returns:
        True.
        Throws:
        IllegalActionException - Not thrown in this base class.

      • preinitialize

        public void preinitialize()
                   throws IllegalActionException
        Validate the attributes and then invoke the preinitialize() methods of all its deeply contained actors. This method is invoked once per execution, before any iteration, and before the initialize() method. Time is not set during this stage. So preinitialize() method of actors should not make use of time. They should wait until the initialize phase of the execution.

        This method also resets the protected variable _stopRequested to false, so if a derived class overrides this method, then it should also do that.

        This method is not synchronized on the workspace, so the caller should be.

        Specified by:
        preinitialize in interface Initializable
        Throws:
        IllegalActionException - If the preinitialize() method of one of the associated actors throws it.

      • requestInitialization

        public void requestInitialization​(Actor actor)
        Queue an initialization request with the manager. The specified actor will be initialized at an appropriate time, between iterations, by calling its preinitialize() and initialize() methods. This method is called by CompositeActor when an actor sets its container to that composite actor. Typically, that will occur when a model is first constructed, and during the execute() method of a ChangeRequest. In this base class, the request is delegated to the manager. If there is no manager, or if the container is not an instance of CompositeActor, then do nothing.
        Parameters:
        actor - The actor to initialize.

      • resume

        public void resume()
            throws IllegalActionException
        Start or resume the actor, which means (re)start the local clock. If the clock is not stopped then this has no effect.
        Throws:
        IllegalActionException - If the fireAt() request throws it.

      • setContainer

        public void setContainer​(NamedObj container)
                  throws IllegalActionException,
                         NameDuplicationException
        Specify the container. If the specified container is an instance of CompositeActor, then this becomes the active director for that composite. Otherwise, this is an attribute like any other within the container. If the container is not in the same workspace as this director, throw an exception. If this director is already an attribute of the container, then this has the effect only of making it the active director. If this director already has a container, remove it from that container first. Otherwise, remove it from the directory of the workspace, if it is present. If the argument is null, then remove it from its container. This director is not added to the workspace directory, so calling this method with a null argument could result in this director being garbage collected.

        If this method results in removing this director from a container that is a CompositeActor, then this director ceases to be the active director for that CompositeActor. Moreover, if the composite actor contains any other directors, then the most recently added of those directors becomes the active director.

        This method is write-synchronized to the workspace and increments its version number.

        Overrides:
        setContainer in class Attribute
        Parameters:
        container - The proposed container.
        Throws:
        IllegalActionException - If the action would result in a recursive containment structure, or if this director and container are not in the same workspace, or if the protected method _checkContainer() throws it.
        NameDuplicationException - If the name of this director collides with a name already in the container. This will not be thrown if the container argument is an instance of CompositeActor.
        See Also:
        Attribute.getContainer()

      • setCurrentTime

        @Deprecated
public void setCurrentTime​(double newTime)
                    throws IllegalActionException
        Deprecated.
        As of Ptolemy 4.1, replaced by setModelTime(ptolemy.actor.util.Time)
        Set a new value to the current time of the model, where the new time must be no earlier than the current time. Derived classes will likely override this method to ensure that the time is valid.
        Parameters:
        newTime - The new current simulation time.
        Throws:
        IllegalActionException - If the new time is less than the current time returned by getCurrentTime().
        See Also:
        getCurrentTime()

      • setEmbedded

        public final void setEmbedded​(boolean force)
        With a false argument, force this director to behave as if it is a top-level director even if it is not. This is used by composite actors such as RunCompositeActor that need for the inside director to behave as if it is running at the top level.
        Parameters:
        force - False to force this director to behave as if it were not embedded.
        See Also:
        isEmbedded()

      • setModelTime

        public void setModelTime​(Time newTime)
                  throws IllegalActionException
        Set a new value to the current time of the model.
        Parameters:
        newTime - The new current simulation time.
        Throws:
        IllegalActionException - If the new time is less than the current time returned by getCurrentTime().
        See Also:
        getModelTime()

      • setTimeResolution

        public void setTimeResolution​(double timeResolution)
        Set time resolution.
        Parameters:
        timeResolution - The new time resolution.
        See Also:
        getTimeResolution()

      • stop

        public void stop()
        Request that the director cease execution altogether. This causes a call to stop() on all actors contained by the container of this director, and sets a flag so that the next call to postfire() returns false.

        The stop() method requests immediate stopping. To give determinate stopping, call finish() so that the current iteration is completed.

        In multithreaded domains, Director.stopFire() is called to request that all actors conclude ongoing firings.

        Specified by:
        stop in interface Executable

      • stopFire

        public void stopFire()
        Request that execution of the current iteration stop. In this base class, the request is simply passed on to all actors that are deeply contained by the container of this director. For most domains, an iteration is a finite computation, so nothing further needs to be done here. However, for some process-oriented domains, the fire() method of the director is an unbounded computation. Those domains should override this method so that when it is called, it does whatever it needs to do to get the fire() method to return. Typically, it will set flags that will cause all executing threads to suspend. These domains 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, they should not assume the fire() method will be called again. It is possible that the wrapup() method will be called next. If the container is not an instance of CompositeActor, then this method does nothing.
        Specified by:
        stopFire in interface Executable

      • suggestedModalModelDirectors

        public java.lang.String[] suggestedModalModelDirectors()
        Return an array of suggested directors to be used with ModalModel. Each director is specified by its full class name. The first director in the array will be the default director used by a modal model. This base class delegates to the executive director, if there is one, and otherwise returns an array with only one element, "ptolemy.domains.modal.kernel.FSMDirector".
        Returns:
        An array of suggested directors to be used with ModalModel.

      • supportMultirateFiring

        public boolean supportMultirateFiring()
        Return a boolean to indicate whether a ModalModel under control of this director supports multirate firing. In this class, false is always returned. Subclasses may override this method to return true.
        Returns:
        False indicating a ModalModel under control of this director does not support multirate firing.

      • suspend

        public void suspend()
        Suspend the actor at the specified time. This will stop the local clock.

      • 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.). There is no assurance that the topology will be in a consistent state after this method returns. The topology should probably be recreated before attempting any further operations.

        This base class recursively calls terminate() on all actors deeply contained by the container of this director. Derived classes should override this method to release all resources in use and kill any sub-threads. Derived classes should not synchronize this method because it should execute as soon as possible. If the container is not an instance of CompositeActor, then this method does nothing.

        Specified by:
        terminate in interface Executable

      • transferInputs

        public boolean transferInputs​(IOPort port)
                       throws IllegalActionException
        Transfer data from an input port of the container to the ports it is connected to on the inside. The implementation in this base class transfers at most one token. Derived classes may override this method to transfer a domain-specific number of tokens.
        Parameters:
        port - The port to transfer tokens from.
        Returns:
        True if at least one data token is transferred.
        Throws:
        IllegalActionException - If the port is not an opaque input port.

      • transferOutputs

        public void transferOutputs()
                     throws IllegalActionException
        Transfer data from all output ports of the container to the ports they are connected to on the outside. This base class iterates over the ports in their natural order and delegates to transferOutputs(IOPort) to actually do the transfer. Override this method if you need to change the order in which the transfers occur.
        Throws:
        IllegalActionException - Not thrown in this base class.

      • transferOutputs

        public boolean transferOutputs​(IOPort port)
                        throws IllegalActionException
        Transfer data from an output port of the container to the ports it is connected to on the outside. The implementation in this base class transfers at most one token, but derived classes may transfer more than one token.
        Parameters:
        port - The port to transfer tokens from.
        Returns:
        True if at least one data token is transferred.
        Throws:
        IllegalActionException - If the port is not an opaque output port.

      • wrapup

        public void wrapup()
            throws IllegalActionException
        Invoke the wrapup() method of all the actors contained in the director's container. In this base class wrapup() is called on the associated actors in the order of their creation. If the container is not an instance of CompositeActor, then this method does nothing.

        This method should be invoked once per execution. None of the other action methods should be invoked after it in the execution. This method is not synchronized on the workspace, so the caller should be.

        Specified by:
        wrapup in interface Initializable
        Throws:
        IllegalActionException - If the wrapup() method of one of the associated actors throws it.

      • _actorFinished

        protected boolean _actorFinished​(NamedObj actor)
        Return true if the actor finished execution.
        Parameters:
        actor - The actor.
        Returns:
        True if the actor finished execution.

      • _consultTimeRegulators

        protected Time _consultTimeRegulators​(Time proposedTime)
                               throws IllegalActionException
        Consult all attributes contained by the container of this director that implement the TimeRegulator interface, if any, and return the smallest time returned by those regulators. If there are no such attributes, return the proposedTime argument.
        Parameters:
        proposedTime - The time proposed.
        Returns:
        The smallest time returned by a TimeRegulator, or the proposedTime if none.
        Throws:
        IllegalActionException - If a time regulator throws it.

      • _description

        protected java.lang.String _description​(int detail,
                                        int indent,
                                        int bracket)
                                 throws IllegalActionException
        Return a description of the object. The level of detail depends on the argument, which is an or-ing of the static final constants defined in the NamedObj class. Lines are indented according to to the level argument using the protected method _getIndentPrefix(). Zero, one or two brackets can be specified to surround the returned description. If one is specified it is the the leading bracket. This is used by derived classes that will append to the description. Those derived classes are responsible for the closing bracket. An argument other than 0, 1, or 2 is taken to be equivalent to 0. This method is read-synchronized on the workspace.
        Overrides:
        _description in class NamedObj
        Parameters:
        detail - The level of detail.
        indent - The amount of indenting.
        bracket - The number of surrounding brackets (0, 1, or 2).
        Returns:
        A description of the object.
        Throws:
        IllegalActionException - If thrown while getting the description of subcomponents.

      • _isEmbedded

        @Deprecated
protected boolean _isEmbedded()
        Deprecated.
        Use isEmbedded() instead
        Return true if this director is embedded inside an opaque composite actor contained by another composite actor.
        Returns:
        True if this directory is embedded inside an opaque composite actor contained by another composite actor.

      • _isTopLevel

        protected boolean _isTopLevel()
        Return true if this is a top-level director, or if it should always be handled as if it were a top-level director. Parts of this method is read synchronized on the workspace.
        Returns:
        True if this director is at the top-level.

      • getExecutionAspect

        public ActorExecutionAspect getExecutionAspect​(NamedObj actor)
                                        throws IllegalActionException
        Find the ExecutionAspect for the actor. Only one ExecutionAspect is returned at this point.
        Parameters:
        actor - The actor to be scheduled.
        Returns:
        The aspect.
        Throws:
        IllegalActionException - If thrown while getting the enable token or the decorator.

      • _transferInputs

        protected boolean _transferInputs​(IOPort port)
                           throws IllegalActionException
        Transfer at most one data token from the given input port of the container to the ports it is connected to on the inside. This method delegates the operation to the IOPort, so that the subclass of IOPort, TypedIOPort, can override this method to perform run-time type conversion.
        Parameters:
        port - The port to transfer tokens from.
        Returns:
        True if at least one data token is transferred.
        Throws:
        IllegalActionException - If the port is not an opaque input port.
        See Also:
        IOPort.transferInputs()

      • _transferOutputs

        protected boolean _transferOutputs​(IOPort port)
                            throws IllegalActionException
        Transfer at most one data token from the given output port of the container to the ports it is connected to on the outside..
        Parameters:
        port - The port to transfer tokens from.
        Returns:
        True if the port has an inside token that was successfully transferred. Otherwise return false (or throw an exception).
        Throws:
        IllegalActionException - If the port is not an opaque output port

      • _schedule

        protected boolean _schedule​(NamedObj actor,
                            Time timestamp)
                     throws IllegalActionException
        Schedule an actor for execution on a ExecutionAspect. If the actor can execute this method returns true. If resources are not available this method returns false.
        Parameters:
        actor - The actor.
        timestamp - The time the actor requests to be scheduled.
        Returns:
        True if actor was scheduled and can be fired.
        Throws:
        IllegalActionException - Thrown if parameters cannot be read, actor cannot be scheduled or container cannot be fired at future time.