ptolemy.domains.fsm.kernel
Class FSMDirector

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

All Implemented Interfaces:

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

Direct Known Subclasses:

HSFSMDirector, HSModalDirector, ModalDirector, MultirateFSMDirector, NonStrictFSMDirector

public class FSMDirector
extends Director
implements ExplicitChangeContext, QuasiTransparentDirector

An FSMDirector governs the execution of a modal model. A modal model is a TypedCompositeActor with a FSMDirector 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.

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

Version:

$Id: FSMDirector.java 59167 2010-09-21 17:08:02Z cxh $

Author:

Xiaojun Liu, Haiyang Zheng

See Also:

FSMActor, Serialized Form

Accepted Rating:

Red (hyzheng)

Proposed Rating:

Yellow (hyzheng)

Nested Class Summary

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

NamedObj.ContainedObjectsIterator

Field Summary

private FSMActor	_controller Cached reference to mode controller.
private long	_controllerVersion Version of cached reference to mode controller.
protected java.util.Map	_currentLocalReceiverMap Map from input ports of the modal model to the local receivers for the current state.
protected java.util.List	_enabledRefinements The list of enabled actors that refines the current state.
protected Transition	_enabledTransition cached enabled transition.
protected java.util.Map	_localReceiverMaps Stores for each state of the mode controller the map from input ports of the modal model to the local receivers when the mode controller is in that state.
private long	_localReceiverMapsVersion
private java.util.List<Actor>	_stateRefinementsToPostfire State refinements to postfire(), as determined by the fire() method.
private java.util.List<Actor>	_transitionRefinementsToPostfire Transition refinements to postfire(), as determined by the fire() method.
StringAttribute	controllerName Attribute specifying the name of the mode controller in the container of this director.

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

FSMDirector()
Construct a director in the default workspace with an empty string as its name.

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

FSMDirector(Workspace workspace)
Construct a director in the workspace with an empty name.

Method Summary

protected void	_buildLocalReceiverMaps() Build for each state of the mode controller the map from input ports of the modal model to the local receivers when the mode controller is in that state.
private void	_checkActorsForReceiver(TypedActor[] actors, Nameable cont, Receiver receiver, java.util.List resultsList)
protected java.util.List	_checkTransition(java.util.List transitionList) Return a list of enabled transitions among the given list of transitions.
protected Transition	_chooseTransition(java.util.List transitionList) Return the enabled transition among the given list of transitions.
private void	_createAttribute() Create the controllerName attribute.
protected Receiver[][]	_currentLocalReceivers(IOPort port) Return the receivers contained by ports connected to the inside of the given input port and on the mode controller or the refinement of its current state.
protected Transition	_getLastChosenTransition() Return the last chosen transition.
protected void	_readInputs() Set the value of the shadow variables for input ports of the controller actor.
protected void	_readOutputsFromRefinement() Set the value of the shadow variables for input ports of the controller actor that are defined by output ports of the refinement.
protected void	_setCurrentConnectionMap() Set the map from input ports to boolean flags indicating whether a channel is connected to an output port of the refinement of the current state.
protected void	_setCurrentState(State state) Set the current state of this actor.
void	attributeChanged(Attribute attribute) React to a change in an attribute.
java.lang.Object	clone(Workspace workspace) Clone the director into the specified workspace.
Dependency	defaultDependency() Return a default dependency to use between input input ports and output ports.
void	fire() Fire the model model for one iteration.
Time	fireAt(Actor actor, Time time) Schedule a firing of the given actor at the given time.
Entity	getContext() Return the explicit change context.
FSMActor	getController() Return the mode controller of this director.
Time	getModelNextIterationTime() Override the base class so that if any outgoing transition has a guard that evaluates to true, then return the current time.
java.util.List	getModifiedVariables() Return a list of variables that are modified in a modal model.
ParseTreeEvaluator	getParseTreeEvaluator() Return the parse tree evaluator used to evaluate guard expressions.
boolean	handleModelError(NamedObj context, IllegalActionException exception) Return true if the model errors are handled.
boolean	implementsStrictActorSemantics() Return true if all state refinements have directors that implement the strict actor semantics and if the enclosing executive director also returns true.
void	initialize() Initialize the mode controller and all the refinements by calling the initialize() method in the super class.
boolean	isStrict() Return false if there is any output of the container does not depend directly on all inputs of the container.
Receiver	newReceiver() Return a receiver that is a one-place buffer.
boolean	postfire() Invoke postfire() on any state refinements that were fired, then execute the commit actions contained by the last chosen transition, if any, then invoke postfire() on any transition refinements that were fired, and finally set the current state to the destination state of the transition.
boolean	prefire() Return true if the mode controller is ready to fire.
void	setContainer(NamedObj container) If the container is not null, register this director as the model error handler.
void	setModelTime(Time newTime) Set a new value to the current time of the model, where the new time can be earlier than the current time.
boolean	transferInputs(IOPort port) Transfer data from the input port of the container to the ports connected to the inside of the input port and on the mode controller or the refinement of its current state.

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

