A Transition has a source state and a destination state. A
transition has a guard expression, which is evaluated to a boolean value.
Whenever a transition out of the current state
is enabled, it must be taken in the current firing.
That is, unlike some state machines formalisms, our guard is not just
an enabler for the transition but rather a trigger for the transition.
<p> A transition can contain actions. The way to specify actions is
to give value to the <i>outputActions</i> parameter and the
<i>setActions</i> parameter.
The value of these parameters is a string of the form:
<pre>
<i>command</i>; <i>command</i>; ...
</pre>
where each <i>command</i> has the form:
<pre>
<i>destination</i> = <i>expression</i>
</pre>
For the <i>outputActions</i> parameter, <i>destination</i> is either
<pre>
<i>portName</i>
</pre>
or
<pre>
<i>portName</i>(<i>channelNumber</i>)
</pre>
Here, <i>portName</i> is the name of a port of the FSM actor,
If no <i>channelNumber</i> is given, then the value
is broadcast to all channels of the port.
<p>
For the <i>setActions</i> parameter, <i>destination</i> is
<pre>
<i>variableName</i>
</pre>
<i>variableName</i> identifies either a variable or parameter of
the FSM actor, or a variable or parameter of the refinement of the
destination state of the transition. To give a variable of the
refinement, use a dotted name, as follows:
<pre>
<i>refinementName</i>.<i>variableName</i>
</pre>
The <i>expression</i> is a string giving an expression in the usual
Ptolemy II expression language. The expression may include references
to variables and parameters contained by the FSM actor.
<p>
The <i>outputActions</i> and <i>setActions</i> parameters are not the only
ways to specify actions. In fact, you can add action attributes that are
instances of anything that inherits from Action.
(Use the Add button in the Edit Parameters dialog).
<p>
An action is either a ChoiceAction or a CommitAction. The <i>setActions</i>
parameter is a CommitAction, whereas the <i>outputActions</i> parameter is a
ChoiceAction. A commit action is executed when the transition is taken to
change the state of the FSM, in the postfire() method of FSMActor.
A choice action, by contrast, is executed in the fire() method
of the FSMActor when the transition is chosen, but not yet taken.
The difference is subtle, and for most domains, irrelevant.
A few domains, however, such as CT, which have fixed point semantics,
where the fire() method may be invoked several times before the
transition is taken (committed). For such domains, it is useful
to have actions that fulfill the ChoiceAction interface.
Such actions participate in the search for a fixed point, but
do not change the state of the FSM.
<p>
A transition can be preemptive or non-preemptive. When a preemptive transition
is chosen, the refinement of its source state is not fired. A non-preemptive
transition is only chosen after the refinement of its source state is fired.
<p>
The <i>history</i> parameter specifies whether the refinement of the destination
state refinement is initialized when the transition is taken. By default, this
is false, which means that the destination refinement is initialized.
If you change this to true, then the destination refinement will not be
initialized, so when the state is re-entered, the refinement will
continue executing where it left off.
<p>
The <i>nondeterministic</i> parameter specifies whether this transition is
nondeterministic. Here nondeterministic means that this transition may not
be the only enabled transition at a time. The default value is a boolean
token with value as false, meaning that if this transition is enabled, it
must be the only enabled transition.
<p>
The <i>immediateTransition</i> parameter, if given a value true, specifies
that this transition is may be taken as soon as its source state is entered,
in the same iteration. This may lead to transient states, where a state is
passed through without ever becoming the current state.
<p>
The <i>defaultTransition</i> parameter, if given a value true, specifies
that this transition is enabled if no other non-default
transition is enabled and if its guard evaluates to true.
<p>
The <i>error</i> parameter, if given a value true, specifies
that this transition is enabled if the refinement of the source state of
the transition throws a model error or an exception
while executing. The default value is a boolean
token with value false. When such an exception or model error
occurs, two variables are set that may be used in the guard
or the output or set actions of this transition:
<ul>
<li> <i>errorMessage</i>: The error message (a string).
<li> <i>errorClass</i>: The class of the exception thrown.
</ul>
In addition, if the exception is an instance of KernelException
or a subclass (such as IllegalActionException), then a third
variable is set:
<ul>
<li> <i>errorCause</i>: The Ptolemy object that caused the exception.
</ul>
The <i>errorCause</i> is made available as an ObjectToken on which
you can invoke methods such as getName() in the guard or output
or set actions of this transition.
Xiaojun Liu, Edward A. Lee, Haiyang Zheng, Christian Motika
$Id: Transition.java 70402 2014-10-23 00:52:20Z cxh $
Ptolemy II 8.0
Yellow (hyzheng)
Red (hyzheng)
An annotation that describes the transition. If this is non-empty,
then a visual editor will be expected to put this annotation on
or near the transition to document its function. This is a string
that defaults to the empty string. Note that it can reference
variables in scope using the notation $name.
Indicator that this transition is a default transition. A
default transition is enabled only if no other non-default
transition is enabled. This is a boolean with default value
false. If the value is true, then the guard expression is
ignored.
Parameter specifying whether this transition should be treated
as an error transition. The default value is a boolean with
the value false, which indicates that this transition is not
an error transition. If the value is true, that this transition
is enabled if and only if the refinement of the source state of
the transition throws a model error while executing.
Attribute the exit angle of a visual rendition.
This parameter contains a DoubleToken, initially with value PI/5.
It must lie between -PI and PI. Otherwise, it will be truncated
to lie within this range.
The name of the transition, which defaults to the name of
the transition followed by the string "Parameter".
Attribute giving the orientation of a self-loop. This is equal to
the tangent at the midpoint (more or less).
This parameter contains a DoubleToken, initially with value 0.0.
Parameter specifying whether the refinements of the destination
state are initialized when the transition is taken.
This is a boolean that defaults to false.
Parameter specifying whether this transition is immediate.
Parameter specifying whether this transition is nondeterministic.
Here nondeterministic means that this transition may not be the only
enabled transition at a time. The default value is a boolean token
with value as false, meaning that if this transition is enabled, it
must be the only enabled transition.
Parameter specifying whether this transition is preemptive.
True of the the value of the <a href="../../../../ptolemy/domains/modal/kernel/Transition.xml#fsmTransitionParameterName">fsmTransitionParameterName</a> parameter
should be returned by <a href="../../../../ptolemy/domains/modal/kernel/Transition.html#getLabel">getLabel()</a>.
Parameter specifying whether the refinements of the origin
state must have terminated (postfire has returned false)
for the transition to be enabled.
Attribute specifying the guard expression.
The action commands that produce outputs when the transition is taken.
Attribute specifying one or more names of refinements. The
refinements must be instances of TypedActor and have the same
container as the FSMActor containing this state, otherwise
an exception will be thrown when getRefinement() is called.
Usually, the refinement is a single name. However, if a
comma-separated list of names is provided, then all the specified
refinements will be executed.
This attribute has a null expression or a null string as
expression when the state is not refined.
The action commands that set parameters when the transition is taken.
By default, this is empty.