ptolemy.domains.fsm.kernel
Class FSMDirector

java.lang.Object
  extended byptolemy.kernel.util.NamedObj
      extended byptolemy.kernel.util.Attribute
          extended byptolemy.actor.Director
              extended byptolemy.domains.fsm.kernel.FSMDirector
All Implemented Interfaces:
Changeable, java.lang.Cloneable, Debuggable, DebugListener, Derivable, Executable, ExplicitChangeContext, ModelErrorHandler, MoMLExportable, Nameable, java.io.Serializable
Direct Known Subclasses:
HSDirector

public class FSMDirector
extends Director
implements ModelErrorHandler, ExplicitChangeContext

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 a TypedActor 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, an exception is thrown. If there is exactly one preemptive transition enabled then it is chosen and the choice actions contained by the transition are executed. The refinement of the current state is not fired. Any output token produced by the mode controller is transferred to the outside domain. If no preemptive transition is enabled, the refinement of the current state is fired. The non-preemptive transitions from the current state of the mode controller are examined. If there is more than one transition enabled, 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 or the refinement is transferred to the outside domain.

The mode controller does not change state during successive firings in one iteration in order to support outside 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,v 1.88 2004/04/13 05:12:55 cxh Exp $
Author:
Xiaojun Liu
See Also:
FSMActor, Serialized Form
Accepted Rating:
Yellow (liuxj)
Proposed Rating:
Yellow (liuxj)

Nested Class Summary
 
Nested classes inherited from class ptolemy.kernel.util.NamedObj
NamedObj.ContainedObjectsIterator
 
Field Summary
protected  java.util.Map _currentLocalReceiverMap
           
protected  java.util.List _enabledRefinements
           
protected  boolean _fireRefinement
           
protected  boolean _firstFire
           
protected  java.util.Map _localReceiverMaps
           
 StringAttribute controllerName
          Attribute specifying the name of the mode controller in the container of this director.
 
Fields inherited from class ptolemy.actor.Director
_currentTime, _stopRequested
 
Fields inherited from class ptolemy.kernel.util.NamedObj
_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _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()
           
protected  Transition _chooseTransition(java.util.List transitionList)
          Return the enabled transition among the given list of transitions.
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.
 void fire()
          Set the values of input variables in the mode controller.
 void fireAt(Actor actor, double time)
          Schedule a firing of the given actor at the given time.
 Entity getContext()
          Return the change context being made explicit.
 FSMActor getController()
          Return the mode controller of this director.
 java.util.List getModifiedVariables()
          Return a list of variables that are modified in a modal model.
 double getNextIterationTime()
          Return the next iteration time provided by the refinement of the current state of the mode controller.
 boolean handleModelError(NamedObj context, IllegalActionException exception)
          Handle a model error by checking if there is any enabled non-preemptive transitions.
 void initialize()
          Initialize the mode controller and all the refinements.
 Receiver newReceiver()
          Return a receiver that is a one-place buffer.
 boolean postfire()
          Return true if the mode controller wishes to be scheduled for another iteration.
 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 setCurrentTime(double newTime)
          Set the current time of the model under this director.
 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, _isEmbedded, _isTopLevel, _writeAccessRequired, domainPolymorphicTransferInputs, domainPolymorphicTransferOutputs, fireAtCurrentTime, getCurrentTime, getTimeResolution, initialize, invalidateResolvedTypes, invalidateSchedule, iterate, needWriteAccess, preinitialize, requestInitialization, setTimeResolution, stop, stopFire, terminate, transferOutputs, wrapup
 
Methods inherited from class ptolemy.kernel.util.Attribute
_getContainedObject, _propagateExistence, getContainer, setName
 
Methods inherited from class ptolemy.kernel.util.NamedObj
_addAttribute, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoML, getAttribute, getAttribute, getAttributes, getChangeListeners, getClassName, getDerivedLevel, getDerivedList, getElementName, getFullName, getModelErrorHandler, getName, getName, getPrototypeList, getSource, isDeferringChangeRequests, isOverridden, isPersistent, message, propagateExistence, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setModelErrorHandler, setPersistent, setSource, 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, 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

_enabledRefinements

protected java.util.List _enabledRefinements

_firstFire

protected boolean _firstFire

_fireRefinement

