ptolemy.domains.modal.kernel
Class FSMActor

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.InstantiableNamedObj
          ptolemy.kernel.Entity
              ptolemy.kernel.ComponentEntity
                  ptolemy.kernel.CompositeEntity
                      ptolemy.domains.modal.kernel.FSMActor

All Implemented Interfaces:

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

Direct Known Subclasses:

FmvAutomaton, FSMMatcher, InterfaceAutomaton, ModalController

public class FSMActor
extends CompositeEntity
implements TypedActor, ExplicitChangeContext

An FSMActor contains a set of states and transitions. A transition has a guard expression, any number of output actions, and any number of set actions. It has an initial state, which is the unique state whose isInitialState parameter is true. In outline, a firing of this actor is a sequence of steps as follows. In the fire() method:

1. Read inputs.
2. Evaluate guards on outgoing transitions of the current state.
3. Choose a transitions whose guard is true.
4. Execute the output actions.

In the postfire() method:

1. Execute the set actions of the chosen transition.
2. Change the current state to the destination of the chosen transition.

The fire() method may be invoked more than once in an iteration, for example in a fixedpoint iteration. This actor makes no persistent state changes in its fire() method, so actor conforms with the actor abstract semantics, and hence can be used in any Ptolemy II domain.

After reading the inputs, this actor examines the outgoing transitions of the current state, evaluating their guard expressions. A transition is enabled if its guard expression evaluates to true. A blank guard expression is interpreted to be always true. The guard expression may refer to any input port and any variable in scope.

If an input port name portName is used in a guard expression, it refers to the current input on that port on channel zero. If the input port status is not known, or if the input is absent, then a guard expression referring to portName will not be evaluated. The guard expression may alternatively refer to portName_isPresent, which is a boolean that is true if an input is present on the specified port. Again, if the input port status is not known, such a guard would not be evaluated. The status of an input port may not be known during firings under a director with fixed-point semantics, such as SR or Continuous.

To refer to a channel specificatlly, a guard expression may use portName_channelIndex, which has value equal to the token received on the port on the given channel. Similarly, it may refer to portName_channelIndex_isPresent.

FIXME: Document multirate behavior.

The identifier portNameArray or portName_channelIndexArray refers the array of all tokens consumed from the port in the last firing. This identifier has an array type whose element type is the type of the corresponding input port.

Nondeterministic transitions are allowed if all enabled transitions are marked nondeterministic. If more than one transition is enabled and they are all marked nondeterministic, then one is chosen at random in the fire() method. If the fire() method is invoked more than once in an iteration, then subsequent invocations in the same iteration will always choose the same transition. However, if more transitions become enabled in subsequent firings and they are not all marked nondeterminate, then an exception will thrown. Note that this means that if some input is unknown on the first invocation of fire(), and a guard refers to that input, then that transition will not be chosen. As a consequence, for nondeterministic state machines, the behavior may depend on the order of firings in a fixed-point iteration. This is in fact unavoidable (it is related to the celebrated Brock-Ackerman anomaly, which demonstrates that the input/output relations of a nondeterministic system do not completely determine its behavior; the context in which it is used can also affect the behavior; specifically, the context may make it impossible to know the value of input on the first invocation of fire() because of a feedback loop).

If no transition is enabled and all their guard expressions have been evaluated (all relevant inputs are known), then if there is a transition marked as a default transition, then that transition is chosen. If there is more than one default transition and they are all marked nondeterministic, then one is chosen at random.

Once a transition is chosen, its output actions are executed. Typically, these will write values to output ports. The form of an output action is typically y = expression, where expression may refer to any variable defined as above or any parameter in scope (and also to outputs of state refinements, see below). This gives the behavior of a Mealy machine, where outputs are produced by transitions rather than by states. Moore machine behavior is also achievable using state refinements that produce outputs (see FSMDirector documentation). Multiple output actions may be given by separating them with semicolons. Also, output actions may take the form of d.p = expression, where d is the name of the destination state and p is a parameter of the destination refinement.

After a transition is taken, this actor calls fireAtCurrentTime() on its enclosing director. This ensures that if the destination state has an enabled transition, that transition will be taken at the same time (in the next superdense time index). It also supports continuous-time models, where the destination state refinement, if any, should produce an output at the next superdense time index.

A final state is a state that has its isFinalState parameter set to true. When the actor reaches a final state, then the postfire method will return false, indicating that the actor does not wish to be fired again.

An FSMActor can be used in a modal model to represent the mode control logic. In this case, the states and transitions have refinements, and this actor works in concert with the FSMDirector to execute those refinements. See the documentation for FSMDirector for details on how that works.

By default, this actor has a conservative causality interface, implemented by the DefaultCausalityInterface, which declares that all outputs depend on all inputs. If, however, the enclosing director and all state refinement directors implement the strict actor semantics (as indicated by their implementsStrictActorSemantics() method), then the returned causality interface is implemented by the FSMCausalityInterface class. If the stateDependentCausality is false (the default), then this causality interface in conservative and valid in all states. If it is true, then the causality interface will show different input/output dependencies depending on the state. See FSMCausalityInterface for details.

