Package ptolemy.domains.sequence.kernel

Class SequenceScheduler

  • All Implemented Interfaces:
    java.lang.Cloneable, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    Direct Known Subclasses:
    PartialSequenceScheduler
    public class SequenceScheduler
extends Scheduler
    The SequenceScheduler is responsible for creating and maintaining a schedule for the sequence models of computation. The scheduler accepts a list of elements from the director. This scheduler assembles three data structures that are used by SequenceSchedule: - A directed graph containing all actors scheduled by this scheduler - A hash table mapping each sequenced actor to an ordered list of dependent upstream actors - A control table, which identifies the sequenced actors that are dependent on other actors (for example, an If: Then (dependent actors) and :Else (dependent actors) - - Sequence numbers are reused within a composite actor. So, - Things with a sequence number but not a process number should be treated as upstream actors (note for SequenceDirector and ProcessDirector) - When the boundary (port) of a class or module is reached, no further items inside that module are executed The base class for schedulers. A scheduler schedules the execution order of the containees of a CompositeActor.

    A SequenceScheduler is contained by a SequencedModelDirector, and provides the schedule for it. The director will use this schedule to govern the execution of a CompositeActor.

    A schedule is represented by the Schedule class, and determines the order of the firing of the actors in a particular composite actor. In this base class, the default schedule fires the deeply contained actors in the order of their construction. A domain specific scheduler will override this to provide a different order.

    The schedule, once constructed, is cached and reused as long as the schedule is still valid. The validity of the schedule is set by the setValid() method. If the current schedule is not valid, then the schedule will be recomputed the next time the getSchedule() method is called. However, derived classes will usually override only the protected _getSchedule() method.

    The scheduler does not perform any mutations, and it does not listen for changes in the model. Directors that use this scheduler should normally invalidate the schedule when mutations occur.

    Since:
    Ptolemy II 10.0
    Version:
    $Id$
    Author:
    Elizabeth Latronico (Bosch), Thomas Mandl (Bosch), Edward A. Lee
    See Also:
    Schedule
    Pt.AcceptedRating:
    Red (beth)
    Pt.ProposedRating:
    Red (beth)

    • Field Detail

      • _DEFAULT_SCHEDULER_NAME

        protected static final java.lang.String _DEFAULT_SCHEDULER_NAME
        The default name.
        See Also:
        Constant Field Values

      • _scheduleUnexecutedActors

        protected boolean _scheduleUnexecutedActors
        Flag for appending all the unexecuted actors that are not sequenced at the end of the schedule.

      • _actorGraph

        public DirectedGraph _actorGraph
        The DirectedGraph for the model.

    • Constructor Detail

      • SequenceScheduler

        public SequenceScheduler()
        Construct a scheduler with no container(director) in the default workspace, the name of the scheduler is "Scheduler".

      • SequenceScheduler

        public SequenceScheduler​(Workspace workspace)
        Construct a scheduler in the given workspace with the name "Scheduler". If the workspace argument is null, use the default workspace. The scheduler is added to the list of objects in the workspace. Increment the version number of the workspace.
        Parameters:
        workspace - Object for synchronization and version tracking.

      • SequenceScheduler

        public SequenceScheduler​(Director container,
                         java.lang.String name)
                  throws IllegalActionException,
                         NameDuplicationException
        Construct a scheduler in the given container with the given name. The container argument must not be null, or a NullPointerException will be thrown. This attribute will use the workspace of the container for synchronization and version counts. If the name argument is null, then the name is set to the empty string. Increment the version of the workspace.
        Parameters:
        container - The container.
        name - The name of this attribute.
        Throws:
        IllegalActionException - If the attribute is not of an acceptable class for the container, or if the name contains a period.
        NameDuplicationException - If the name coincides with an attribute already in the container.

    • Method Detail

      • clone

        public java.lang.Object clone​(Workspace workspace)
                       throws java.lang.CloneNotSupportedException
        Clone the scheduler 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). The result is a new scheduler with no container, and no valid schedule.
        Overrides:
        clone in class Scheduler
        Parameters:
        workspace - The workspace for the cloned object.
        Returns:
        The new Scheduler.
        Throws:
        java.lang.CloneNotSupportedException - If one of the attributes cannot be cloned.
        See Also:
        NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

      • getSchedule

        public SequenceSchedule getSchedule​(java.util.List<SequenceAttribute> independentList,
                                    boolean validSequence)
                             throws IllegalActionException,
                                    NotSchedulableException
        Have to override this function in order to return a SequenceSchedule All additional code copied from Scheduler.java Have to also introduce own local variable, _cachedGetSchedule, to be of type SequenceSchedule The Sequence Scheduler takes one list as input - A list of independent sequenced actor attributes The sequence scheduler determines an additional list: - A list of sequenced actors that are dependent on control actors, or other actors It is possible to get the actor name from a sequence attribute by calling attributename.getContainer() Return the scheduling sequence as an instance of the Schedule class. For efficiency, this method returns a cached version of the schedule, if it is valid. Otherwise, it calls the protected method _getSchedule() to update the schedule. Derived classes normally override the protected method, not this one. The validity of the current schedule is set by the setValid() method. This method is read-synchronized on the workspace.
        Parameters:
        independentList - List of independent and dependent sequence attributes (and, associated actors, found by calling getContainer() on a SequenceAttribute) There must be at least one sequence attribute in the _independentList.
        validSequence - true if the schedule being returned is for a valid sequence schedule and not for a list of unexecuted actors, false otherwise.
        Returns:
        The sequence schedule for the given sequence attributes.
        Throws:
        IllegalActionException - If the scheduler has no container (a director), or the director has no container (a CompositeActor), or the scheduling algorithm throws it.
        NotSchedulableException - If the _getSchedule() method throws it. Not thrown in this base class, but may be needed by the derived schedulers.

      • getSchedule

        public SequenceSchedule getSchedule​(java.util.List<SequenceAttribute> independentList)
                             throws IllegalActionException,
                                    NotSchedulableException
        Return the schedule assuming that list of sequence numbers is for a valid schedule and not for a list of unexecuted actors after a valid schedule has been executed.
        Parameters:
        independentList - List of independent and dependent sequence attributes (and, associated actors, found by calling getContainer() on a SequenceAttribute) There must be at least one sequence attribute in the _independentList.
        Returns:
        The Schedule returned by the _getSchedule() method.
        Throws:
        IllegalActionException - If the scheduler has no container (a director), or the director has no container (a CompositeActor), or the scheduling algorithm throws it.
        NotSchedulableException - If the _getSchedule() method throws it.

      • unreachableActorList

        public java.util.List<Actor> unreachableActorList()
        Returns a list of unreachable actors found in the most recent call to Scheduler.getSchedule(). Actors are unreachable if they are not connected FIXME and have no sequence number?. , that are unreachable due to a lack of connected actors. These will be 'upstream' actors that are not upstream of any sequenced actor. This is done by returning a list of all actors with a 'false' entry in the hashtable _visitedNodes. This method is meant to be called after processGraph() has been called for all schedules. However, the SequenceScheduler itself does not know if there are any more schedules remaining. So, the director can call this function, once all schedules have been handled.
        Returns:
        (Possible empty) List of unreachable upstream actors

      • setContainer

        public void setContainer​(NamedObj container)
                  throws IllegalActionException,
                         NameDuplicationException
        FIXME: Keep this or change? Should the SequencedModelDirector be a sub-class of StaticSchedulingDirector? If it is, then can just use superclass function Specify the container. If the specified container is an instance of Director, then this becomes the active scheduler for that director. 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 scheduler is already an attribute of the container, then this has the effect only of making it the active scheduler. If this scheduler 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 Director, then this scheduler ceases to be the active scheduler for that CompositeActor. Moreover, if the director contains any other schedulers, then the most recently added of those schedulers becomes the active scheduler.

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

        Overrides:
        setContainer in class Scheduler
        Parameters:
        container - The proposed container.
        Throws:
        IllegalActionException - If the action would result in a recursive containment structure, or if this scheduler and container are not in the same workspace, or if the protected method _checkContainer() throws it.
        NameDuplicationException - If the name of this scheduler 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()

      • _getSchedule

        protected SequenceSchedule _getSchedule​(boolean validSequence)
                                 throws IllegalActionException,
                                        NotSchedulableException
        Beth - The SequenceScheduler assembles the structures that the SequenceSchedule will need to determine the next actor to fire. Note that, due to control branches, the exact firing order cannot be known before the control actors are actually fired. FIXME: In the future, some of this code should be factored out to execute when a new Scheduler is created (for example, creating the actor graph). The Process Director uses the same scheduler, but will have multiple schedules. Reschedule the model. In this base class, this method returns the actors contained by the CompositeActor in the order of their construction, i.e. the same order as returned by the CompositeActor.deepGetEntities() method. Derived classes should override this method to provide a domain-specific scheduling algorithm. This method is not intended to be called directly, but is called in turn by the getSchedule() method. This method is not synchronized on the workspace, because the getSchedule() method is.
        Parameters:
        validSequence - true if the schedule being returned is for a valid sequence schedule and not for a list of unexecuted actors, false otherwise.
        Returns:
        A Schedule of the deeply contained opaque entities in the firing order.
        Throws:
        IllegalActionException - If the scheduling algorithm throws it. Not thrown in this base class, but may be thrown by derived classes.
        NotSchedulableException - If the CompositeActor is not schedulable. Not thrown in this base class, but may be thrown by derived classes.
        See Also:
        CompositeEntity.deepEntityList()

      • unreachableActorExists

        public boolean unreachableActorExists()
        Prints a list of unreachable actors, that are unreachable due to a lack of connected actors. These will be 'upstream' actors that are not upstream of any sequenced actor. This is done by returning a list of all actors with a 'false' entry in the hashtable _visitedNodes. This method is meant to be called after processGraph() has been called for all schedules. However, the SequenceScheduler itself does not know if there are any more schedules remaining. So, the director can call this function, once all schedules have been handled.
        Returns:
        True if there is an unreachable actor

      • printSubGraph

        public void printSubGraph​(DirectedAcyclicGraph subGraph)
        Print the subGraph edges and nodes.
        Parameters:
        subGraph - The directed acyclic graph to print.

      • _getInitialValueParameterName

        protected static java.lang.String _getInitialValueParameterName​(TypedIOPort port,
                                                                int channel)
        Return the initialValueParameter name for each of the port .
        Parameters:
        port - The port.
        channel - The channel of the port.
        Returns:
        THe initialValueParameter name.