ptolemy.domains.metroII.kernel

Class MetroIIPtidesDirector

java.lang.Object

ptolemy.kernel.util.NamedObj

ptolemy.kernel.util.Attribute

ptolemy.actor.Director

ptolemy.domains.de.kernel.DEDirector

ptolemy.domains.metroII.kernel.MetroIIDEDirectorForPtides

ptolemy.domains.metroII.kernel.MetroIIPtidesDirector

All Implemented Interfaces:

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

public class MetroIIPtidesDirector
extends MetroIIDEDirectorForPtides

MetroIIPtidesDirector adapts Ptides programming model to MetroII semantics. Instead of firing actors sequentially, MetroIIPtides simultaneously fires actors by calling startOrResume(MetroII event list) (@see StartOrResumable). This implies that each firing is a process that executes and blocks to propose MetroII events. The proposed events from actors will be passed to upper level directors and ultimately passed to MetroIIDirector (@see MetroIIDirector), where the states of the MetroII events are updated based on constraint resolution and architectural models. In other words, the order of firing may be affected by the architectural model. But causality should not be violated because the actors ready to fire simultaneously are obtained by causality analysis, see isCausallyAffected(Collection, PtidesEvent).

Most methods are identical to PtidesDirector except directors are mapped to MetroIIPtidesdirector instead of PtidesDirector.

Since:

Ptolemy II 11.0

Version:

$Id$

Author:

Patricia Derler, Edward A. Lee, Slobodan Matic, Mike Zimmer, Jia Zou, Liangpeng Guo

Pt.AcceptedRating:

Red (derler)

Pt.ProposedRating:

Red (derler)

Nested Class Summary

Nested classes/interfaces inherited from class ptolemy.domains.metroII.kernel.MetroIIDEDirectorForPtides

MetroIIDEDirectorForPtides.Pair<F,S>

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

NamedObj.ContainedObjectsIterator

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.Map<TypedIOPort,java.util.Set<TypedIOPort>>	_inputPortGroups Map an input port to a set which is its input port group.
protected java.util.List<TypedIOPort>	_inputPorts List of all input ports in the model (actuator and network transmitter ports are also considered input ports).
protected Time	_nextFireTime The earliest time this director should be refired.
protected java.util.Map<IOPort,java.util.Map<IOPort,SuperdenseDependency>>	_superdenseDependencyPair Store the superdense dependency between pairs of input ports using nested Maps.
SharedParameter	clockSynchronizationErrorBound Bounds on clock synchronization error across all platforms.

Fields inherited from class ptolemy.domains.metroII.kernel.MetroIIDEDirectorForPtides

_actorDictionary, _eventList, printTrace

Fields inherited from class ptolemy.domains.de.kernel.DEDirector

_actorsFinished, _actorsInExecution, _disabledActors, _eventQueue, _eventQueueLock, _isInitializing, _microstep, _noMoreActorsToFire, _stopFireRequested, binCountFactor, enforceMicrostepSemantics, isCQAdaptive, minBinCount, stopWhenQueueIsEmpty, synchronizeToRealTime

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 and Description
MetroIIPtidesDirector(CompositeEntity container, java.lang.String name) Construct a director in the given container with the given name.

Method Summary

