Package ptolemy.domains.giotto.kernel

Class GiottoDirector

java.lang.Object

ptolemy.kernel.util.NamedObj

ptolemy.kernel.util.Attribute

ptolemy.actor.Director

ptolemy.actor.sched.StaticSchedulingDirector

ptolemy.domains.giotto.kernel.GiottoDirector

All Implemented Interfaces:

java.lang.Cloneable, Executable, Initializable, Changeable, Debuggable, DebugListener, Decorator, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

public class GiottoDirector
extends StaticSchedulingDirector
implements Decorator

This class implements a director for the Giotto model of computation without Giotto modes. Schedules are generated according to the Giotto semantics. The GiottoScheduler class contains methods to compute the schedules. The GiottoReceiver class implements the data flow between actors using double-buffering.

If the parameter synchronizeToRealTime is set to true, then the director will not process events until the real time elapsed since the model started matches the time stamp of the event. This ensures that the director does not get ahead of real time, but, of course, it does not ensure that the director keeps up with real time.

Since:

Ptolemy II 1.0

Version:

$Id$

Author:

Christoph Meyer Kirsch, Edward A. Lee, Haiyang Zheng, and Shanna-Shaye Forbes

See Also:

GiottoScheduler, GiottoReceiver

Pt.AcceptedRating:

Red (eal)

Pt.ProposedRating:

Yellow (cm)

Nested Class Summary

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

NamedObj.ContainedObjectsIterator

Field Summary

Fields

Modifier and Type	Field	Description
protected static double	_DEFAULT_GIOTTO_PERIOD	The static default Giotto period is 100ms.
Parameter	iterations	The number of times that postfire may be called before it returns false.
Parameter	period	The period of an iteration.
Parameter	synchronizeToRealTime	Specify whether the execution should synchronize to the real time.

Fields inherited from class ptolemy.actor.sched.StaticSchedulingDirector

_postfireReturns, _prefire

Fields inherited from class ptolemy.actor.Director

_actorsFinishedExecution, _aspectForActor, _aspectsPresent, _defaultMicrostep, _executionAspects, _finishRequested, _initializables, _nextScheduleTime, _stopRequested, _tokenSentToCommunicationAspect, _zeroTime, localClock, startTime, stopTime

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

Fields inherited from interface ptolemy.actor.Executable

COMPLETED, NOT_READY, STOP_ITERATING

Constructor Summary

Constructors

Constructor	Description
GiottoDirector()	Construct a director in the default workspace with an empty string as its name.
GiottoDirector(CompositeEntity container, java.lang.String name)	Construct a director in the given container with the given name.
GiottoDirector(Workspace workspace)	Construct a director in the given workspace with an empty name.

Method Summary

Modifier and Type	Method	Description
void	attributeChanged(Attribute attribute)	If the specified attribute is filename, then close the current file (if there is one) and open the new one.
java.lang.Object	clone(Workspace workspace)	Clone the object into the specified workspace.
DecoratorAttributes	createDecoratorAttributes(NamedObj target)	Return the decorated attributes for the target NamedObj.
java.util.List<NamedObj>	decoratedObjects()	Return a list of the entities deeply contained by the container of this resource scheduler.
void	fire()	Fire a complete iteration and advance time to the current time plus the period value.
Time	fireAt(Actor actor, Time time, int microstep)	Request a firing of the given actor at the given absolute time.
static int	getActorFrequency(NamedObj actor, GiottoDirector director)	Return the frequency of the specified actor by accessing a parameter named "frequency".
int	getIntPeriod()	Get the period of the giotto director in ms.
Time	getModelNextIterationTime()	Return the next time that this director expects activity.
double	getPeriod()	Get the period of the giotto director in ms.
void	initialize()	Initialize the actors associated with this director.
boolean	isGlobalDecorator()	Return false to indicate that this decorator should not decorate objects across opaque hierarchy boundaries.
Receiver	newReceiver()	Return a new receiver consistent with the Giotto domain.
boolean	postfire()	Return false if the system has finished executing, either by reaching the iteration limit, or by having an actor in the model return false in postfire.
boolean	prefire()	This method always return true.
void	preinitialize()	Preinitialize the actors associated with this director.
void	setContainer(NamedObj container)	Override the base class to first set the container, then establish a connection with any decorated objects it finds in scope in the new container.
java.lang.String[]	suggestedModalModelDirectors()	Return an array of suggested directors to be used with ModalModel.
boolean	transferInputs(IOPort port)	Transfer data from an input port of the container to the ports it is connected to on the inside.
boolean	transferOutputs(IOPort port)	Transfer data from this port to the ports it is connected to on the outside.

Methods inherited from class ptolemy.actor.sched.StaticSchedulingDirector

_setScheduler, addDebugListener, getScheduler, invalidateSchedule, isScheduleValid, removeDebugListener, resumeActor, setScheduler

Methods inherited from class ptolemy.actor.Director