Since:

Ptolemy II 8.0

Version:

$Id: FSMActor.java 59155 2010-09-21 13:50:12Z cxh $

Author:

Edward A. Lee, Xiaojun Liu, Haiyang Zheng, Ye Zhou

See Also:

State, Transition, Action, FSMDirector, Serialized Form

Accepted Rating:

Yellow (kienhuis)

Proposed Rating:

Yellow (liuxj)

Nested Class Summary

class

FSMActor.PortScope This class implements a scope, which is used to evaluate the parsed expressions.

Nested classes/interfaces inherited from class ptolemy.kernel.CompositeEntity

CompositeEntity.ContainedObjectsIterator

Field Summary

private java.util.LinkedList	_cachedInputPorts
private java.util.LinkedList	_cachedOutputPorts
private CausalityInterface	_causalityInterface The causality interface, if it has been created, for the case where the causality interface is not state dependent.
private Director	_causalityInterfaceDirector The director for which the causality interface was created.
private java.util.Map<State,FSMCausalityInterface>	_causalityInterfaces The causality interfaces by state, for the case where the causality interface is state dependent.
private java.util.Map<State,java.lang.Long>	_causalityInterfacesVersions The workspace version for causality interfaces by state, for the case where the causality interface is state dependent.
private java.util.Map	_connectionMaps
private long	_connectionMapsVersion
private java.util.Map	_currentConnectionMap
protected State	_currentState Current state.
private boolean	_foundUnknown A flag indicating that unknown inputs were referenced in guards and/or output value expressions (when guards evaluate to true) in the most recently called enabledTransition() or chooseTransition().
private java.util.HashMap<java.lang.String,Port>	_identifierToPort A map that associates each identifier with the unique port that that identifier describes.
private long	_identifierToPortVersion Version number for _identifierToPort.
protected java.util.List<Initializable>	_initializables List of objects whose (pre)initialize() and wrapup() methods should be slaved to these.
(package private) State	_initialState The initial state.
private long	_inputPortsVersion
protected java.util.Map	_inputTokenMap A map from ports to corresponding input variables.
protected Transition	_lastChosenTransition The last chosen transition.
private boolean	_newIteration
private long	_outputPortsVersion
private boolean	_reachedFinalState
private long	_receiversVersion
protected boolean	_stopRequested Indicator that a stop has been requested by a call to stop().
private boolean	_supportMultirate
private java.util.Hashtable	_tokenListArrays
StringAttribute	finalStateNames Attribute specifying the names of the final states of this actor.
StringAttribute	initialStateName Attribute specifying the name of the initial state of this actor.
Parameter	stateDependentCausality Indicate whether input/output dependencies can depend on the state.

Fields inherited from class ptolemy.kernel.CompositeEntity

_levelCrossingLinks

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

FSMActor()
Construct an FSMActor in the default workspace with an empty string as its name.

FSMActor(CompositeEntity container, java.lang.String name)
Create an FSMActor in the specified container with the specified name.

FSMActor(Workspace workspace)
Construct an FSMActor in the specified workspace with an empty string as its name.

Method Summary

