Package ptolemy.domains.modal.kernel

Class FSMActor

java.lang.Object

ptolemy.kernel.util.NamedObj

ptolemy.kernel.InstantiableNamedObj

ptolemy.kernel.Entity<T>

ptolemy.kernel.ComponentEntity

ptolemy.kernel.CompositeEntity

ptolemy.domains.modal.kernel.FSMActor

All Implemented Interfaces:

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

Direct Known Subclasses:

FmvAutomaton, FSMMatcher, InterfaceAutomaton, ModalController, TDLActor

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 specifically, 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. Note that this class provides no guarantees about the probability of selecting a particular nondeterministic transition. It is perfectly valid to always choose the same one, for example. To provide such a guarantee, we would have to impose the constraint that no nondeterministic transition can be chosen until the guards of all nondeterministic transitions can be evaluated. This would rule out certain models, in particular those that illustrate the celebrated Brock-Ackerman anomaly. Hence, in this implementation, 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, if it is still enabled. If more transitions become enabled in subsequent firings and they are not all marked nondeterminate, then an exception will thrown. All of 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). Thus, to correctly realize all nondeterministic systems, we cannot provide probabilistic execution of nondeterministic transitions.

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$

Author:

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

See Also:

State, Transition, Action, FSMDirector

Pt.AcceptedRating:

Yellow (kienhuis)

Pt.ProposedRating:

Yellow (liuxj)

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
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

Fields

Modifier and Type	Field	Description
protected State	_currentState	Current state.
protected java.util.Set<Actor>	_disabledRefinements	State and transition refinements that have returned false in postfire().
protected java.util.List<Initializable>	_initializables	List of objects whose (pre)initialize() and wrapup() methods should be slaved to these.
protected java.util.Map	_inputTokenMap	A map from ports to corresponding input variables.
protected Transition	_lastChosenTransition	The most recently chosen transition within the fire() method.
protected java.util.HashMap<State,Transition>	_lastChosenTransitions	The last chosen transitions, by state from which these transitions emerge.
protected java.util.List<Transition>	_lastTakenTransitions	The last taken transitions, by state from which these transitions emerge.
protected java.util.List<Actor>	_stateRefinementsToPostfire	State refinements to postfire(), as determined by the fire() method.
protected boolean	_stopRequested	Indicator that a stop has been requested by a call to stop().
Parameter	errorCause	Parameter containing the cause of an exception thrown while executing a refinement if the exception is a KernelException that specified a Nameable.
StringParameter	errorClass	Parameter containing the name of the class of exception thrown while executing a refinement.
StringParameter	errorMessage	Parameter containing the message of exception thrown while executing a refinement.
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	probability	Parameter that is a function which evaluates to true when the randomly generated token value is within the probability range expressed by a transition.
SharedParameter	resetOnEachRun	Boolean parameter to determine whether seeds are reset on each run.
SharedParameter	seed	The seed to be used for random token generation, to evaluate probabilistic transitions between states.
Parameter	stateDependentCausality	Indicate whether input/output dependencies can depend on the state.
Parameter	timeout	Parameter that is a function that evaluates to true when the time elapsed in the current state equals the argument to the function.

Fields inherited from class ptolemy.kernel.CompositeEntity

_levelCrossingLinks

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _deferChangeRequests, _elementName, _isPersistent, _verbose, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS

Fields inherited from interface ptolemy.actor.Executable

COMPLETED, NOT_READY, STOP_ITERATING

Constructor Summary

Constructors

Constructor	Description
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

