ptolemy.domains.metroII.kernel

Class MetroIIDirector

java.lang.Object

ptolemy.kernel.util.NamedObj

ptolemy.kernel.util.Attribute

ptolemy.actor.Director

ptolemy.domains.metroII.kernel.MetroIIDirector

All Implemented Interfaces:

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

public class MetroIIDirector
extends Director

A MetroII Director governs the execution of actors with simplified MetroII execution semantics. The major distinction from other directors is the way MetroIIDirector fires the actors. In stead of explicitly calling fire() of the governing actors, MetroIIDirector implicitly fires actors by exchanging MetroII events with actors (@see ptolemy.domains.metroII.kernel.util.ProtoBuf.Event). Under MetroIIDirector, each actor is wrapped by either BlockingFire (@see BlockingFire) or ResumableFire (@see ResumableFire). With a wrapper, the firing of an actor is a process which executes and then blocks to generate MetroII events. Each MetroII event has one of the following states: PROPOSED, WAITING, and NOTIFIED. When the firing of an actor blocks to generate MetroII events, the events are sent to MetroIIDirector with the state of PROPOSED. This is also referred to as proposing MetroII events. MetroIIDirector delegates the events to constraint solvers (@see ConstraintSolver) which update the event states to either WAITING or NOTIFIED. If any event state of a process is updated to NOTIFIED, the process is supposed to resume execution. The resumed execution may depend on the updated events.

The execution of MetroIIDirector has two phases. In Phase 1, MetroIIDirector repeatedly fires each actor (no particular order should be presumed). As mentioned, each firing is a process runs and then blocks to propose MetroII events. Phase 1 ends when all processes of firing are blocked. In Phase 2, MetroIIDirector delegates all the proposed events to constraint solvers (@see ConstraintSolver), which updates the states of MetroII events based on the constraints. In particular, MappingConstraintSolver (MappingConstraintSolver) is a constraint solver that resolves rendezvous constraints. A rendezvous constraint requires the specified pair of MetroII events must be proposed together, otherwise the states will be updated to WAITING. A collection of two completed phases is referred to as an iteration. After constraint resolving in Phase 2, MetroIIDirector goes back to Phase 1, in which each existing process has a chance to react to the updated MetroII events. The process with at least one NOTIFIED event is supposed to resume execution while the process with all events WAITING keeps blocked. If the process of firing successfully completes in last iteration, a new process will be created as long as prefire() returns true. The actor with postfire() returns false will not be fired any more.

An actor that implements GetFirable interface (@see GetFirable) is wrapped by ResumableFire (@see ResumableFire). Otherwise it's wrapped by BlockingFire (@see BlockingFire). Particularly, the MetroIIComposite, MetroIIModalModel, MetroIIPtidesPlatform have GetFirable interface implemented and are thus wrapped by ResumableFire. And all other ordinary Ptolemy actors are wrapped by BlockingFire. If an actor is wrapped by BlockingFire, the firing of an actor has two MetroII events associated: FIRE_BEGIN and FIRE_END. FIRE_BEGIN is first proposed and the firing blocks. When FIRE_BEGIN is NOTIFIED, fire() is called and FIRE_END is proposed. When FIRE_END is NOTIFIED, the firing successfully completes. The firing is atomic and there is no chance to propose events during firing. If an actor is wrapped by ResumableFire, in addition to FIRE_BEGIN and FIRE_END, getfire(MetroII event list) is called instead of fire(). The process of firing may not only block on FIRE_BEGIN and FIRE_END, but also block on the internal events of getfire(MetroII event list).

In ResumableFire, the 'start', 'block', and 'resume' are realized using YieldAdapter, see http://jimblackler .net/blog/?p=61. The underlying mechanism is to create, suspend, and resume a java thread. And proposed MetroII events are returned by the parameters of startOrResume().

Since:

Ptolemy II 11.0

Version:

$Id$

Author:

Liangpeng Guo

Pt.AcceptedRating:

Red (glp)

Pt.ProposedRating:

Red (glp)

Nested Class Summary

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

NamedObj.ContainedObjectsIterator

Field Summary

Fields

Modifier and Type	Field and Description
protected int	_iterationCount The iteration count.
Parameter	iterations A Parameter representing the number of times that postfire may be called before it returns false.
FileParameter	mappingFileName A mapping constraint is a pair of events that are rendezvous.
Parameter	printDebug Option parameter whether debug info is printed out.
Parameter	printTrace Option parameter whether trace info is printed out.

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

Method Summary