protected void	_addEntity(ComponentEntity entity) Add a state to this FSMActor.
protected void	_addRelation(ComponentRelation relation) Add a transition to this FSMActor.
private void	_buildConnectionMaps()
protected void	_commitLastChosenTransition() Execute all set actions contained by the transition chosen during the last call to chooseTransition().
private void	_createReceivers() Create receivers for each input port.
protected int	_getChannelForIdentifier(java.lang.String identifier) Given an identifier, return a channel number i if the identifier is of the form portName_i, portName_i_isPresent, portName_iArray.
protected Port	_getPortForIdentifier(java.lang.String identifier) Get the port for the specified identifier, which may be of form portName, portName_isPresent, portName_i, portName_i_isPresent, etc.
private void	_init()
protected boolean	_isRefinementOutput(IOPort port, int channel) Return true if the channel of the port is connected to an output port of the refinement of current state.
protected void	_readInputs(IOPort port, int channel) Read tokens from the given channel of the given input port and make them accessible to the expressions of guards and transitions through the port scope.
private boolean	_referencedInputPortsByGuardKnown(Transition transition) Given a transition, find any input ports referenced in the guard expressions of the transition, and if any of those input ports has status unknown, return false.
private boolean	_referencedInputPortsByOutputKnown(Transition transition) Given a transition, find any input ports referenced in the output actions of the transitions, and if any of those input ports has status unknown, return false.
private boolean	_referencedInputPortValuesByGuardPresent(Transition transition) Given a transition, return false if the guard includes any reference to an input port value and that input port is known to be absent, or any reference to an input port whose status is unknown.
private void	_removePortVariables(java.lang.String portName, int channel) Remove all variable definitions associated with the specified port name and channel number.
private void	_resetReceivers() Reset receivers for each input port.
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.
private void	_setIdentifierToPort() For each input port of this actor, associate all identifiers with that port.
private void	_setInputTokenMap(Port port, int channel, Token token, Token[] tokenArray) Set the port variables for the specified port as follows: The portName_isPresent variable is set to true if the token argument is non-null, and false otherwise.
void	addInitializable(Initializable initializable) Add the specified object to the list of objects whose preinitialize(), intialize(), and wrapup() methods should be invoked upon invocation of the corresponding methods of this object.
Transition	chooseTransition(java.util.List transitionList) Return an enabled transition among the given list of transitions for which both the guard expression and the output actions can be evaluated (the inputs referred by these are known).
java.lang.Object	clone(Workspace workspace) Clone the actor into the specified workspace.
void	createReceivers() Create receivers for each input port.
State	currentState() Return the current state of this actor.
java.util.List	enabledTransitions(java.util.List transitionList) Return a list of enabled transitions among the given list of transitions.
void	exportSubmodel(java.io.Writer output, int depth, java.lang.String name) Write this FSMActor into the output writer as a submodel.
void	fire() Set the values of input variables.
boolean	foundUnknown() Return true if the most recent call to enabledTransition() or chooseTransition() found guard expressions or output value expressions that could not be evaluated due to unknown inputs.
CausalityInterface	getCausalityInterface() Return a causality interface for this actor.
Entity	getContext() Return the change context being made explicit.
Director	getDirector() Return the director responsible for the execution of this actor.
Director	getExecutiveDirector() Return the executive director (same as getDirector()).
State	getInitialState() Return the initial state of this actor.
Transition	getLastChosenTransition() Get the last chosen transition.
Manager	getManager() Return the Manager responsible for execution of this actor, if there is one.
java.util.List	getModifiedVariables() Return a list of variables that this entity modifies.
ParserScope	getPortScope() Return a scope object that has current values from input ports of this FSMActor in scope.
boolean	hasInput() Test whether new input tokens have been received at the input ports.
boolean	hasInput(Port port) Test whether new input tokens have been received at the given input port.
void	initialize() Initialize this actor by setting the current state to the initial state.
java.util.List	inputPortList() Return a list of the input ports.
boolean	isFireFunctional() Return false.
boolean	isOpaque() Return true.
boolean	isStrict() Return false.
int	iterate(int count) Invoke a specified number of iterations of the actor.
Port	newPort(java.lang.String name) Create a new TypedIOPort with the specified name.
Receiver	newReceiver() Return a new receiver obtained from the director.
ComponentRelation	newRelation(java.lang.String name) Create a new instance of Transition with the specified name in this actor, and return it.
java.util.List	outputPortList() Return a list of the output ports.
boolean	postfire() Execute actions on the last chosen transition.
boolean	prefire() Return true.
void	preinitialize() Create receivers and input variables for the input ports of this actor, and validate attributes of this actor, and attributes of the ports of this actor.
void	readInputs() Set the value of the shadow variables for input ports of this actor.
void	readOutputsFromRefinement() Set the input variables for channels that are connected to an output port of the refinement of current state.
void	removeInitializable(Initializable initializable) Remove the specified object from the list of objects whose preinitialize(), intialize(), and wrapup() methods should be invoked upon invocation of the corresponding methods of this object.
void	reset() Reset current state to the initial state.
void	setLastChosenTransition(Transition transition) Set the last chosen transition.
void	setNewIteration(boolean newIteration) Set the flag indicating whether we are at the start of a new iteration (firing).
void	setSupportMultirate(boolean supportMultirate) Set true indicating that this actor supports multirate firing.
void	stop() Request that execution of the current iteration stop as soon as possible.
void	stopFire() Do nothing.
void	terminate() Call stop().
java.util.Set<Inequality>	typeConstraints() Return the type constraints of this actor.
void	wrapup() Do nothing except invoke the wrapup method of any objects that have been added using addInitializable().

Methods inherited from class ptolemy.kernel.CompositeEntity

_adjustDeferrals, _deepOpaqueEntityList, _description, _exportMoMLContents, _finishedAddEntity, _recordDecoratedAttributes, _removeEntity, _removeRelation, _validateSettables, allAtomicEntityList, allCompositeEntityList, allowLevelCrossingConnect, classDefinitionList, connect, connect, containedObjectsIterator, deepEntityList, deepGetEntities, deepOpaqueEntityList, deepRelationSet, entityList, entityList, exportLinks, exportMoML, getAttribute, getEntities, getEntity, getPort, getRelation, getRelations, isAtomic, lazyAllAtomicEntityList, lazyAllCompositeEntityList, lazyClassDefinitionList, lazyDeepEntityList, lazyEntityList, lazyRelationList, numberOfEntities, numberOfRelations, numEntities, numRelations, relationList, removeAllEntities, removeAllRelations, setClassDefinition, setContainer, statistics, uniqueName

Methods inherited from class ptolemy.kernel.ComponentEntity

_addPort, _checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, propagateExistence, setName