Modifier and Type	Method and Description
protected boolean	_checkForNextEvent() Model time is only used for correct execution of actors and the scheduler will determine whether another event can be fired in the current firing of the platform, so this method isn't needed.
protected void	_enqueueTriggerEvent(IOPort ioPort, Token token, Receiver receiver) Put a trigger event into the event queue.
protected double	_getDeadline(Actor actor, Time timestamp) Compute the deadline for an actor that requests a firing at time timestamp.
protected static java.lang.Double	_getDoubleParameterValue(NamedObj object, java.lang.String parameterName) Return the value stored in a parameter associated with the NamedObj.
protected static java.lang.Integer	_getIntParameterValue(NamedObj object, java.lang.String parameterName) Return the value stored in a parameter associated with the NamedObj.
protected Actor	_getNextActorToFire() Return the actor to fire in this iteration, or null if no actor should be fired.
protected PtidesEvent	_getNextEventToFire() Returns the actor to fire in this iteration, or null if no actor should be fired.
protected void	_resetLogicalTime() Reset logical time to null.
protected void	_setLogicalTime(PtidesEvent ptidesEvent) Set logical time to that of the ptidesEvent.
void	addInputEvent(MetroIIPtidesPort sourcePort, PtidesEvent event, double deviceDelay) Add a new event to the input queue.
void	attributeChanged(Attribute attribute) Update the director parameters when attributes are changed.
boolean	causallyAffect(PtidesEvent e1, PtidesEvent e2) Calculate whether Ptides event e1 could possibly affect Ptides event e2.
java.lang.Object	clone(Workspace workspace) Clone the object into the specified workspace.
Dependency	defaultDependency() Return the default dependency between input and output ports, which for the Ptides domain is a SuperdenseDependency.
void	fire() Before super.fire() is called, transfer all input events that are ready are transferred.
Time	fireAt(Actor actor, Time time, int index) Add a pure event to the queue of pure events.
Time	getCurrentSourceTimestamp() Return the source timestamp of the event that is currently being processed.
void	getfire(ResultHandler<java.lang.Iterable<metroIIcomm.Event.Builder>> resultHandler) Before super.getfire() is called, transfer all input events that are ready are transferred.
int	getIndex() Return a superdense time index for the current time, where the index is equal to the microstep.
int	getMicrostep() Return the current microstep or the microstep of the event, if an actor is currently executing.
Time	getModelTime() Return the local time or, (i) if an actor is executing or (ii) an input token is read, (i) the timestamp of the event that caused the actor execution or (ii) the timestamp of the input event.
void	initialize() Initialize all the actors and variables.
boolean	isCausallyAffected(java.util.Collection<PtidesEvent> eventArray, PtidesEvent event) Calculate whether any Ptides event in eventArray could causally affect event.
boolean	isFiringEventCausallyAffect(PtidesEvent event) Calculate whether any Ptides event currently being processed could causally affect event.
boolean	isPendingEventCausallyAffect(PtidesEvent event) Calculates whether any Ptides event pending could causally affect event.
double	minDelayBetween(java.util.Collection<IOPort> ports1, java.util.Collection<IOPort> ports2) Calculate the minimal delay in logical time between two ports.
Receiver	newReceiver() Return a new receiver.
boolean	postfire() Return false if there are no more actors to be fired or the stop() method has been called.
boolean	prefire() Override the base class to not set model time to that of the enclosing director.
void	preinitialize() Calls the preinitialize of the super class and create new event Queue.

Methods inherited from class ptolemy.domains.metroII.kernel.MetroIIDEDirectorForPtides

_checkNextEventToFire, adapter, stop

Methods inherited from class ptolemy.domains.de.kernel.DEDirector

_actorFired, _disableActor, _enqueueEvent, _enqueueTriggerEvent, _fire, _getDepthOfActor, _getDepthOfIOPort, _issueExecutionAspectWarning, _noActorToFire, _requestFiring, _schedule, addDebugListener, cancelFireAt, cancelFireAt, describePriorities, fireAt, fireAtCurrentTime, fireAtRelativeTime, getCausalityInterface, getModelNextIterationTime, getNextEventTime, getStartTime, getStopTime, invalidateSchedule, mutexLockObject, removeDebugListener, resumeActor, setIndex, stopFire, suggestedModalModelDirectors, transferInputs, wrapup

Methods inherited from class ptolemy.actor.Director

_actorFinished, _consultTimeRegulators, _description, _isEmbedded, _isTopLevel, _transferInputs, _transferOutputs, addInitializable, createSchedule, delayDependency, elapsedTimeSinceStart, finish, fireAt, fireContainerAt, fireContainerAt, getCurrentTime, getDeadline, getEnvironmentTime, getExecutionAspect, getGlobalTime, getModelStartTime, getModelStopTime, getNextIterationTime, getTimeResolution, implementsStrictActorSemantics, initialize, invalidateResolvedTypes, isEmbedded, isFireFunctional, isStopRequested, isStrict, iterate, notifyTokenSentToCommunicationAspect, preinitialize, removeInitializable, requestInitialization, resume, scheduleContainedActors, setContainer, setCurrentTime, setEmbedded, setModelTime, setTimeResolution, supportMultirateFiring, suspend, terminate, transferOutputs, transferOutputs

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