Modifier and Type	Method	Description
protected void	_addEntity(ComponentEntity entity)	Add a state to this FSMActor.
protected void	_addRelation(ComponentRelation relation)	Add a transition to this FSMActor.
protected boolean	_areAllImmediateTransitionsDisabled(State state)	Return true if all immediate transitions from the specified state have guards that can be evaluated and that evaluate to false.
protected void	_chooseTransitions(java.util.List<Transition> transitionList, boolean preemptive, boolean immediateOnly, boolean inInitialize, boolean inPreinitialize)	Choose zero or more transitions enabled in the current state from the list of specified transitions.
protected State	_destinationState()	Return the chosen destination state.
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 IOPort	_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.
protected java.util.List<Actor>	_getStateRefinementsToPostfire()	Return the list used to keep track of refinements that have been fired.
protected java.util.List<Actor>	_getTransitionRefinementsToPostfire()	Return the list used to keep track of refinements that have been fired.
protected void	_init()
protected void	_initializeRefinements(State state)	Initialize the refinements of the specified state.
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 boolean	_isSafeToClear(IOPort port, int channel, State state, boolean immediateOnly, java.util.HashSet<State> visitedStates)	Given an output port and channel, determine whether the output port must be absent on the specified channel, given whatever current information about the inputs is available (the inputs may be known or unknown).
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.
protected boolean	_schedule(NamedObj actor, Time timestamp)	Schedule an actor for execution on a ExecutionAspect.
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	_setTimeForRefinement(Actor refinement)	Set the refinements current time equal to the matching environment, or if there is no environment, do nothing.
void	addChosenTransition(State state, Transition transition)	Add a chosen transition to the set of chosen transitions.
void	addInitializable(Initializable initializable)	Add the specified object to the list of objects whose preinitialize(), initialize(), and wrapup() methods should be invoked upon invocation of the corresponding methods of this object.
void	attributeChanged(Attribute attribute)	If the attribute is seed then create the base random number generator.
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, boolean preemptive, boolean immediateOnly)	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()	Deprecated. Use getLastChosenTransitions() instead.
java.util.Map<State,Transition>	getLastChosenTransitions()	Get the last chosen transitions.
java.util.List<Transition>	getLastTakenTransitions()	Get the last taken transitions.
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	handleModelError(NamedObj context, IllegalActionException exception)	Handle a model error.
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	isBackwardTypeInferenceEnabled()	Return false because backward type inference is not implemented for this actor.
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(), initialize(), 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)	Deprecated. Use addChosenTransition(State, 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.
boolean	wasTransitionTaken()	Return true if a transition was taken in the previous iteration, or if this is before the first iteration concludes, true if during initialize an immediate transition was taken.
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, _containedDecorators, _deepOpaqueEntityList, _description, _exportMoMLContents, _finishedAddEntity, _removeEntity, _removeRelation, _validateSettables, allAtomicEntityList, allowLevelCrossingConnect, classDefinitionList, connect, connect, containedObjectsIterator, deepCompositeEntityList, deepEntityList, deepGetEntities, deepNamedObjList, deepOpaqueEntityList, deepRelationSet, entityList, entityList, exportLinks, exportMoML, getAttribute, getEntities, getEntity, getPort, getRelation, getRelations, isAtomic, lazyAllAtomicEntityList, lazyAllCompositeEntityList, lazyAllCompositeTransparentAndOpaqueEntityList, lazyClassDefinitionList, lazyDeepEntityList, lazyEntityList, lazyRelationList, numberOfEntities, numberOfRelations, numEntities, numRelations, relationList, removeAllEntities, removeAllRelations, setClassDefinition, setContainer, statistics, uniqueName

Methods inherited from class ptolemy.kernel.ComponentEntity

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

Methods inherited from class ptolemy.kernel.Entity

_addPort, _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, _copyChangeRequestList, _debug, _debug, _debug, _debug, _debug, _executeChangeRequests, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _notifyHierarchyListenersAfterChange, _notifyHierarchyListenersBeforeChange, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, addHierarchyListener, attributeDeleted, attributeList, attributeList, attributeTypeChanged, clone, decorators, 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, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, notifyOfNameChange, propagateValue, propagateValues, removeAttribute, removeChangeListener, removeDebugListener, removeHierarchyListener, 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.Derivable

getDerivedLevel, getDerivedList, propagateValue

Methods inherited from interface ptolemy.kernel.util.Nameable

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

Field Detail

errorCause

public Parameter errorCause

Parameter containing the cause of an exception thrown while executing a refinement if the exception is a KernelException that specified a Nameable. This parameter may be used in a guard expression or output or set action to access the object that originated an exception on an error transition. This is an object token that defaults to null. This parameter is not persistent. It will not be exported to MoML.

errorClass

public StringParameter errorClass

Parameter containing the name of the class of exception thrown while executing a refinement. This parameter may be used in a guard expression or output or set action to access the class of an exception on an error transition. This is a string that defaults to the empty string. This parameter is not persistent. It will not be exported to MoML.

errorMessage

public StringParameter errorMessage

Parameter containing the message of exception thrown while executing a refinement. This parameter may be used in a guard expression or output or set action to access the message of an exception on an error transition. This is a string that defaults to the empty string. This parameter is not persistent. It will not be exported to MoML.

probability

public Parameter probability

Parameter that is a function which evaluates to true when the randomly generated token value is within the probability range expressed by a transition.

resetOnEachRun

public SharedParameter resetOnEachRun

Boolean parameter to determine whether seeds are reset on each run.

seed

public SharedParameter seed

The seed to be used for random token generation, to evaluate probabilistic transitions between states.

timeout

public Parameter timeout

Parameter that is a function that evaluates to true when the time elapsed in the current state equals the argument to the function. This can be used in a guard to trigger a transition.

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.

_disabledRefinements

protected java.util.Set<Actor> _disabledRefinements

State and transition refinements that have returned false in postfire().

_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 most recently chosen transition within the fire() method.

_lastChosenTransitions

protected java.util.HashMap<State,Transition> _lastChosenTransitions

The last chosen transitions, by state from which these transitions emerge.

_lastTakenTransitions

protected java.util.List<Transition> _lastTakenTransitions

The last taken transitions, by state from which these transitions emerge.

_stateRefinementsToPostfire

protected java.util.List<Actor> _stateRefinementsToPostfire

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

_stopRequested

protected boolean _stopRequested

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

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

addChosenTransition

public void addChosenTransition(State state,
                                Transition transition)
                         throws IllegalActionException

Add a chosen transition to the set of chosen transitions. There may be more than one chosen transition because the destination state of a chosen transition may have immediate transitions emerging from it.

Parameters:

state - The state that has the last chosen transition.

transition - The last chosen transition.

Throws:

IllegalActionException - If there is already a chosen transition associated with the specified state and it is not the same transition.

See Also:

getLastChosenTransitions()

addInitializable

public void addInitializable(Initializable initializable)

Add the specified object to the list of objects whose preinitialize(), initialize(), 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)

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