Methods inherited from class ptolemy.kernel.Entity

_removePort, connectedPortList, connectedPorts, connectionsChanged, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts

Methods inherited from class ptolemy.kernel.InstantiableNamedObj

_setParent, getChildren, getElementName, getParent, getPrototypeList, isClassDefinition, isWithinClassDefinition

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeChanged, attributeList, attributeList, attributeTypeChanged, clone, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getFullName, getModelErrorHandler, getName, getName, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, toString, 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

Methods inherited from interface ptolemy.kernel.util.Derivable

getDerivedLevel, getDerivedList, propagateValue

Field Detail

finalStateNames

public StringAttribute finalStateNames

Attribute specifying the names of the final states of this actor. This attribute is kept for backward compatibility only, and is set to expert visibility. To set the final states, set the isFinalState parameter of a States.

initialStateName

public StringAttribute initialStateName

Attribute specifying the name of the initial state of this actor. This attribute is kept for backward compatibility only, and is set to expert visibility. To set the initial state, set the isInitialState parameter of a State.

stateDependentCausality

public Parameter stateDependentCausality

Indicate whether input/output dependencies can depend on the state. By default, this is false (the default), indicating that a conservative dependency is provided by the causality interface. Specifically, if there is a dependency in any state, then the causality interface indicates that there is a dependency. If this is true, then a less conservative dependency is provided, indicating a dependency only if there can be one in the current state. If this is true, then upon any state transition, this actor issues a change request, which forces causality analysis to be redone. Note that this can be expensive.

_currentState

protected State _currentState

Current state.

_initializables

protected transient java.util.List<Initializable> _initializables

List of objects whose (pre)initialize() and wrapup() methods should be slaved to these.

_inputTokenMap

protected java.util.Map _inputTokenMap

A map from ports to corresponding input variables.

_lastChosenTransition

protected Transition _lastChosenTransition

The last chosen transition.

_stopRequested

protected boolean _stopRequested

Indicator that a stop has been requested by a call to stop().

_initialState

State _initialState

The initial state. This is package friendly so that State can access it.

_cachedInputPorts

private transient java.util.LinkedList _cachedInputPorts

_cachedOutputPorts

private transient java.util.LinkedList _cachedOutputPorts

_causalityInterface

private CausalityInterface _causalityInterface

The causality interface, if it has been created, for the case where the causality interface is not state dependent.

_causalityInterfaceDirector

private Director _causalityInterfaceDirector

The director for which the causality interface was created.

_causalityInterfaces

private java.util.Map<State,FSMCausalityInterface> _causalityInterfaces

The causality interfaces by state, for the case where the causality interface is state dependent.

_causalityInterfacesVersions

private java.util.Map<State,java.lang.Long> _causalityInterfacesVersions

The workspace version for causality interfaces by state, for the case where the causality interface is state dependent.

_connectionMaps

private java.util.Map _connectionMaps

_connectionMapsVersion

private long _connectionMapsVersion

_currentConnectionMap

private java.util.Map _currentConnectionMap

_foundUnknown

private boolean _foundUnknown

A flag indicating that unknown inputs were referenced in guards and/or output value expressions (when guards evaluate to true) in the most recently called enabledTransition() or chooseTransition().

_identifierToPort

private java.util.HashMap<java.lang.String,Port> _identifierToPort

A map that associates each identifier with the unique port that that identifier describes. This map is used to detect port names that result in ambiguous identifier bindings.

_identifierToPortVersion

private long _identifierToPortVersion

Version number for _identifierToPort.

_inputPortsVersion

private transient long _inputPortsVersion

_newIteration

private boolean _newIteration

_outputPortsVersion

private transient long _outputPortsVersion

_reachedFinalState

private boolean _reachedFinalState

_receiversVersion

private long _receiversVersion

_supportMultirate

private boolean _supportMultirate

_tokenListArrays

private java.util.Hashtable _tokenListArrays

Constructor Detail

FSMActor

public FSMActor()

Construct an FSMActor in the default workspace with an empty string as its name. Add the actor to the workspace directory. Increment the version number of the workspace.

FSMActor

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

Create an FSMActor in the specified container with the specified name. The name must be unique within the container or an exception is thrown. The container argument must not be null, or a NullPointerException will be thrown.

Parameters:

container - The container.

name - The name of this actor within the container.

Throws:

IllegalActionException - If the entity cannot be contained by the proposed container.

NameDuplicationException - If the name coincides with an entity already in the container.

FSMActor

public FSMActor(Workspace workspace)

Construct an FSMActor in the specified workspace with an empty string as its name. You can then change the name with setName(). If the workspace argument is null, then use the default workspace. Add the actor to the workspace directory. Increment the version number of the workspace.

Parameters:

workspace - The workspace that will list the actor.

Method Detail

addInitializable

public void addInitializable(Initializable initializable)

Add the specified object to the list of objects whose preinitialize(), intialize(), and wrapup() methods should be invoked upon invocation of the corresponding methods of this object.

Specified by:

addInitializable in interface Initializable

Parameters:

initializable - The object whose methods should be invoked.

See Also:

removeInitializable(Initializable), CompositeActor.addPiggyback(Executable)

chooseTransition

public Transition chooseTransition(java.util.List transitionList)
                            throws IllegalActionException

Return an enabled transition among the given list of transitions for which both the guard expression and the output actions can be evaluated (the inputs referred by these are known). If there is only one transition enabled, return that transition. In case there are multiple enabled transitions, if any of them is not nondeterministic, throw an exception. See Transition for the explanation of "nondeterministic". Otherwise, randomly choose one from the enabled transitions and return it if the output actions can be evaluated. Execute the output actions contained by the returned transition before returning.

After calling this method, you can call foundUnknown() to determine whether any guard expressions or output value expressions on a transition whose guard evaluates to true were found in the specified transition list that referred to input ports that are not currently known.

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 and not all of them are nondeterministic.

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 CompositeEntity

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)

createReceivers

public void createReceivers()
                     throws IllegalActionException

Create receivers for each input port. In case the receivers don't need to be created they are reset

Specified by:

createReceivers in interface Actor

Throws:

IllegalActionException - If any port throws it.

See Also:

AtomicActor.createReceivers(), CompositeActor.createReceivers()

currentState

public State currentState()

Return the current state of this actor.

Returns:

The current state of this actor.

enabledTransitions

public java.util.List enabledTransitions(java.util.List transitionList)
                                  throws IllegalActionException

Return a list of enabled transitions among the given list of transitions. This includes all transitions whose guards can can be evaluated and evaluate to true, plus, if all guards can be evaluated and evaluate to false, all default transitions.

After calling this method, you can call foundUnknown() to determine whether any guard expressions were found in the specified transition list that referred to input ports that are not currently known.

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.

exportSubmodel

public void exportSubmodel(java.io.Writer output,
                           int depth,
                           java.lang.String name)
                    throws java.io.IOException

Write this FSMActor into the output writer as a submodel. All refinements of the events in this FSMActor will be exported as configurations of those events, not as composite entities belonging to the closest modal model.

Parameters:

output - The output stream to write to.

depth - The depth in the hierarchy, to determine indenting.

name - The name to use in the exported MoML.

Throws:

java.io.IOException - If an I/O error occurs.

fire

public void fire()
          throws IllegalActionException

Set the values of input variables. Choose the enabled transition among the outgoing transitions of the current state. Throw an exception if there is more than one transition enabled. Otherwise, execute the output actions contained by the chosen transition.

Specified by:

fire in interface Executable

Throws:

IllegalActionException - If there is more than one transition enabled.

foundUnknown

public boolean foundUnknown()

Return true if the most recent call to enabledTransition() or chooseTransition() found guard expressions or output value expressions that could not be evaluated due to unknown inputs. Specifically, after calling enabledTransitions(List), call this method to see whether there were guard expressions in the specified list that could not be evaluated. After calling chooseTransition(List), call this to determine whether any guard expressions or output value expressions on a transition whose guard evaluates to true were found in the specified transition list that referred to input ports that are not currently known.

Returns:

True If guards or output value expressions could not be evaluated.

getCausalityInterface

public CausalityInterface getCausalityInterface()

Return a causality interface for this actor. This method returns an instance of class FSMCausalityInterface if the enclosing director returns true in its implementsStrictActorSemantics() method. Otherwise, it returns an interface of class DefaultCausalityInterface.

Specified by:

getCausalityInterface in interface Actor

Returns:

A representation of the dependencies between input ports and output ports.

getContext

public Entity getContext()

Return the change context being made explicit. This class returns this.

Specified by:

getContext in interface ExplicitChangeContext

Returns:

The change context being made explicit

getDirector

public Director getDirector()

Return the director responsible for the execution of this actor. In this class, this is always the executive director. Return null if either there is no container or the container has no director.

Specified by:

getDirector in interface Actor

Returns:

The director that invokes this actor.

getExecutiveDirector

public Director getExecutiveDirector()

Return the executive director (same as getDirector()).

Specified by:

getExecutiveDirector in interface Actor

Returns:

The executive director.

getInitialState

public State getInitialState()
                      throws IllegalActionException

Return the initial state of this actor. The initial state is the unique state with its isInitialState parameter set to true. An exception is thrown if this actor does not contain an initial state. This method is read-synchronized on the workspace.

Returns:

The initial state of this actor.

Throws:

IllegalActionException - If this actor does not contain a state with the specified name.

getLastChosenTransition

public Transition getLastChosenTransition()

Get the last chosen transition.

Returns:

The last chosen transition.

See Also:

setLastChosenTransition(Transition)

getManager

public Manager getManager()

Return the Manager responsible for execution of this actor, if there is one. Otherwise, return null.

Specified by:

getManager in interface Actor

Returns:

The manager.

getModifiedVariables

public java.util.List getModifiedVariables()
                                    throws IllegalActionException