Modifier and Type	Method and Description
void	attributeChanged(Attribute attribute) Reacts to a change in an attribute.
java.lang.Object	clone(Workspace workspace) Clones the object into the specified workspace.
void	fire() Each iteration has two phases.
void	initialize() Initializes the model controlled by this director.
boolean	postfire() The postfire() counts the number of iterations and returns false when the number of iteration exceeds the parameter iterations or the time in TimeScheduler exceeds stopTime, whichever comes first.
void	stop() Stops firing as soon as possible.
void	stopFire() Calls stopFire() of the superclass and show a message.
void	wrapup() Resets all the StartOrResumable wrapped actors before calling the wrapup() of Director.

Methods inherited from class ptolemy.actor.Director

_actorFinished, _consultTimeRegulators, _description, _isEmbedded, _isTopLevel, _schedule, _transferInputs, _transferOutputs, addInitializable, createSchedule, defaultDependency, delayDependency, elapsedTimeSinceStart, finish, fireAt, fireAt, fireAt, fireAtCurrentTime, fireContainerAt, fireContainerAt, getCausalityInterface, getCurrentTime, getDeadline, getEnvironmentTime, getExecutionAspect, getGlobalTime, getModelNextIterationTime, getModelStartTime, getModelStopTime, getModelTime, getNextIterationTime, getStartTime, getStopTime, getTimeResolution, implementsStrictActorSemantics, initialize, invalidateResolvedTypes, invalidateSchedule, isEmbedded, isFireFunctional, isStopRequested, isStrict, iterate, mutexLockObject, newReceiver, notifyTokenSentToCommunicationAspect, prefire, preinitialize, preinitialize, removeInitializable, requestInitialization, resume, resumeActor, scheduleContainedActors, setContainer, setCurrentTime, setEmbedded, setModelTime, setTimeResolution, suggestedModalModelDirectors, supportMultirateFiring, suspend, terminate, transferInputs, 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, 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

mappingFileName

public FileParameter mappingFileName

A mapping constraint is a pair of events that are rendezvous. Mapping file is a text file that specifies such constraints. In mapping file, each line is a mapping constraint, which contains two event names separated by a space.

_mappingFileName is a string that contains the absolute path of the mapping file.

The default value of _mappingFileName is null, which means no mapping constraint is specified.

iterations

public Parameter iterations

A Parameter representing 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.

printTrace

public Parameter printTrace

Option parameter whether trace info is printed out.

printDebug

public Parameter printDebug

Option parameter whether debug info is printed out.

_iterationCount

protected int _iterationCount

The iteration count.

Constructor Detail

MetroIIDirector

public MetroIIDirector(CompositeEntity container,
                       java.lang.String name)
                throws NameDuplicationException,
                       IllegalActionException

Constructs 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. May be thrown in a derived class.

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

Method Detail

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

Reacts to a change in an attribute. If the changed attribute matches a parameter of the director, then the corresponding local copy of the parameter value will be updated.

Overrides:

attributeChanged in class Director

Parameters:

attribute - The changed parameter.

Throws:

IllegalActionException - If the parameter set is not valid.

initialize

public void initialize()
                throws IllegalActionException

Initializes the model controlled by this director. Call the initialize() of super class and then wrap each actor that is controlled by this director. This method should typically be invoked once per execution, after the preinitialization phase, but before any iteration. It may be invoked in the middle of an execution, if reinitialization is desired. This method is not synchronized on the workspace, so the caller should be.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class Director

Throws:

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

fire

public void fire()
          throws IllegalActionException

Each iteration has two phases. In Phase 1, MetroIIDirector calls each actor (no particular order should be presumed. See Note 1). Each actor runs until it wants to propose MetroII events: the actor saves the state and returns with MetroII events. In Phase 2, MetroIIDirector calls the MappingConstraintSolver, which updates the MetroII events based on the mapping constraints.

Specified by:

fire in interface Executable

Overrides:

fire in class Director

Throws:

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

clone

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

Clones 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 Director

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)

postfire

public boolean postfire()
                 throws IllegalActionException

The postfire() counts the number of iterations and returns false when the number of iteration exceeds the parameter iterations or the time in TimeScheduler exceeds stopTime, whichever comes first. postfire() will always return true if the parameter iterations is less or equal to 0.

Specified by:

postfire in interface Executable

Overrides:

postfire in class Director

Returns:

True to continue execution, and false otherwise.

Throws:

IllegalActionException - Not thrown in this base class.

stop

public void stop()

Stops firing as soon as possible.

Specified by:

stop in interface Executable

Overrides:

stop in class Director

stopFire

public void stopFire()

Calls stopFire() of the superclass and show a message.

Specified by:

stopFire in interface Executable

Overrides:

stopFire in class Director

wrapup

public void wrapup()
            throws IllegalActionException

Resets all the StartOrResumable wrapped actors before calling the wrapup() of Director.

Specified by:

wrapup in interface Initializable

Overrides:

wrapup in class Director

Throws:

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