controllerName

public StringAttribute controllerName

Attribute specifying the name of the mode controller in the container of this director. This director must have a mode controller that has the same container as this director, otherwise an IllegalActionException will be thrown when action methods of this director are called.

_currentLocalReceiverMap

protected java.util.Map _currentLocalReceiverMap

Map from input ports of the modal model to the local receivers for the current state.

_enabledRefinements

protected java.util.List _enabledRefinements

The list of enabled actors that refines the current state.

_enabledTransition

protected Transition _enabledTransition

cached enabled transition.

_localReceiverMaps

protected java.util.Map _localReceiverMaps

Stores for each state of the mode controller the map from input ports of the modal model to the local receivers when the mode controller is in that state.

_controller

private FSMActor _controller

Cached reference to mode controller.

_controllerVersion

private long _controllerVersion

Version of cached reference to mode controller.

_localReceiverMapsVersion

private long _localReceiverMapsVersion

_stateRefinementsToPostfire

private java.util.List<Actor> _stateRefinementsToPostfire

State refinements to postfire(), as determined by the fire() method.

_transitionRefinementsToPostfire

private java.util.List<Actor> _transitionRefinementsToPostfire

Transition refinements to postfire(), as determined by the fire() method.

Constructor Detail

FSMDirector

public FSMDirector()

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.

FSMDirector

public FSMDirector(Workspace workspace)

Construct a director in the 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 of this director.

FSMDirector

public FSMDirector(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

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

React to a change in an attribute. If the changed attribute is the controllerName attribute, then make note that this has changed.

Overrides:

attributeChanged in class Director

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - If thrown by the superclass attributeChanged() method.

clone

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

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

Overrides:

clone in class Attribute

Parameters:

workspace - The workspace for the new director.

Returns:

A new director.

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)

defaultDependency

public Dependency defaultDependency()

Return a default dependency to use between input input ports and output ports. This overrides the base class so that if there is an executive director, then we get the default dependency from it.

Overrides:

defaultDependency in class Director

Returns:

A default dependency between input ports and output ports.

See Also:

Dependency, CausalityInterface, Actor.getCausalityInterface()

fire

public void fire()
          throws IllegalActionException

Fire the model model for one iteration. If there is a preemptive transition enabled, execute its choice actions (outputActions). Otherwise, fire the refinement of the current state. After this firing, if there is a transition enabled, execute its choice actions. If any tokens are produced during this iteration, 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 Director

Throws:

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

fireAt

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

Schedule a firing of the given actor at the given time. If there exists an executive director, this method delegates to the fireAt() method of the executive director by requesting a firing of the container of this director at the given time.

If there is no executive director, then the request results in model time of this director being set to the specified time. The reason for this latter behavior is to support models where FSM is at the top level. A director inside the state refinements could be timed, and expects time to advance in its environment between firings. It typically makes a call to fireAt() at the conclusion of each iteration to specify the time value it expects to next see. Such directors can thus be used inside top-level FSM models. For example, the DEDirector and SDFDirector behave exactly this way.

Overrides:

fireAt in class Director

Parameters:

actor - The actor scheduled to be fired.

time - The scheduled time.

Returns:

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

Throws:

IllegalActionException - If thrown by the executive director.

See Also:

Director.fireAtCurrentTime(Actor)

getController

public FSMActor getController()
                       throws IllegalActionException

Return the mode controller of this director. The name of the mode controller is specified by the controllerName attribute. The mode controller must have the same container as this director. This method is read-synchronized on the workspace.

Returns:

The mode controller of this director.

Throws:

IllegalActionException - If no controller is found.

getContext

public Entity getContext()

Return the explicit change context. In this case, the change context returned is the composite actor controlled by this director.

Specified by:

getContext in interface ExplicitChangeContext

Returns:

The explicit change context.

getModelNextIterationTime

