ptolemy.domains.fsm.kernel
Class ModalDirector

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.util.Attribute
          ptolemy.actor.Director
              ptolemy.domains.fsm.kernel.FSMDirector
                  ptolemy.domains.fsm.kernel.ModalDirector

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Executable, Initializable, QuasiTransparentDirector, ExplicitChangeContext, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

Direct Known Subclasses:

TDLModuleDirector

public class ModalDirector
extends FSMDirector

An ModalDirector governs the execution of a modal model. A modal model is a TypedCompositeActor with a ModalDirector as local director. The mode control logic is captured by a mode controller, an instance of FSMActor contained by the composite actor. Each state of the mode controller represents a mode of operation and can be refined by an opaque CompositeActor contained by the same composite actor.

This class differs from its base class in that it strictly follows the actor semantics. It does not invoke the postfire() method of any actors under its control until its own postfire() method is called. Thus, if those actors also follow the actor semantics, then no persistent changes are made in the prefire() or fire() methods.

When a modal model is fired, this director first transfers the input tokens from the outside domain to the mode controller and the refinement of its current state. The preemptive transitions from the current state of the mode controller are examined. If there is more than one transition enabled, and any of the enabled transitions is not marked nondeterministic, an exception is thrown. If there is exactly one preemptive transition enabled then it is chosen. The choice actions (outputActions) contained by the transition are executed. Any output token produced by the mode controller is transferred to both the output ports of the modal model and the input ports of the mode controller. Then the refinements associated with the enabled transition are fired. Any output token produced by the refinements is transferred to both the output ports of the modal model and the input ports of the mode controller. The refinements of the current state will not be fired.

If no preemptive transition is enabled, the refinements of the current state are fired. Any output token produced by the refinements is transferred to both the output ports of the modal model and the input ports of the mode controller. After this, the non-preemptive transitions from the current state of the mode controller are examined. If there is more than one transition enabled, and any of the enabled transitions is not marked nondeterministic, an exception is thrown. If there is exactly one non-preemptive transition enabled then it is chosen and the choice actions contained by the transition are executed. Any output token produced by the mode controller is transferred to the output ports of the modal model and the input ports of the mode controller. Then, the refinements of the enabled transition are executed. Any output token produced by the refinements is transferred to both the output ports of the modal model and the input ports of the mode controller.

At the end of one firing, the modal model transfers its outputs to the outside model. The mode controller does not change state during successive firings in one iteration of the top level in order to support upper level domains that iterate to a fixed point.

When the modal model is postfired, the chosen transition of the latest firing is committed. The commit actions contained by the transition are executed and the current state of the mode controller is set to the destination state of the transition.

Since:

Ptolemy II 5.2

Version:

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

Author:

Edward A. Lee

See Also:

FSMActor, Serialized Form

Accepted Rating:

Red (hyzheng)

Proposed Rating:

Green (eal)

Nested Class Summary

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

NamedObj.ContainedObjectsIterator

Field Summary

protected java.util.Set	_actorsFired Actors that were fired in the current iteration.
private java.util.Set	_disabledActors Actors that have returned false in postfire().

Fields inherited from class ptolemy.domains.fsm.kernel.FSMDirector

_currentLocalReceiverMap, _enabledRefinements, _enabledTransition, _localReceiverMaps, controllerName

Fields inherited from class ptolemy.actor.Director

_actorsFinishedExecution, _currentTime, _finishRequested, _initializables, _stopRequested, timeResolution

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _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

ModalDirector(CompositeEntity container, java.lang.String name)
Construct a director in the given container with the given name.

Method Summary

java.lang.Object	clone(Workspace workspace) Clone the actor into the specified workspace.
void	fire() Fire the modal model.
void	initialize() Initialize this director.
void	invalidateSchedule() Indicate that a schedule for the model may no longer be valid.
boolean	postfire() Return true if the mode controller wishes to be scheduled for another iteration.
boolean	prefire() Override the prefire() method of the super class to clear local variables.