_actorFinished, _consultTimeRegulators, _description, _isEmbedded, _isTopLevel, _schedule, _transferInputs, _transferOutputs, addInitializable, createSchedule, defaultDependency, delayDependency, elapsedTimeSinceStart, finish, fireAt, fireAt, fireAtCurrentTime, fireContainerAt, fireContainerAt, getCausalityInterface, getCurrentTime, getDeadline, getEnvironmentTime, getExecutionAspect, getGlobalTime, getModelStartTime, getModelStopTime, getModelTime, getNextIterationTime, getStartTime, getStopTime, getTimeResolution, implementsStrictActorSemantics, initialize, invalidateResolvedTypes, isEmbedded, isFireFunctional, isStopRequested, isStrict, iterate, mutexLockObject, notifyTokenSentToCommunicationAspect, preinitialize, removeInitializable, requestInitialization, resume, scheduleContainedActors, setCurrentTime, setEmbedded, setModelTime, setTimeResolution, stop, stopFire, supportMultirateFiring, suspend, terminate, transferOutputs, wrapup

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, _executeChangeRequests, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _notifyHierarchyListenersAfterChange, _notifyHierarchyListenersBeforeChange, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, _validateSettables, addChangeListener, addHierarchyListener, 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, 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

Methods inherited from interface ptolemy.kernel.util.Nameable

description, getContainer, getDisplayName, getFullName, getName, getName, setName

Field Detail

iterations

public Parameter iterations

The number of times that postfire may be called before it returns false. If the value is less than or equal to zero, then the execution will never return false in postfire, and thus the execution can continue forever. The default value is an IntToken with the value zero.

period

public Parameter period

The period of an iteration. This is a double that defaults to 0.1.

synchronizeToRealTime

public Parameter synchronizeToRealTime

Specify whether the execution should synchronize to the real time. This parameter must contain a BooleanToken. If this parameter is true, then do not process events until the elapsed real time matches the time stamp of the events. The value defaults to false.

_DEFAULT_GIOTTO_PERIOD

protected static final double _DEFAULT_GIOTTO_PERIOD

The static default Giotto period is 100ms.

See Also:

Constant Field Values

Constructor Detail

GiottoDirector

public GiottoDirector()
               throws IllegalActionException,
                      NameDuplicationException

Construct a director in the default workspace with an empty string as its name. The director is added to the list of objects in the workspace. Increment the version number of the workspace.

Throws:

IllegalActionException - If the name has a period in it, or the director is not compatible with the specified container.

NameDuplicationException - If the container already contains an entity with the specified name.

GiottoDirector

public GiottoDirector(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 - Container of the director.

name - Name of this director.

Throws:

IllegalActionException - If the director is not compatible with the specified container.

NameDuplicationException - If the name collides with an attribute in the container or if there is a name duplication during initialization.

GiottoDirector

public GiottoDirector(Workspace workspace)
               throws IllegalActionException,
                      NameDuplicationException

Construct a director in the given workspace with an empty name. The director is added to the list of objects in the workspace. Increment the version number of the workspace.

Parameters:

workspace - The workspace for this object.

Throws:

IllegalActionException - If there is an exception thrown by the super class or while initializing parameters.

NameDuplicationException - If the container reports an entity that duplicates an existing name during initialization.

Method Detail

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

If the specified attribute is filename, then close the current file (if there is one) and open the new one. If the specified attribute is period or synchronizeToRealTime, then cache the new values. If the specified attribute is timeResolution, then cache the new value.

Overrides:

attributeChanged in class Director

Parameters:

attribute - The attribute that has changed.

Throws:

IllegalActionException - If the specified attribute is filename and the file cannot be opened.

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). The result is an object with no container.

Overrides:

clone in class StaticSchedulingDirector

Parameters:

workspace - The workspace for the cloned object.

Returns:

The new object.

Throws:

java.lang.CloneNotSupportedException - Not thrown in this base class

See Also:

NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

createDecoratorAttributes

public DecoratorAttributes createDecoratorAttributes(NamedObj target)

Return the decorated attributes for the target NamedObj.

Specified by:

createDecoratorAttributes in interface Decorator

Parameters:

target - The NamedObj that will be decorated.

Returns:

The decorated attributes for the target NamedObj.

decoratedObjects

public java.util.List<NamedObj> decoratedObjects()

Return a list of the entities deeply contained by the container of this resource scheduler.

Specified by:

decoratedObjects in interface Decorator

Returns:

A list of the objects decorated by this decorator.

fire

public void fire()
          throws IllegalActionException

Fire a complete iteration and advance time to the current time plus the period value. A complete iteration consists of several minor cycles. At each minor cycle, iterate actors in the corresponding minor cycle schedule. After iterating the actors, increment time by the minor cycle time. Also, update the receivers that are destinations of all actors that will be invoked in the next minor cycle of the schedule. This works because all actors in Giotto are invoked periodically, and the ones that will be invoked in the next cycle are the ones that are completing invocation at the end of this cycle.

Specified by:

fire in interface Executable

Overrides:

fire in class StaticSchedulingDirector

Throws:

IllegalActionException - If this director does not have a container.