If the attribute is seed then create the base random number generator.

Overrides:

attributeChanged in class NamedObj

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - If the change is not acceptable to this container (not thrown in this base class).

isBackwardTypeInferenceEnabled

public boolean isBackwardTypeInferenceEnabled()

Return false because backward type inference is not implemented for this actor.

Specified by:

isBackwardTypeInferenceEnabled in interface TypedActor

Returns:

false

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,
                                         boolean preemptive,
                                         boolean immediateOnly)
                                  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.

preemptive - True to consider only preemptive transitions, false to consider only non-preemptive transitions.

immediateOnly - True to consider only immediate transitions, false to consider both immediate and non-immediate 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, boolean, boolean), call this method to see whether there were guard expressions in the specified list that could not be evaluated. After calling _chooseTransitions(List, boolean, boolean, boolean, boolean), 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

@Deprecated
public Transition getLastChosenTransition()

Deprecated.

Use getLastChosenTransitions() instead.

Get the last chosen transition from the current state. Note that this does not include chosen immediate transitions from the destination of the returned transition.

Returns:

The last chosen transition from the current state.

See Also:

setLastChosenTransition(Transition)

getLastChosenTransitions

public java.util.Map<State,Transition> getLastChosenTransitions()

Get the last chosen transitions.

Returns:

A map of last chosen transitions.

See Also:

addChosenTransition(State,Transition)

getLastTakenTransitions

public java.util.List<Transition> getLastTakenTransitions()

Get the last taken transitions.

Returns:

A list of last taken 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.

handleModelError

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

Handle a model error.

Specified by:

handleModelError in interface ModelErrorHandler

Overrides:

handleModelError in class NamedObj

Parameters:

context - The object in which the error occurred.

exception - An exception that represents the error.

Returns:

True if the error has been handled, or false if the error is not handled.

Throws:

IllegalActionException - If the handler handles the error by throwing an exception.

See Also:

NamedObj.setModelErrorHandler(ModelErrorHandler handler)

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. This method skips over ports that connected to outputs of a refinement.

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(), initialize(), 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

@Deprecated
public void setLastChosenTransition(Transition transition)

Deprecated.

Use addChosenTransition(State, Transition)

Set the last chosen transition. Note that this erases any previously set chosen transitions and makes the specified transition the only chosen transition, ignoring immediate transitions that this might lead to.

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

wasTransitionTaken

public boolean wasTransitionTaken()

Return true if a transition was taken in the previous iteration, or if this is before the first iteration concludes, true if during initialize an immediate transition was taken.

Returns:

True if a transition was taken.

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.

_areAllImmediateTransitionsDisabled

protected boolean _areAllImmediateTransitionsDisabled(State state)
                                               throws IllegalActionException

Return true if all immediate transitions from the specified state have guards that can be evaluated and that evaluate to false. Note that this will return true if there are no immediate transitions.

Parameters:

state - The state to check for immediate transitions.

Returns:

true If there are no immediate transitions or if they are all disabled.

Throws:

IllegalActionException - If the guard expression cannot be parsed or if it cannot yet be evaluated.

_chooseTransitions