Methods inherited from class ptolemy.domains.fsm.kernel.FSMDirector

_buildLocalReceiverMaps, _checkTransition, _chooseTransition, _currentLocalReceivers, _getLastChosenTransition, _readInputs, _readOutputsFromRefinement, _setCurrentConnectionMap, _setCurrentState, attributeChanged, defaultDependency, fireAt, getContext, getController, getModelNextIterationTime, getModifiedVariables, getParseTreeEvaluator, handleModelError, implementsStrictActorSemantics, isStrict, newReceiver, setContainer, setModelTime, transferInputs

Methods inherited from class ptolemy.actor.Director

_description, _fireContainerAt, _isEmbedded, _isTopLevel, _transferInputs, _transferOutputs, addInitializable, createSchedule, finish, fireAt, fireAtCurrentTime, getCausalityInterface, getCurrentTime, getErrorTolerance, getGlobalTime, getModelStartTime, getModelStopTime, getModelTime, getNextIterationTime, getStartTime, getStopTime, getTimeResolution, initialize, invalidateResolvedTypes, isFireFunctional, isStopRequested, iterate, preinitialize, preinitialize, removeInitializable, requestInitialization, setCurrentTime, stop, stopFire, suggestedModalModelDirectors, supportMultirateFiring, 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, _debug, _debug, _debug, _debug, _debug, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _recordDecoratedAttributes, _removeAttribute, _splitName, _stripNumericSuffix, _validateSettables, addChangeListener, addDebugListener, 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, 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

Methods inherited from interface ptolemy.kernel.util.Nameable

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

Field Detail

_actorsFired

protected java.util.Set _actorsFired

Actors that were fired in the current iteration.

_disabledActors

private java.util.Set _disabledActors

Actors that have returned false in postfire().

Constructor Detail

ModalDirector

public ModalDirector(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 this director.

name - Name of this director.

Throws:

IllegalActionException - If the name has a period in it, or 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 actor into the specified workspace. This calls the base class and then sets the attribute public members to refer to the attributes of the new actor.

Overrides:

clone in class FSMDirector

Parameters:

workspace - The workspace for the new actor.

Returns:

A new FSMActor.

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)

fire

public void fire()
          throws IllegalActionException

Fire the modal model. If there is a preemptive transition enabled, execute its choice actions (outputActions) and fire its refinement. Otherwise, fire the refinement of the current state. After this firing, if there is a transition enabled, execute its choice actions and fire the refinement of the transition. If any tokens are produced during this firing, they are sent to both the output ports of the model model but also the input ports of the mode controller.

Specified by:

fire in interface Executable

Overrides:

fire in class FSMDirector

Throws:

IllegalActionException - If there is more than one transition enabled, or there is no controller, or thrown by any choice action.

postfire

public boolean postfire()
                 throws IllegalActionException

Return true if the mode controller wishes to be scheduled for another iteration. Postfire all the actors that were fired since the last call to initialize() or postfire(). Then execute the commit actions contained by the last chosen transition of the mode controller and set its current state to the destination state of the transition.

Specified by:

postfire in interface Executable

Overrides:

postfire in class FSMDirector

Returns:

True if the mode controller wishes to be scheduled for another iteration.

Throws:

IllegalActionException - If thrown by any commit action or there is no controller.

prefire

public boolean prefire()
                throws IllegalActionException

Override the prefire() method of the super class to clear local variables.

Specified by:

prefire in interface Executable

Overrides:

prefire in class FSMDirector

Returns:

Whatever super.prefire() returns (true if the director is ready to fire.

Throws:

IllegalActionException - If throw by the parent class.

initialize

public void initialize()
                throws IllegalActionException

Initialize this director.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class FSMDirector

Throws:

IllegalActionException - If the superclass throws it.

invalidateSchedule

public void invalidateSchedule()

Indicate that a schedule for the model may no longer be valid. This method simply notifies the executive director.

Overrides:

invalidateSchedule in class Director