ptolemy.domains.ptera.kernel

Class SchedulingRelation

java.lang.Object

ptolemy.kernel.util.NamedObj

ptolemy.kernel.Relation

ptolemy.kernel.ComponentRelation

ptolemy.domains.modal.kernel.Transition

ptolemy.domains.ptera.kernel.SchedulingRelation

All Implemented Interfaces:

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

public class SchedulingRelation
extends Transition

A scheduling relation is an edge from one Ptera event to another. If it is not a cancelling edge, then processing the event at the starting point of the edge causes the one at the end point to be scheduled after a certain amount of model-time delay, if the guard of the scheduling relation is satisfied. If it is a cancelling edge, then processing the first event causes the second one to be cancelled if it is already scheduled in the containing Ptera controller's event queue.

A scheduling relation may carry argument values to be supplied to the event to be scheduled, who has parameters defined on it. The number and types of the evaluated arguments must match those of the parameters declared by the event.

If the guard of a scheduling relation is omitted, it is defaulted to true, which means the scheduling relation is unconditional.

A scheduling relation can be assigned a priority, which is an integer number. The default priority is 0. Priorities are used to order the scheduling relations from the same event. Scheduling relations with higher priorities (smaller priority numbers) are scheduled before those with lower priorities from the same event, if they are scheduled at exactly the same time in the future.

Since:

Ptolemy II 8.0

Version:

$Id$

Author:

Thomas Huining Feng

Pt.AcceptedRating:

Red (tfeng)

Pt.ProposedRating:

Yellow (tfeng)

Nested Class Summary

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

NamedObj.ContainedObjectsIterator

Field Summary

Fields

Modifier and Type	Field and Description
StringAttribute	arguments The attribute for arguments.
Parameter	canceling A Boolean-valued parameter that defines whether this scheduling relation is cancelling.
StringAttribute	delay The attribute for the model-time delay.
Priority	priority The priority of this scheduling relation.
StringParameter	triggers A comma-separated list of port names and variable names to be monitored.

Fields inherited from class ptolemy.domains.modal.kernel.Transition

annotation, defaultTransition, error, exitAngle, fsmTransitionParameterName, gamma, guardExpression, history, immediate, nondeterministic, outputActions, preemptive, refinementName, setActions, showFSMTransitionParameter, termination

Fields inherited from class ptolemy.kernel.Relation

_linkList

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
SchedulingRelation(PteraController container, java.lang.String name) Construct a scheduling relation with the given name contained by the specified entity.

Method Summary

Modifier and Type	Method and Description
void	attributeChanged(Attribute attribute) React to a change in an attribute.
java.lang.Object	clone(Workspace workspace) Clone the scheduling relation into the specified workspace.
Token	getArguments(ParserScope scope) Evaluate the parse tree of the arguments and return an ArrayToken or RecordToken that contains the values of those arguments in the given parser scope.
double	getDelay(ParserScope scope) Evaluate the delay parameter in the given parse scope and return its value.
java.lang.String	getLabel() Return a string describing this scheduling relation.
java.util.List<NamedObj>	getTriggers() Get the list of ports or variables referred to in the triggers attributes.
boolean	isCanceling() Return whether this scheduling relation is cancelling.
boolean	isEnabled(ParserScope scope) Evaluate the guard in the given parser scope, and return whether this scheduling relation is enabled (with its guard evaluated to true).

Methods inherited from class ptolemy.domains.modal.kernel.Transition

_checkPort, choiceActionList, commitActionList, destinationState, getFullLabel, getGuardExpression, getParseTreeEvaluator, getRefinement, isDefault, isEnabled, isErrorTransition, isHistory, isImmediate, isNondeterministic, isPreemptive, isTermination, setContainer, setFsmTransitionParameter, setGuardExpression, sourceState

Methods inherited from class ptolemy.kernel.ComponentRelation

_checkContainer, _checkRelation, _propagateExistence, deepLinkedPortList, deepLinkedPorts, getContainer, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, setName, unlinkAll

Methods inherited from class ptolemy.kernel.Relation

_description, _getContainedObject, link, linkedObjectsList, linkedPortList, linkedPortList, linkedPorts, linkedPorts, numLinks, relationGroupList, unlink

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, addDebugListener, 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, 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

arguments

public StringAttribute arguments

The attribute for arguments. Its value must be evaluated to an ArrayToken or RecordToken, though this evaluation is performed only when this scheduling relation is to be considered by the starting event but not when this attribute is set by the designer.