Return a list of variables that this entity modifies. The variables are assumed to have a change context of the given entity. This method returns the destinations of all choice and commit identifiers that are deeply contained by this actor. Note that this actor is also used as the controller of modal models and FSMDirector reports destinations of all choice and commit identifiers, even those not contained by the finite state machine.

Specified by:

getModifiedVariables in interface ExplicitChangeContext

Returns:

A list of variables.

Throws:

IllegalActionException - If a valid destination object can not be found.

See Also:

FSMDirector.getModifiedVariables()

getPortScope

public ParserScope getPortScope()

Return a scope object that has current values from input ports of this FSMActor in scope. This scope is used to evaluate guard expressions and set and output actions.

Returns:

A scope object that has current values from input ports of this FSMActor in scope.

hasInput

public boolean hasInput()

Test whether new input tokens have been received at the input ports.

Returns:

true if new input tokens have been received.

hasInput

public boolean hasInput(Port port)

Test whether new input tokens have been received at the given input port.

Parameters:

port - The input port.

Returns:

true if new input tokens have been received.

initialize

public void initialize()
                throws IllegalActionException

Initialize this actor by setting the current state to the initial state.

Specified by:

initialize in interface Initializable

Throws:

IllegalActionException - If a derived class throws it.

inputPortList

public java.util.List inputPortList()

Return a list of the input ports. This method is read-synchronized on the workspace.

Specified by:

inputPortList in interface Actor

Returns:

A list of input IOPort objects.

isFireFunctional

public boolean isFireFunctional()

Return false. During the fire() method, if a transition is enabled, it will be taken and the actions associated with this transition are executed. We assume the actions will change states of this actor.

Specified by:

isFireFunctional in interface Executable

Returns:

False.

isOpaque

public boolean isOpaque()

Return true.

Overrides:

isOpaque in class CompositeEntity

Returns:

True.

See Also:

CompositeEntity

isStrict

public boolean isStrict()
                 throws IllegalActionException

Return false. This actor checks inputs to see whether they are known before evaluating guards, so it can fired even if it has unknown inputs.

Specified by:

isStrict in interface Executable

Returns:

False.

Throws:

IllegalActionException - Not thrown in this base class.

iterate

public int iterate(int count)
            throws IllegalActionException

Invoke a specified number of iterations of the actor. An iteration is equivalent to invoking prefire(), fire(), and postfire(), in that order. In an iteration, if prefire() returns true, then fire() will be called once, followed by postfire(). Otherwise, if prefire() returns false, fire() and postfire() are not invoked, and this method returns NOT_READY. If postfire() returns false, then no more iterations are invoked, and this method returns STOP_ITERATING. Otherwise, it returns COMPLETED. If stop() is called while this is executing, then cease executing and return STOP_ITERATING.

Specified by:

iterate in interface Executable

Parameters:

count - The number of iterations to perform.

Returns:

NOT_READY, STOP_ITERATING, or COMPLETED.

Throws:

IllegalActionException - If iterating is not permitted, or if prefire(), fire(), or postfire() throw it.

newPort

public Port newPort(java.lang.String name)
             throws NameDuplicationException

Create a new TypedIOPort with the specified name. The container of the port is set to this actor. This method is write-synchronized on the workspace.

Overrides:

newPort in class ComponentEntity

Parameters:

name - The name for the new port.

Returns:

The new port.

Throws:

NameDuplicationException - If the actor already has a port with the specified name.

newReceiver

public Receiver newReceiver()
                     throws IllegalActionException

Return a new receiver obtained from the director.

Specified by:

newReceiver in interface Actor

Returns:

A new object implementing the Receiver interface.

Throws:

IllegalActionException - If there is no director.

newRelation

public ComponentRelation newRelation(java.lang.String name)
                              throws IllegalActionException,
                                     NameDuplicationException

Create a new instance of Transition with the specified name in this actor, and return it. This method is write-synchronized on the workspace.

Overrides:

newRelation in class CompositeEntity

Parameters:

name - The name of the new transition.

Returns:

A transition with the given name.

Throws:

IllegalActionException - If the name argument is null.

NameDuplicationException - If name collides with that of a transition already in this actor.

outputPortList

public java.util.List outputPortList()

Return a list of the output ports. This method is read-synchronized on the workspace.

Specified by:

outputPortList in interface Actor

Returns:

A list of output IOPort objects.

postfire

public boolean postfire()
                 throws IllegalActionException

Execute actions on the last chosen transition. Change state to the destination state of the last chosen transition.

Specified by:

postfire in interface Executable

Returns:

True, unless stop() has been called, in which case, false.

Throws:

IllegalActionException - If any action throws it.

prefire

public boolean prefire()
                throws IllegalActionException

Return true.

Specified by:

prefire in interface Executable

Returns:

True.

Throws:

IllegalActionException - Not thrown in this base class.

preinitialize

public void preinitialize()
                   throws IllegalActionException

Create receivers and input variables for the input ports of this actor, and validate attributes of this actor, and attributes of the ports of this actor. Set current state to the initial state.