fireAt

public Time fireAt(Actor actor,
                   Time time,
                   int microstep)
            throws IllegalActionException

Request a firing of the given actor at the given absolute time. This method calculates the period of invocation of the specified actor (which is the period of this director divided by the actor's frequency), and if the requested time is ahead of current time by some multiple of the actor's period, then return the requested time.

Overrides:

fireAt in class Director

Parameters:

actor - The actor scheduled to be fired.

time - The requested time.

microstep - The microstep (ignored by this director).

Returns:

The time at which the actor passed as an argument will be fired.

Throws:

IllegalActionException - If the operation is not permissible (e.g. the given time is in the past).

See Also:

Director.fireAtCurrentTime(Actor), Director.fireContainerAt(Time)

getActorFrequency

public static int getActorFrequency(NamedObj actor,
                                    GiottoDirector director)
                             throws IllegalActionException

Return the frequency of the specified actor by accessing a parameter named "frequency". If there is no such parameter, then look for a decorator parameter named "frequency."

Parameters:

actor - The actor.

director - The director.

Returns:

The frequency of the actor firings.

Throws:

IllegalActionException - If thrown while getting the value of the frequency decorator attribute.

getIntPeriod

public int getIntPeriod()

Get the period of the giotto director in ms.

Returns:

int value of period in ms.

getModelNextIterationTime

public Time getModelNextIterationTime()

Return the next time that this director expects activity.

Overrides:

getModelNextIterationTime in class Director

Returns:

The time of the next iteration.

See Also:

Director.getModelTime()

getPeriod

public double getPeriod()

Get the period of the giotto director in ms.

Returns:

double value of period in ms.

initialize

public void initialize()
                throws IllegalActionException

Initialize the actors associated with this director. The order in which the actors are initialized is arbitrary.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class StaticSchedulingDirector

Throws:

IllegalActionException - If the initialize() method of one of the associated actors throws it.

isGlobalDecorator

public boolean isGlobalDecorator()

Return false to indicate that this decorator should not decorate objects across opaque hierarchy boundaries.

Specified by:

isGlobalDecorator in interface Decorator

Returns:

True if decorator is global.

newReceiver

public Receiver newReceiver()

Return a new receiver consistent with the Giotto domain.

Overrides:

newReceiver in class Director

Returns:

A new GiottoReceiver.

postfire

public boolean postfire()
                 throws IllegalActionException

Return false if the system has finished executing, either by reaching the iteration limit, or by having an actor in the model return false in postfire.

Specified by:

postfire in interface Executable

Overrides:

postfire in class StaticSchedulingDirector

Returns:

True if the execution is not finished.

Throws:

IllegalActionException - If the iterations parameter does not have a valid token.

prefire

public boolean prefire()
                throws IllegalActionException

This method always return true. If this director is at the top level, returning true means always ready to fire. If embedded, return true usually means that the current time of the outside domain is greater than or equal to the current time. However, when a giotto model is used inside a CT model, its inputs may either be DISCRETE or CONTINUOUS. When the inputs are of type CONTINUOUS, this method should always return true. To accommodate this requirement, the prefire method still returns true but an internal flag will be set to false and the fire and postfire methods are forced to do nothing.

Specified by:

prefire in interface Executable

Overrides:

prefire in class StaticSchedulingDirector

Returns:

True if the director is ready to run for one iteration.

Throws:

IllegalActionException - If time is set backwards.

preinitialize

public void preinitialize()
                   throws IllegalActionException

Preinitialize the actors associated with this director. Generate the giotto schedule.

Specified by:

preinitialize in interface Initializable

Overrides:

preinitialize in class Director

Throws:

IllegalActionException - If the preinitialize() method of one of the associated actors throws it.

setContainer

public void setContainer(NamedObj container)
                  throws IllegalActionException,
                         NameDuplicationException

Override the base class to first set the container, then establish a connection with any decorated objects it finds in scope in the new container.

Overrides:

setContainer in class Director

Parameters:

container - The container to attach this attribute to..

Throws:

IllegalActionException - If this attribute is not of the expected class for the container, or it has no name, or the attribute and container are not in the same workspace, or the proposed container would result in recursive containment.

NameDuplicationException - If the container already has an attribute with the name of this attribute.

See Also:

Attribute.getContainer()

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.

Overrides:

suggestedModalModelDirectors in class Director

Returns:

An array of suggested directors to be used with ModalModel.

See Also:

Director.suggestedModalModelDirectors()

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 port argument must be an opaque input port. If any channel of the input port has no data, then that channel is ignored. This method will transfer exactly one token on each input channel that has at least one token available. Update all receivers to which a token is transferred.

Overrides:

transferInputs in class Director

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 boolean transferOutputs(IOPort port)
                        throws IllegalActionException

Transfer data from this port to the ports it is connected to on the outside. This port must be an opaque output port. If any channel of this port has no data, then that channel is ignored. This method will transfer exactly one token on each output channel that has at least one token available.

Overrides:

transferOutputs in class Director

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.