protected boolean _fireRefinement

_localReceiverMaps

protected java.util.Map _localReceiverMaps
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, record the change but do not check whether there is an FSMActor with the specified name in the container of this director.

Overrides:
attributeChanged in class NamedObj
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.

fire

public void fire()
          throws IllegalActionException
Set the values of input variables in the mode controller. Examine the preemptive outgoing transitions of its current state. Throw an exception if there is more than one transition enabled. If there is exactly one preemptive transition enabled then it is chosen and the choice actions contained by the transition are executed. The refinement of the current state of the mode controller is not fired. If no preemptive transition is enabled and the refinement is ready to fire in the current iteration, fire the refinement. The non-preemptive transitions from the current state of the mode controller are examined. If there is more than one transition enabled, 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.

Specified by:
fire in interface Executable
Overrides:
fire in class Director
Throws:
IllegalActionException - If there is more than one transition enabled, or there is no controller, or thrown by any choice action.

fireAt

public void fireAt(Actor actor,
                   double time)
            throws IllegalActionException
Schedule a firing of the given actor at the given time. This is delegated to the executive director by scheduling with it a firing of the container of this director at the given time. The actor should be either the mode controller or the refinement of one of its states. For both cases firing the actor happens when the container of this director is fired at the given time. In the second case, if the actor is not the refinement of the state of the mode controller when the execution reaches the given time, the firing is ignored.

Overrides:
fireAt in class Director
Parameters:
actor - The actor scheduled to be fired.
time - The scheduled time.
Throws:
IllegalActionException - If thrown in scheduling a firing of the container of this director at the given time with the executive director.

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 change context being made explicit. In this case, the change context returned is the composite actor controlled by this director.

Specified by:
getContext in interface ExplicitChangeContext

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 the list of modified variables cannot be returned.

getNextIterationTime

public double getNextIterationTime()
Return the next iteration time provided by the refinement of the current state of the mode controller. If the refinement does not provide this, return that given by the superclass.

Overrides:
getNextIterationTime in class Director
Returns:
The time of the next iteration.

handleModelError

public boolean handleModelError(NamedObj context,
                                IllegalActionException exception)
                         throws IllegalActionException
Handle a model error by checking if there is any enabled non-preemptive transitions. If there is some one, the model error is ignored. Otherwise, the model error (exception) will be passed to higher level in hierarchy.

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, or nothing if the model error is thrown to higher level.
Throws:
IllegalActionException - The model error exception.
See Also:
NamedObj.setModelErrorHandler(ModelErrorHandler handler)

initialize

public void initialize()
                throws IllegalActionException
Initialize the mode controller and all the refinements. Set the current time to 0.0 or the time of the executive director. If the container is not an instance of CompositeActor, do nothing. 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. Since type resolution has been completed and the current time is set, the initialize() method of a contained actor may produce output or schedule events. If stop() is called during this methods execution, then stop initializing actors immediately. This method is not synchronized on the workspace, so the caller should be.

Specified by:
initialize in interface Executable
Overrides:
initialize in class Director
Throws:
IllegalActionException - If the initialize() method of one of the associated actors throws it.

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
Return true if the mode controller wishes to be scheduled for another iteration. Postfire the refinement of the current state of the mode controller if it is ready to fire in the current iteration. 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. If this director is at the top level, it will return the postfire() value of the current refinement.

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 refinement of the current state of the mode controller is ready to fire.

Specified by:
prefire in interface Executable
Overrides:
prefire in class Director
Returns:
True.
Throws:
IllegalActionException - If there is no controller. FIXME: Changed by liuj, not yet reviewed.

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.

setCurrentTime

public void setCurrentTime(double newTime)
                    throws IllegalActionException
Set the current time of the model under this director. It allows the set time to be earlier than the current time. This feature is needed when switching between timed and untimed models.

Overrides:
setCurrentTime in class Director
Parameters:
newTime - The new current simulation time.
Throws:
IllegalActionException - Not thrown in this base class. FIXME: Changed by liuj, not yet reviewed.

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.
See Also:
IOPort.transferInputs()

_buildLocalReceiverMaps

protected void _buildLocalReceiverMaps()
                                throws IllegalActionException
Throws:
IllegalActionException

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

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()
Return the last chosen transition.

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

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

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

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

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