public Time getModelNextIterationTime()

Override the base class so that if any outgoing transition has a guard that evaluates to true, then return the current time. Otherwise, delegate to the enclosing director.

Overrides:

getModelNextIterationTime in class Director

Returns:

The time of the next iteration.

See Also:

Director.getModelTime()

getModifiedVariables

public java.util.List getModifiedVariables()
                                    throws IllegalActionException

Return a list of variables that are modified in a modal model. The variables are assumed to have a change context of the container of this director. This class returns all variables that are assigned in the actions of transitions.

Specified by:

getModifiedVariables in interface ExplicitChangeContext

Returns:

A list of variables.

Throws:

IllegalActionException - If no controller can be found, or the variables to be assigned by the actions can not be found.

getParseTreeEvaluator

public ParseTreeEvaluator getParseTreeEvaluator()

Return the parse tree evaluator used to evaluate guard expressions. In this base class, an instance of ParseTreeEvaluator is returned. The derived classes may need to override this method to return different parse tree evaluators.

Returns:

ParseTreeEvaluator used to evaluate guard expressions.

handleModelError

public boolean handleModelError(NamedObj context,
                                IllegalActionException exception)
                         throws IllegalActionException

Return true if the model errors are handled. Otherwise, return false and the model errors are passed to the higher level in hierarchy.

In this method, model errors including multipleEnabledTransitionException and InvariantViolationException are handled.

In the current design, if multiple enabled transitions are detected, an exception will be thrown. For future designs, different ways to handle this situation will be introduced here.

When an invariant is violated, this method checks whether there exists an enabled (non-preemptive) transition. If there is one, the model error is ignored and this director will handle the enabled transition later. Otherwise, an exception will be thrown.

Specified by:

handleModelError in interface ModelErrorHandler

Overrides:

handleModelError in class NamedObj

Parameters:

context - The context where the model error happens.

exception - An exception that represents the model error.

Returns:

True if the error has been handled, false if the model error is passed to the higher level.

Throws:

IllegalActionException - If multiple enabled transition is detected, or mode controller can not be found, or can not read outputs from refinements.

See Also:

NamedObj.setModelErrorHandler(ModelErrorHandler handler)

implementsStrictActorSemantics

public boolean implementsStrictActorSemantics()

Return true if all state refinements have directors that implement the strict actor semantics and if the enclosing executive director also returns true.

Overrides:

implementsStrictActorSemantics in class Director

Returns:

True if the director assumes and exports strict actor semantics.

initialize

public void initialize()
                throws IllegalActionException

Initialize the mode controller and all the refinements by calling the initialize() method in the super class. Build the local maps for receivers.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class Director

Throws:

IllegalActionException - If thrown by the initialize() method of the super class, or can not find mode controller, or can not find refinement of the current state.

isStrict

public boolean isStrict()
                 throws IllegalActionException

Return false if there is any output of the container does not depend directly on all inputs of the container.

Specified by:

isStrict in interface Executable

Overrides:

isStrict in class Director

Returns:

False if there is any output that does not depend directly on an input.

Throws:

IllegalActionException - Thrown if causality interface cannot be computed.

newReceiver

public Receiver newReceiver()

Return a receiver that is a one-place buffer. A token put into the receiver will override any token already in the receiver.

Overrides:

newReceiver in class Director

Returns:

A receiver that is a one-place buffer.

postfire

public boolean postfire()
                 throws IllegalActionException

Invoke postfire() on any state refinements that were fired, then execute the commit actions contained by the last chosen transition, if any, then invoke postfire() on any transition refinements that were fired, and finally set the current state to the destination state of the transition. This will return false if any refinement that is postfired returns false.

If any transition was taken in this iteration, and if there is an executive director, then this method calls fireAtCurrentTime(Actor) on that executive director. This requests a refiring in case the there is an enabled transition. If there is, then the current state is transient, and we will want to spend zero time in it.

Specified by:

postfire in interface Executable

Overrides:

postfire in class Director

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

Return true if the mode controller is ready to fire. If this model is not at the top level and the current time of this director lags behind that of the executive director, update the current time to that of the executive director. Record whether the refinements of the current state of the mode controller are ready to fire.

Specified by:

prefire in interface Executable

Overrides:

prefire in class Director

Returns:

True.

Throws:

IllegalActionException - If there is no controller.

setContainer

public void setContainer(NamedObj container)
                  throws IllegalActionException,
                         NameDuplicationException