canceling

public Parameter canceling

A Boolean-valued parameter that defines whether this scheduling relation is cancelling.

delay

public StringAttribute delay

The attribute for the model-time delay. Its value must be evaluated to a ScalarToken, though this evaluation is performed only when this scheduling relation is to be considered by the starting event but not when this attribute is set by the designer.

priority

public Priority priority

The priority of this scheduling relation.

triggers

public StringParameter triggers

A comma-separated list of port names and variable names to be monitored.

Constructor Detail

SchedulingRelation

public SchedulingRelation(PteraController container,
                          java.lang.String name)
                   throws IllegalActionException,
                          NameDuplicationException

Construct a scheduling relation with the given name contained by the specified entity. The container argument must not be null, or a NullPointerException will be thrown. This transition 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.

Parameters:

container - The container.

name - The name of the scheduling relation.

Throws:

IllegalActionException - If the container is incompatible with this scheduling relation.

NameDuplicationException - If the name coincides with any relation already in the container.

Method Detail

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

React to a change in an attribute. If the changed attribute is the arguments parameter, evaluate the arguments. If the changed attribute is delay, evaluate the delay. Then, check whether the combination of this scheduling relation's parameters is reasonable. If the scheduling relation is cancelling, then its arguments parameter must specify an empty list ("()"), and its delay must be evaluated to 0.0.

Overrides:

attributeChanged in class Transition

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - If thrown by the superclass attributeChanged() method, or the changed attribute is the arguments parameter or the delay parameter and is given an expression that does not evaluate to a boolean value, or this scheduling relation is set to cancelling but the values of arguments and delay are not acceptable.

clone

public java.lang.Object clone(Workspace workspace)
                       throws java.lang.CloneNotSupportedException

Clone the scheduling relation into the specified workspace. This calls the base class and then sets the attribute public members to refer to the attributes of the new scheduling relation.

Overrides:

clone in class Transition

Parameters:

workspace - The workspace for the new scheduling relation.

Returns:

A new scheduling relation.

Throws:

java.lang.CloneNotSupportedException - If a derived class contains an attribute that cannot be cloned.

See Also:

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

getArguments

public Token getArguments(ParserScope scope)
                   throws IllegalActionException

Evaluate the parse tree of the arguments and return an ArrayToken or RecordToken that contains the values of those arguments in the given parser scope.

Parameters:

scope - The parser scope in which the arguments are evaluated.

Returns:

The token containing the values of those arguments, which must be of type ArrayToken or RecordToken.

Throws:

IllegalActionException - If the evaluation is unsuccessful.

getDelay

public double getDelay(ParserScope scope)
                throws IllegalActionException

Evaluate the delay parameter in the given parse scope and return its value.

Parameters:

scope - The parser scope in which the delay is evaluated.

Returns:

The value of the model-time delay.

Throws:

IllegalActionException - If the evaluation is unsuccessful.

getLabel

public java.lang.String getLabel()

Return a string describing this scheduling relation. The string has up to three lines. The first line is the guard expression, preceded by "guard: ". The second line is the delay expression, preceded by "δ: " (unicode for the delta character). The third line is the list of arguments, preceded by "arguments: ". If any of these is missing, then the corresponding line is omitted.

Overrides:

getLabel in class Transition

Returns:

A string describing this transition.

getTriggers

public java.util.List<NamedObj> getTriggers()
                                     throws IllegalActionException

Get the list of ports or variables referred to in the triggers attributes. When a port receives a token or a variable's value is changed, the event that this scheduling relation points to is triggered (if that event is still in the event queue). Only ports belonging to the container of this scheduling relation (which is an PteraController) is searched for. Variables belonging to this scheduling relation, its container, and containers of the container are searched for. Variable names can contain dots.

Returns:

A list of ports and variables.

Throws:

IllegalActionException - If the value of the triggers parameter cannot be obtained.

isCanceling

public boolean isCanceling()

Return whether this scheduling relation is cancelling.

Returns:

True if this scheduling relation is cancelling.

isEnabled

public boolean isEnabled(ParserScope scope)
                  throws IllegalActionException

Evaluate the guard in the given parser scope, and return whether this scheduling relation is enabled (with its guard evaluated to true).

Overrides:

isEnabled in class Transition

Parameters:

scope - The parser scope in which the guard is to be evaluated.

Returns:

True if the transition is enabled and some event is detected.

Throws:

IllegalActionException - If thrown when evaluating the guard.