ptolemy.domains.sequence.kernel

Class SequenceScheduler

java.lang.Object

ptolemy.kernel.util.NamedObj

ptolemy.kernel.util.Attribute

ptolemy.actor.sched.Scheduler

ptolemy.domains.sequence.kernel.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)

Nested Class Summary

Nested classes/interfaces inherited from class ptolemy.kernel.util.NamedObj

NamedObj.ContainedObjectsIterator

Field Summary

Fields

Modifier and Type	Field and Description
DirectedGraph	_actorGraph The DirectedGraph for the model.
(package private) java.util.Hashtable<Actor,java.util.List<Node>>	_actorGraphNodeList Hashtable of actors to graph nodes FIXME: Is there a better way to do this?
(package private) boolean	_allowDisconnectedGraphs Cache of the value of allowDisconnectedGraphs.
protected static java.lang.String	_DEFAULT_SCHEDULER_NAME The default name.
protected boolean	_scheduleUnexecutedActors Flag for appending all the unexecuted actors that are not sequenced at the end of the schedule.
(package private) java.util.Hashtable<Node,java.lang.Boolean>	_visitedNodes Hashtable of graph nodes to a boolean value Keeps track of which nodes in the graph have been visited (in other words, can be scheduled somewhere) Anything that has not been visited is unreachable.

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _deferChangeRequests, _elementName, _isPersistent, _verbose, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS

Constructor Summary

Constructors

Constructor and Description
SequenceScheduler() Construct a scheduler with no container(director) in the default workspace, the name of the scheduler is "Scheduler".
SequenceScheduler(Director container, java.lang.String name) Construct a scheduler in the given container with the given name.
SequenceScheduler(Workspace workspace) Construct a scheduler in the given workspace with the name "Scheduler".

Method Summary

Modifier and Type	Method and Description
protected static java.lang.String	_getInitialValueParameterName(TypedIOPort port, int channel) Return the initialValueParameter name for each of the port .
protected SequenceSchedule	_getSchedule(boolean validSequence) Beth - The SequenceScheduler assembles the structures that the SequenceSchedule will need to determine the next actor to fire.
java.lang.Object	clone(Workspace workspace) Clone the scheduler into the specified workspace.
SequenceSchedule	getSchedule(java.util.List<SequenceAttribute> independentList) 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.
SequenceSchedule	getSchedule(java.util.List<SequenceAttribute> independentList, boolean validSequence) 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.
void	printSubGraph(DirectedAcyclicGraph subGraph) Print the subGraph edges and nodes.
void	setContainer(NamedObj container) FIXME: Keep this or change?
boolean	unreachableActorExists() Prints a list of unreachable actors, that are unreachable due to a lack of connected actors.
java.util.List<Actor>	unreachableActorList() Returns a list of unreachable actors found in the most recent call to Scheduler.getSchedule().

Methods inherited from class ptolemy.actor.sched.Scheduler

_getSchedule, getSchedule, isValid, setValid

Methods inherited from class ptolemy.kernel.util.Attribute

_checkContainer, _getContainedObject, _propagateExistence, getContainer, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, setName, updateContent

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _containedDecorators, _copyChangeRequestList, _debug, _debug, _debug, _debug, _debug, _description, _executeChangeRequests, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _notifyHierarchyListenersAfterChange, _notifyHierarchyListenersBeforeChange, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, _validateSettables, addChangeListener, addDebugListener, addHierarchyListener, attributeChanged, attributeDeleted, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, decorators, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getElementName, getFullName, getModelErrorHandler, getName, getName, getPrototypeList, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, notifyOfNameChange, propagateExistence, propagateValue, propagateValues, removeAttribute, removeChangeListener, removeDebugListener, removeHierarchyListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, toString, uniqueName, validateSettables, workspace

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

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.

_allowDisconnectedGraphs

boolean _allowDisconnectedGraphs

Cache of the value of allowDisconnectedGraphs.

_actorGraph

public DirectedGraph _actorGraph

The DirectedGraph for the model.

_actorGraphNodeList

java.util.Hashtable<Actor,java.util.List<Node>> _actorGraphNodeList

Hashtable of actors to graph nodes FIXME: Is there a better way to do this?

_visitedNodes

java.util.Hashtable<Node,java.lang.Boolean> _visitedNodes

Hashtable of graph nodes to a boolean value Keeps track of which nodes in the graph have been visited (in other words, can be scheduled somewhere) Anything that has not been visited is unreachable. Note: TestExceptionHandler actors are not included in this hashtable That way, we can use the easy .contains(false) on the hash table to see if an unreachable node exists, instead of having to check each node and make sure it's not a TestExceptionHandler

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.