Specified by:

preinitialize in interface Initializable

Throws:

IllegalActionException - If this actor does not contain an initial state.

readInputs

public void readInputs()
                throws IllegalActionException

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

Throws:

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

readOutputsFromRefinement

public void readOutputsFromRefinement()
                               throws IllegalActionException

Set the input variables for channels that are connected to an output port of the refinement of current state.

Throws:

IllegalActionException - If a value variable cannot take the token read from its corresponding channel.

removeInitializable

public void removeInitializable(Initializable initializable)

Remove the specified object from the list of objects whose preinitialize(), intialize(), and wrapup() methods should be invoked upon invocation of the corresponding methods of this object. If the specified object is not on the list, do nothing.

Specified by:

removeInitializable in interface Initializable

Parameters:

initializable - The object whose methods should no longer be invoked.

See Also:

addInitializable(Initializable), CompositeActor.removePiggyback(Executable)

reset

public void reset()
           throws IllegalActionException

Reset current state to the initial state.

Throws:

IllegalActionException - If thrown while getting the initial state or setting the current connection map.

setLastChosenTransition

public void setLastChosenTransition(Transition transition)

Set the last chosen transition.

Parameters:

transition - The last chosen transition.

See Also:

getLastChosenTransition()

setNewIteration

public void setNewIteration(boolean newIteration)

Set the flag indicating whether we are at the start of a new iteration (firing). Normally, the flag is set to true. It is only set to false in HDF.

Parameters:

newIteration - A boolean variable indicating whether this is a new iteration.

setSupportMultirate

public void setSupportMultirate(boolean supportMultirate)

Set true indicating that this actor supports multirate firing.

Parameters:

supportMultirate - A boolean variable indicating whether this actor supports multirate firing.

stop

public void stop()

Request that execution of the current iteration stop as soon as possible. In this class, we set a flag indicating that this request has been made (the protected variable _stopRequested). This will result in postfire() returning false.

Specified by:

stop in interface Executable

stopFire

public void stopFire()

Do nothing.

Specified by:

stopFire in interface Executable

terminate

public void terminate()

Call stop().

Specified by:

terminate in interface Executable

typeConstraints

public java.util.Set<Inequality> typeConstraints()

Return the type constraints of this actor. The constraints have the form of a set of inequalities. This method first creates constraints such that the type of any input port that does not have its type declared must be less than or equal to the type of any output port that does not have its type declared. Type constraints from the contained Typeables (ports, variables, and parameters) are collected. In addition, type constraints from all the transitions are added. These constraints are determined by the guard and trigger expressions of transitions, and actions contained by the transitions. This method is read-synchronized on the workspace.

Specified by:

typeConstraints in interface TypedActor

Returns:

A list of inequalities.

See Also:

Inequality

wrapup

public void wrapup()
            throws IllegalActionException

Do nothing except invoke the wrapup method of any objects that have been added using addInitializable(). Derived classes override this method to define operations to be performed exactly once at the end of a complete execution of an application. It typically closes files, displays final results, etc.

Specified by:

wrapup in interface Initializable

Throws:

IllegalActionException - Not thrown in this base class.

_addEntity

protected void _addEntity(ComponentEntity entity)
                   throws IllegalActionException,
                          NameDuplicationException

Add a state to this FSMActor. This overrides the base-class method to make sure the argument is an instance of State. This method is not synchronized on the workspace, so the caller should be.

Overrides:

_addEntity in class CompositeEntity

Parameters:

entity - State to contain.

Throws:

IllegalActionException - If the state has no name, or the action would result in a recursive containment structure, or the argument is not an instance of State.

NameDuplicationException - If the name collides with a name already on the state list.

_addRelation

protected void _addRelation(ComponentRelation relation)
                     throws IllegalActionException,
                            NameDuplicationException

Add a transition to this FSMActor. This method should not be used directly. Call the setContainer() method of the transition instead. This method does not set the container of the transition to refer to this container. This method is not synchronized on the workspace, so the caller should be.

Overrides:

_addRelation in class CompositeEntity

Parameters:

relation - Transition to contain.

Throws:

IllegalActionException - If the transition has no name, or is not an instance of Transition.

NameDuplicationException - If the name collides with a name already on the contained transitions list.

_commitLastChosenTransition

protected void _commitLastChosenTransition()
                                    throws IllegalActionException

Execute all set actions contained by the transition chosen during the last call to chooseTransition(). Change current state to the destination state of the transition. Reset the refinement of the destination state if the reset parameter of the transition is true.

Throws:

IllegalActionException - If any commit action throws it, or the last chosen transition does not have a destination state.

_getChannelForIdentifier

protected int _getChannelForIdentifier(java.lang.String identifier)
                                throws IllegalActionException

Given an identifier, return a channel number i if the identifier is of the form portName_i, portName_i_isPresent, portName_iArray. Otherwise, return -1.

Parameters:

identifier - An identifier.

Returns:

A channel index, if the identifier refers to one.

Throws:

IllegalActionException - If getting the width of the port fails.

_getPortForIdentifier

protected Port _getPortForIdentifier(java.lang.String identifier)
                              throws IllegalActionException

Get the port for the specified identifier, which may be of form portName, portName_isPresent, portName_i, portName_i_isPresent, etc.

Parameters:

identifier - The specified identifier.

Returns:

The port that corresponds with teh specified identifier.

Throws:

IllegalActionException - If getting the width of the port fails.

_isRefinementOutput

protected boolean _isRefinementOutput(IOPort port,
                                      int channel)
                               throws IllegalActionException

Return true if the channel of the port is connected to an output port of the refinement of current state. If the current state does not have refinement, return false.

Parameters:

port - An input port of this actor.

channel - A channel of the input port.

Returns:

True if the channel of the port is connected to an output port of the refinement of current state.

Throws:

IllegalActionException - If the refinement specified for one of the states is not valid.

_readInputs

protected void _readInputs(IOPort port,
                           int channel)
                    throws IllegalActionException

Read tokens from the given channel of the given input port and make them accessible to the expressions of guards and transitions through the port scope. If the specified port is not an input port, then do nothing.

Parameters:

port - An input port of this actor.

channel - A channel of the input port.

Throws:

IllegalActionException - If the port is not contained by this actor.

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

Throws:

IllegalActionException - If the refinement specified for one of the states is not valid.

_buildConnectionMaps

private void _buildConnectionMaps()
                           throws IllegalActionException

Throws:

IllegalActionException

_createReceivers

private void _createReceivers()
                       throws IllegalActionException

Create receivers for each input port. This method gets write permission on the workspace.

Throws:

IllegalActionException - If any port throws it.

_init

private void _init()

_removePortVariables

private void _removePortVariables(java.lang.String portName,
                                  int channel)

Remove all variable definitions associated with the specified port name and channel number.

Parameters:

portName - The name of the port

channel - The channel number

_resetReceivers

private void _resetReceivers()
                      throws IllegalActionException

Reset receivers for each input port.

Throws:

IllegalActionException - If any port throws it.

_referencedInputPortValuesByGuardPresent

private boolean _referencedInputPortValuesByGuardPresent(Transition transition)
                                                  throws IllegalActionException

Given a transition, return false if the guard includes any reference to an input port value and that input port is known to be absent, or any reference to an input port whose status is unknown. Otherwise, return true. A reference to an input port with "_isPresent" appended is not considered. Note that you have to be very careful using this. E.g., if the guard expression is (!in_isPresent || in == 1) then this method would return false when in is absent, even though the guard can be evaluated and evaluates to true. Thus, the correct usage is to attempt first to evaluate the guard, and only if the evaluation fails, then use this method to determine whether the cause is the absence of input.

Parameters:

transition - A transition

Returns:

False if the guard includes references to values of input ports that are absent.

Throws:

IllegalActionException - If the guard expression cannot be parsed.

_referencedInputPortsByGuardKnown

private boolean _referencedInputPortsByGuardKnown(Transition transition)
                                           throws IllegalActionException

Given a transition, find any input ports referenced in the guard expressions of the transition, and if any of those input ports has status unknown, return false. Otherwise, return true. These are the input ports whose status must be known for this transition to be enabled.

Parameters:

transition - A transition

Returns:

True if all input ports referenced by the guard on the transition have known status.

Throws:

IllegalActionException - If the guard expression cannot be parsed.

_referencedInputPortsByOutputKnown

private boolean _referencedInputPortsByOutputKnown(Transition transition)
                                            throws IllegalActionException

Given a transition, find any input ports referenced in the output actions of the transitions, and if any of those input ports has status unknown, return false. Otherwise, return true. These are the input ports whose status must be known to choose this transition.

Parameters:

transition - A transition

Returns:

A set of input ports.

Throws:

IllegalActionException - If the guard expression cannot be parsed.

_setIdentifierToPort

private void _setIdentifierToPort()
                           throws IllegalActionException

For each input port of this actor, associate all identifiers with that port.

Throws:

IllegalActionException - If getting the width of the port fails.

_setInputTokenMap

private void _setInputTokenMap(Port port,
                               int channel,
                               Token token,
                               Token[] tokenArray)
                        throws IllegalActionException

Set the port variables for the specified port as follows: The portName_isPresent variable is set to true if the token argument is non-null, and false otherwise. If the token argument is non-null, then the portName variable is set to have the value of the token. If the tokenArray variable is non-null, then the portNameArray variable is set to have its value. In addition, for each of these cases, another (up to) three variables are set with portName replaced by portName_i, where i is the channel number. If token is null, then the variable portName is set to have the value Token.NIL. Note that this yields far better error messages than leaving it unset, because if if it not set, portName will resolve to the port itself, which can be very confusing.

Parameters:

port - The port.

channel - The channel.

token - If not null, the data token at the port.

tokenArray - If not null, an array of tokens at the port.

Throws:

IllegalActionException - If the identifier is already associated with another port.