If the container is not null, register this director as the model error handler.

Overrides:

setContainer in class Director

Parameters:

container - The proposed container.

Throws:

IllegalActionException - If the action would result in a recursive containment structure, or if this entity and container are not in the same workspace, or if the protected method _checkContainer() throws it, or if a contained Settable becomes invalid and the error handler throws it.

NameDuplicationException - If the name of this entity collides with a name already in the container.

See Also:

Attribute.getContainer()

setModelTime

public void setModelTime(Time newTime)
                  throws IllegalActionException

Set a new value to the current time of the model, where the new time can be earlier than the current time. It allows the set time to be earlier than the current time. This feature is needed when switching between timed and untimed models.

Overrides:

setModelTime in class Director

Parameters:

newTime - The new current simulation time.

Throws:

IllegalActionException - Not thrown in this base class.

See Also:

Director.getModelTime()

transferInputs

public boolean transferInputs(IOPort port)
                       throws IllegalActionException

Transfer data from the input port of the container to the ports connected to the inside of the input port and on the mode controller or the refinement of its current state. This method will transfer exactly one token on each input channel that has at least one token available. The port argument must be an opaque input port. If any channel of the input port has no data, then that channel is ignored. Any token left not consumed in the ports to which data are transferred is discarded.

Overrides:

transferInputs in class Director

Parameters:

port - The input 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.

_buildLocalReceiverMaps

protected void _buildLocalReceiverMaps()
                                throws IllegalActionException

Build for each state of the mode controller the map from input ports of the modal model to the local receivers when the mode controller is in that state. This method is read-synchronized on the workspace.

Throws:

IllegalActionException - If there is no mode controller, or can not find refinements for states.

_checkTransition

protected java.util.List _checkTransition(java.util.List transitionList)
                                   throws IllegalActionException

Return a list of enabled transitions among the given list of transitions. This method is called by subclasses of FSMDirector in other packages.

Parameters:

transitionList - A list of transitions.

Returns:

A list of enabled transition.

Throws:

IllegalActionException - If the guard expression of any transition can not be evaluated.

_chooseTransition

protected Transition _chooseTransition(java.util.List transitionList)
                                throws IllegalActionException

Return the enabled transition among the given list of transitions. Throw an exception if there is more than one transition enabled. This method is called by subclasses of FSMDirector in other packages.

Parameters:

transitionList - A list of transitions.

Returns:

An enabled transition, or null if none is enabled.

Throws:

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

_currentLocalReceivers

protected Receiver[][] _currentLocalReceivers(IOPort port)
                                       throws IllegalActionException

Return the receivers contained by ports connected to the inside of the given input port and on the mode controller or the refinement of its current state.

Parameters:

port - An input port of the container of this director.

Returns:

The receivers that currently get inputs from the given port.

Throws:

IllegalActionException - If there is no controller.

_getLastChosenTransition

protected Transition _getLastChosenTransition()
                                       throws IllegalActionException

Return the last chosen transition.

Returns:

The last chosen transition, or null if there has been none.

Throws:

IllegalActionException - If there is no controller.

_readInputs

protected void _readInputs()
                    throws IllegalActionException

Set the value of the shadow variables for input ports of the controller actor.

Throws:

IllegalActionException - If a shadow variable cannot take the token read from its corresponding channel (should not occur).

_readOutputsFromRefinement

protected void _readOutputsFromRefinement()
                                   throws IllegalActionException

Set the value of the shadow variables for input ports of the controller actor that are defined by output ports of the refinement.

Throws:

IllegalActionException - If a shadow variable cannot take the token read from its corresponding channel (should not occur).

_setCurrentConnectionMap

protected void _setCurrentConnectionMap()
                                 throws IllegalActionException

Set the map from input ports to boolean flags indicating whether a channel is connected to an output port of the refinement of the current state. This method is called by HDFFSMDirector.

Throws:

IllegalActionException - If the refinement specified for one of the states is not valid, or if there is no controller.

_setCurrentState

protected void _setCurrentState(State state)
                         throws IllegalActionException

Set the current state of this actor.

Parameters:

state - The state to set.

Throws:

IllegalActionException - If there is no controller.

_checkActorsForReceiver

private void _checkActorsForReceiver(TypedActor[] actors,
                                     Nameable cont,
                                     Receiver receiver,
                                     java.util.List resultsList)

_createAttribute

private void _createAttribute()

Create the controllerName attribute.