ptolemy.actor.sched
Class Scheduler

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.util.Attribute
          ptolemy.actor.sched.Scheduler

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

Direct Known Subclasses:

BaseSDFScheduler, CTScheduler, FixedPointScheduler, GiottoScheduler, GRScheduler, SRRandomizedScheduler

public class Scheduler
extends Attribute

The base class for schedulers. A scheduler schedules the execution order of the containees of a CompositeActor.

A scheduler is contained by a StaticSchedulingDirector, 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 0.2

Version:

$Id: Scheduler.java 57040 2010-01-27 20:52:32Z cxh $

Author:

Jie Liu, Steve Neuendorffer

See Also:

Schedule, Serialized Form

Accepted Rating:

Yellow (neuendor)

Proposed Rating:

Green (neuendor)

Nested Class Summary

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

NamedObj.ContainedObjectsIterator

Field Summary

private Schedule	_cachedGetSchedule
protected static java.lang.String	_DEFAULT_SCHEDULER_NAME The default name.
private boolean	_valid

Fields inherited from class ptolemy.kernel.util.NamedObj

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

Constructor Summary

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

Scheduler(Director container, java.lang.String name)
Construct a scheduler in the given container with the given name.

Scheduler(Workspace workspace)
Construct a scheduler in the given workspace with the name "Scheduler".

Method Summary

protected Schedule	_getSchedule() Reschedule the model.
java.lang.Object	clone(Workspace workspace) Clone the scheduler into the specified workspace.
Schedule	getSchedule() Return the scheduling sequence as an instance of the Schedule class.
boolean	isValid() Return true if the current schedule is valid.
void	setContainer(NamedObj container) Specify the container.
void	setValid(boolean valid) Validate/invalidate the current schedule by giving a true/false argument.

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, _debug, _debug, _debug, _debug, _debug, _description, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _recordDecoratedAttributes, _removeAttribute, _splitName, _stripNumericSuffix, _validateSettables, addChangeListener, addDebugListener, attributeChanged, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, 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, propagateExistence, propagateValue, propagateValues, removeChangeListener, removeDebugListener, 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

_valid

private boolean _valid

_cachedGetSchedule

private Schedule _cachedGetSchedule

Constructor Detail

Scheduler

public Scheduler()

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

Scheduler

public Scheduler(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.

Scheduler

public Scheduler(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 Attribute

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 Schedule getSchedule()
                     throws IllegalActionException,
                            NotSchedulableException

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.

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. Not thrown in this base class, but may be needed by the derived schedulers.

isValid

public boolean isValid()

Return true if the current schedule is valid.

Returns:

true if the current schedule is valid.

setContainer

public void setContainer(NamedObj container)
                  throws IllegalActionException,
                         NameDuplicationException

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 Attribute

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()

setValid

public void setValid(boolean valid)

Validate/invalidate the current schedule by giving a true/false argument. A true argument will indicate that the current schedule is valid and can be returned immediately when schedule() is called without running the scheduling algorithm. A false argument will invalidate it.

Parameters:

valid - True to set the current schedule to valid.

_getSchedule

protected Schedule _getSchedule()
                         throws IllegalActionException,
                                NotSchedulableException

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.

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()