Field Detail

clockSynchronizationErrorBound

public SharedParameter clockSynchronizationErrorBound

Bounds on clock synchronization error across all platforms. FIXME: eventually set parameter per platform or for some platforms.

_inputPorts

protected java.util.List<TypedIOPort> _inputPorts

List of all input ports in the model (actuator and network transmitter ports are also considered input ports).

_inputPortGroups

protected java.util.Map<TypedIOPort,java.util.Set<TypedIOPort>> _inputPortGroups

Map an input port to a set which is its input port group.

_nextFireTime

protected Time _nextFireTime

The earliest time this director should be refired.

_superdenseDependencyPair

protected java.util.Map<IOPort,java.util.Map<IOPort,SuperdenseDependency>> _superdenseDependencyPair

Store the superdense dependency between pairs of input ports using nested Maps. Providing the source input as a key will return a Map value, where the destination input port can be used as a key to return the superdense dependency.

Constructor Detail

MetroIIPtidesDirector

public MetroIIPtidesDirector(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 - The container of the director.

name - The name of this director.

Throws:

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

NameDuplicationException - If the container not a CompositeActor and the name collides with an entity in the container.

Method Detail

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

Overrides:

clone in class MetroIIDEDirectorForPtides

Parameters:

workspace - The workspace for the cloned object.

Returns:

The new Attribute.

Throws:

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

See Also:

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

addInputEvent

public void addInputEvent(MetroIIPtidesPort sourcePort,
                          PtidesEvent event,
                          double deviceDelay)
                   throws IllegalActionException

Add a new event to the input queue. Compute the time when this input can be consumed and store in queue. The time depends on the device delay.

Parameters:

sourcePort - the source port.

event - New input event.

deviceDelay - The device delay.

Throws:

IllegalActionException - If device delay parameter cannot be computed.

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

Update the director parameters when attributes are changed.

Overrides:

attributeChanged in class DEDirector

Parameters:

attribute - The changed parameter.

Throws:

IllegalActionException - If the parameter set is not valid. Not thrown in this class.

defaultDependency

public Dependency defaultDependency()

Return the default dependency between input and output ports, which for the Ptides domain is a SuperdenseDependency.

Overrides:

defaultDependency in class Director

Returns:

The default dependency that describes a time delay of 0.0, and a index delay of 0 between ports.

See Also:

Dependency, CausalityInterface, Actor.getCausalityInterface()

fire

public void fire()
          throws IllegalActionException

Before super.fire() is called, transfer all input events that are ready are transferred. After super.fire() is called, transfer all output events that are ready are transferred.

Specified by:

fire in interface Executable

Overrides:

fire in class DEDirector

Throws:

IllegalActionException - If we couldn't process an event or if an event of smaller timestamp is found within the event queue.

See Also:

DEDirector._fire()

fireAt

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

Add a pure event to the queue of pure events.

Overrides:

fireAt in class DEDirector

Parameters:

actor - Actor to fire.

time - Time the actor should be fired at.

index - Microstep the actor should be fired at.

Returns:

The time the actor requested to be refired at.

Throws:

IllegalActionException - If firing of the container doesn't succeed.

See Also:

DEDirector.fireAtCurrentTime(Actor)

getCurrentSourceTimestamp

public Time getCurrentSourceTimestamp()

Return the source timestamp of the event that is currently being processed. If no event is being processed, (i.e. event is analyzed for safe to process, actor is fired, ...) this method can return null or the timestamp of the previous event. This method should not be called if no event is currently being processed.

Returns:

The current source timestamp.

getIndex

public int getIndex()

Return a superdense time index for the current time, where the index is equal to the microstep.

Specified by:

getIndex in interface SuperdenseTimeDirector

Overrides:

getIndex in class DEDirector

Returns:

A superdense time index.

See Also:

DEDirector.setIndex(int), SuperdenseTimeDirector

getModelTime

public Time getModelTime()

Return the local time or, (i) if an actor is executing or (ii) an input token is read, (i) the timestamp of the event that caused the actor execution or (ii) the timestamp of the input event.

Overrides:

getModelTime in class Director

Returns:

The local time or the semantic

See Also:

Director.setModelTime(Time)

getMicrostep

public int getMicrostep()

Return the current microstep or the microstep of the event, if an actor is currently executing.

Overrides:

getMicrostep in class DEDirector

Returns:

microstep of the current time.

See Also:

DEDirector.getIndex(), DEDirector.setIndex(int), SuperdenseTimeDirector

minDelayBetween

public double minDelayBetween(java.util.Collection<IOPort> ports1,
                              java.util.Collection<IOPort> ports2)

Calculate the minimal delay in logical time between two ports.

Parameters:

ports1 - The source port.

ports2 - The sink port.

Returns:

The minimal delay between the two ports.

causallyAffect

public boolean causallyAffect(PtidesEvent e1,
                              PtidesEvent e2)
                       throws IllegalActionException

Calculate whether Ptides event e1 could possibly affect Ptides event e2.

Parameters:

e1 - The first Ptides event.

e2 - The second Ptides event.

Returns:

True if e1 could causally affect e2; false otherwise.

Throws:

IllegalActionException - Thrown if causality interface cannot be computed.

isCausallyAffected

public boolean isCausallyAffected(java.util.Collection<PtidesEvent> eventArray,
                                  PtidesEvent event)
                           throws IllegalActionException

Calculate whether any Ptides event in eventArray could causally affect event.

Parameters:

eventArray - A collection of Ptides event

event - An event

Returns:

True if any event in eventArray could causally affect event; false otherwise.

Throws:

IllegalActionException - If the causality interface cannot be computed.

isFiringEventCausallyAffect

public boolean isFiringEventCausallyAffect(PtidesEvent event)
                                    throws IllegalActionException

Calculate whether any Ptides event currently being processed could causally affect event.

Parameters:

event - An event

Returns:

True if any event currently being processed could causally affect event; false otherwise.

Throws:

IllegalActionException - If the causality interface cannot be computed.

isPendingEventCausallyAffect

public boolean isPendingEventCausallyAffect(PtidesEvent event)
                                     throws IllegalActionException

Calculates whether any Ptides event pending could causally affect event.

Parameters:

event - A Ptides event

Returns:

True if any pending Ptides event could causally affect event; false otherwise.

Throws:

IllegalActionException - Thrown if causality interface cannot be computed.

getfire

public void getfire(ResultHandler<java.lang.Iterable<metroIIcomm.Event.Builder>> resultHandler)
             throws CollectionAbortedException,
                    IllegalActionException

Before super.getfire() is called, transfer all input events that are ready are transferred. After super.getfire() is called, transfer all output events that are ready are transferred.

Specified by:

getfire in interface GetFirable

Overrides:

getfire in class MetroIIDEDirectorForPtides

Parameters:

resultHandler - iterable of events 'yield returned'.

Throws:

IllegalActionException - If any called method of one of the associated actors throws it.

CollectionAbortedException - If any called method of one of the associated actors throws it.

initialize

public void initialize()
                throws IllegalActionException

Initialize all the actors and variables. Perform static analysis on superdense dependencies between input ports in the topology.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class MetroIIDEDirectorForPtides

Throws:

IllegalActionException - If thrown while calculating the superdense dependencies, delay offset or relative deadlines.

newReceiver

public Receiver newReceiver()

Return a new receiver. In this class, the receiver is of type MetroIIPtidesReceiver.

Overrides:

newReceiver in class DEDirector

Returns:

A new PtidesReceiver.

postfire

public boolean postfire()
                 throws IllegalActionException

Return false if there are no more actors to be fired or the stop() method has been called.

Specified by:

postfire in interface Executable

Overrides:

postfire in class DEDirector

Returns:

True If this director will be fired again.

Throws:

IllegalActionException - If the stopWhenQueueIsEmpty parameter does not contain a valid token, or refiring can not be requested.

prefire

public boolean prefire()
                throws IllegalActionException

Override the base class to not set model time to that of the enclosing director. This method always returns true, deferring the decision about whether to fire an actor to the fire() method.

Specified by:

prefire in interface Executable

Overrides:

prefire in class DEDirector

Returns:

True.

Throws:

IllegalActionException - If thrown while getting the local time.

preinitialize

public void preinitialize()
                   throws IllegalActionException

Calls the preinitialize of the super class and create new event Queue.

Specified by:

preinitialize in interface Initializable

Overrides:

preinitialize in class DEDirector

Throws:

IllegalActionException - If the preinitialize() method of the container or one of the deeply contained actors throws it, or the parameters, minBinCount, binCountFactor, and isCQAdaptive, do not have valid tokens.

_checkForNextEvent

protected boolean _checkForNextEvent()

Model time is only used for correct execution of actors and the scheduler will determine whether another event can be fired in the current firing of the platform, so this method isn't needed. By always returning true, _getNextActorToFire() will be called which runs the scheduler.

Overrides:

_checkForNextEvent in class DEDirector

Returns:

true Always.

_enqueueTriggerEvent

protected void _enqueueTriggerEvent(IOPort ioPort,
                                    Token token,
                                    Receiver receiver)
                             throws IllegalActionException

Put a trigger event into the event queue.

The trigger event has the same timestamp as that of the director. The microstep of this event is always equal to the current microstep of this director. The depth for the queued event is the depth of the destination IO port. Finally, the token and the destination receiver are also stored in the event.

If the event queue is not ready or the actor that contains the destination port is disabled, do nothing.

Parameters:

ioPort - The destination IO port.

token - The token associated with this event.

receiver - The destination receiver.

Throws:

IllegalActionException - If the time argument is not the current time, or the depth of the given IO port has not be calculated, or the new event can not be enqueued.

_getDeadline

protected double _getDeadline(Actor actor,
                              Time timestamp)
                       throws IllegalActionException

Compute the deadline for an actor that requests a firing at time timestamp.

Parameters:

actor - The actor that requests firing.

timestamp - The time when the actor wants to be fired.

Returns:

The deadline for the actor.

Throws:

IllegalActionException - If time objects cannot be created.

_getDoubleParameterValue

protected static java.lang.Double _getDoubleParameterValue(NamedObj object,
                                                           java.lang.String parameterName)
                                                    throws IllegalActionException

Return the value stored in a parameter associated with the NamedObj.

Parameters:

object - The object that has the parameter.

parameterName - The name of the parameter to be retrieved.

Returns:

the value of the named parameter if the parameter is not null. Otherwise return null.

Throws:

IllegalActionException - If thrown while getting the value of the parameter.

_getIntParameterValue

protected static java.lang.Integer _getIntParameterValue(NamedObj object,
                                                         java.lang.String parameterName)
                                                  throws IllegalActionException

Return the value stored in a parameter associated with the NamedObj.

Parameters:

object - The object that has the parameter.

parameterName - The name of the parameter to be retrieved.

Returns:

the value of the named parameter if the parameter is not null. Otherwise return null.

Throws:

IllegalActionException - If thrown while getting the value of the parameter.

_getNextEventToFire

protected PtidesEvent _getNextEventToFire()
                                   throws IllegalActionException

Returns the actor to fire in this iteration, or null if no actor should be fired. Since _checkForNextEvent() always returns true, this method will keep being called until it returns null.

Specified by:

_getNextEventToFire in class MetroIIDEDirectorForPtides

Returns:

Ptides event that is safe to process

Throws:

IllegalActionException - If thrown while getting the next event from either the pure Events or the eventQueue.

_getNextActorToFire

protected Actor _getNextActorToFire()
                             throws IllegalActionException

Return the actor to fire in this iteration, or null if no actor should be fired. Since _checkForNextEvent() always returns true, this method will keep being called until it returns null.

Overrides:

_getNextActorToFire in class DEDirector

Returns:

The next actor to be fired, which can be null.

Throws:

IllegalActionException - If thrown while getting the next event to fire.

_setLogicalTime

protected void _setLogicalTime(PtidesEvent ptidesEvent)

Set logical time to that of the ptidesEvent.

Specified by:

_setLogicalTime in class MetroIIDEDirectorForPtides

Parameters:

ptidesEvent - Ptides event the logical time is set to.

_resetLogicalTime

protected void _resetLogicalTime()

Reset logical time to null.

Specified by:

_resetLogicalTime in class MetroIIDEDirectorForPtides