protected void _chooseTransitions(java.util.List<Transition> transitionList,
                                  boolean preemptive,
                                  boolean immediateOnly,
                                  boolean inInitialize,
                                  boolean inPreinitialize)
                           throws IllegalActionException

Choose zero or more transitions enabled in the current state from the list of specified transitions. This method follows chains of immediate transitions, if there are any. As a side effect, the controller's _lastChosenTransitions protected variable will contain the chosen transitions.

Parameters:

transitionList - The candidate transitions.

preemptive - True to consider only preemptive transitions, and false to consider only non-preemptive transitions.

immediateOnly - If true, look only at immediate transitions from the current state. Otherwise, look at both immediate and non-immediate transitions.

inInitialize - True when this method is called from initialize or preinitialize, in which case, firing and initializing refinements is not allowed; note that the refinements will be initialized by the initialize method, but this prevents them from being initialized more than once. This could be important if, for example, the refinement produces an output during initialize in a domain where outputs are consumed, such as SDF.

inPreinitialize - True if this is being called in preinitialize. Outputs must not be produced in preinitialize, so we don't execute output actions if this argument is true.

Throws:

IllegalActionException - If something goes wrong.

_destinationState

protected State _destinationState()
                           throws IllegalActionException

Return the chosen destination state. This method follows the chain of chosen transitions from the current state to the new state, possibly traversing several immediate transitions.

Returns:

The state that will be the current state after all chosen transitions are taken, or null if there are no chosen transitions.

Throws:

IllegalActionException - If no controller is found.

_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 IOPort _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 the specified identifier.

Throws:

IllegalActionException - If getting the width of the port fails.

_getStateRefinementsToPostfire

protected java.util.List<Actor> _getStateRefinementsToPostfire()

Return the list used to keep track of refinements that have been fired. This is protected so that FSMDirector can mirror it with its own protected method so that subclasses of FSMDirector can access it.

Returns:

A list of actors to postfire.

_getTransitionRefinementsToPostfire

protected java.util.List<Actor> _getTransitionRefinementsToPostfire()

Return the list used to keep track of refinements that have been fired. This is protected so that FSMDirector can mirror it with its own protected method so that subclasses of FSMDirector can access it.

Returns:

A list of actors to postfire.

_initializeRefinements

protected void _initializeRefinements(State state)
                               throws IllegalActionException

Initialize the refinements of the specified state.

Parameters:

state - The state.

Throws:

IllegalActionException - If initialization 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.

_isSafeToClear

protected boolean _isSafeToClear(IOPort port,
                                 int channel,
                                 State state,
                                 boolean immediateOnly,
                                 java.util.HashSet<State> visitedStates)
                          throws IllegalActionException

Given an output port and channel, determine whether the output port must be absent on the specified channel, given whatever current information about the inputs is available (the inputs may be known or unknown).

The way this works is that it examines all the outgoing transitions of the current state. If the guard on the transition can be evaluated to false, then as far as this transition is concerned, the output port can be absent. Otherwise, two things happen. First, we check to see whether the output actions of a transition writes to the specified port. Second, we look at the destination state of the transition and examine all immediate transition emanating from that state. If none of the transitions makes an assignment to the output port, then we can safely assert that the output is absent, with one exception. If the output port already has a value, that value was probably set by another refinement. Thus, we should leave it alone.

This method ignores any state refinements, and consequently its analysis is valid only if all state refinements also assert that the output is absent.

Parameters:

port - The IOPort in question.

channel - The channel in question.

state - The state whose transitions are examined.

immediateOnly - True to examine only immediate transitions.

visitedStates - The set of states already visited, or null if none have yet been visited.

Returns:

True, if successful.

Throws:

IllegalActionException - If we cannot determine whether the port is known and absent.

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

_setTimeForRefinement

protected void _setTimeForRefinement(Actor refinement)
                              throws IllegalActionException

Set the refinements current time equal to the matching environment, or if there is no environment, do nothing.

Parameters:

refinement - The refinement.

Throws:

IllegalActionException - If setModelTime() throws it.

_schedule

protected boolean _schedule(NamedObj actor,
                            Time timestamp)
                     throws IllegalActionException

Schedule an actor for execution on a ExecutionAspect. If the actor can execute this method returns true. If resources are not available this method returns false.

Parameters:

actor - The actor.

timestamp - The time the actor requests to be scheduled.

Returns:

True if actor was scheduled and can be fired.

Throws:

IllegalActionException - Thrown if parameters cannot be read, actor cannot be scheduled or container cannot be fired at future time.

_init

protected void _init()