Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## avrora.sim
Class FiniteStateMachine

    java.lang.Object
      avrora.sim.FiniteStateMachine

public class FiniteStateMachine
extends java.lang.Object

The `FiniteStateMachine` class represents a model of a finite state machine that allows probing and monitoring the state of a device.

Nested Class Summary
`static interface` | `FiniteStateMachine.Probe` The `Probe` interface allows observation of the state changes of a finite state machine.
`protected class` | `FiniteStateMachine.State` The `State` class represents a state of the finite state machine, including its name as a String, the transition time to each of the other states, and a list of any probes attached to this state.
`protected class` | `FiniteStateMachine.TransitionEvent` The `TransitionEvent` class is used internally by the finite state machine for transitions that take 1 more more clock cycles.

Field Summary
`protected Clock` | `clock`
`protected int` | `curState`
`protected MulticastFSMProbe` | `globalProbe`
`static int` | `IN_TRANSITION`
`protected int` | `numStates`
`protected int` | `startState`
`protected FiniteStateMachine.State[]` | `states`
`protected FiniteStateMachine.TransitionEvent` | `transEvent`

Constructor Summary
`FiniteStateMachine(Clock c, int ss, java.lang.String[] nm, int tt)` This constructor for the `FiniteStateMachine` class creates a new finite state machine with the number of states corresponding to the length of the array containing the names of the states.
`FiniteStateMachine(Clock c, int ss, java.lang.String[] nm, int[][] ttm)` This constructor for the `FiniteStateMachine` class creates a new finite state machine with the number of states corresponding to the length of the array containing the names of the states.

Method Summary
`static int[][]` | `buildBimodalTTM(int size, int ds, int[] tf, int[] tt)` The `buildBimodalTTM()` method builds a transition time matrix that corresponds to a finite state machine with two modes.
`static int[][]` | `buildSparseTTM(int size, int tt)` The `buildSparseTTM()` method builds a transition time matrix that is uniform but sparse; the machine can transition from any state to any other state with the given transition time.
`static int[][]` | `buildUniformTTM(int size, int tt)` The `buildUniformTTM()` method builds a transition time matrix that is uniform; the machine can transition from any state to any other state with the given transition time.
`Clock` | `getClock()` The `getClock()` method gets the underlying clock driving the device.
`int` | `getCurrentState()` The `getCurrentState()` method returns an integer that represents the state that the machine is currently in.
`java.lang.String` | `getCurrentStateName()` The `getCurrentStateName()` method retrieves the name for the current state.
`int` | `getNumberOfStates()` The `getNumberOfStates()` method returns the total number of states that this machine has.
`int` | `getStartState()` The `getStartState()` method returns the state in which the machine starts operation.
`java.lang.String` | `getStateName(int state)` The `getStateName()` method retrieves the name for the specified state.
`int` | `getTransitionTime(int beforeState, int afterState)` The `getTransitionTime()` method retrieves the transition time between the two states specified from the transition time matrix.
`void` | `insertProbe(FiniteStateMachine.Probe p)` The `insertProbe()` method allows the insertion of a probe for each state transition of this finite state machine.
`void` | `insertProbe(FiniteStateMachine.Probe p, int state)` The `insertProbe()` method allows the insertion of a probe for transitions that involve a particular state, either transitioning from this state or from this state.
`static int[][]` | `newTTM(int size)` The `newTTM()` method is a utility function for building a new transition time matrix.
`void` | `removeProbe(FiniteStateMachine.Probe p)` The `removeProbe()` method removes a probe that has been inserted for all state transitions.
`void` | `removeProbe(FiniteStateMachine.Probe p, int state)` The `removeProbe()` method removes a probe that has been inserted for particular state transitions.
`static int[][]` | `setCircularTTM(int[][] ttm, int[] perm, int[] tt)` The `setCircularTTM()` method builds a transition time matrix that represents a finite state machine arranged in a ring; each state can transition to one other state, wrapping around.
`static int[][]` | `setDiagonal(int[][] ttm, int diag)` The `setDiagonal()` method sets the diagonal of the given transition time matrix to the specified value.
`void` | `transition(int newState)` The `transition()` method transitions the machine from the current state to a new state.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### IN_TRANSITION

    public static final int IN_TRANSITION

See Also:
  Constant Field Values

### numStates

    protected final int numStates

### startState

    protected final int startState

### clock

    protected final Clock clock

### transEvent

    protected final FiniteStateMachine.TransitionEvent transEvent

### globalProbe

    protected final MulticastFSMProbe globalProbe

### states

    protected FiniteStateMachine.State[] states

### curState

    protected int curState

Constructor Detail

### FiniteStateMachine

    public FiniteStateMachine(Clock c,
                              int ss,
                              java.lang.String[] nm,
                              int tt)

  This constructor for the `FiniteStateMachine` class creates a new finite state machine with the number of states corresponding to the length of the array containing the names of the states. The transition time matrix is uniform, with all entries being initialized to the same specified value.

Parameters:
  `c` - the clock driving this finite state machine
  `ss` - the starting state of this machine
  `nm` - an array of strings that name each of the states in this machine
  `tt` - the transition time for any state to any other state

### FiniteStateMachine

    public FiniteStateMachine(Clock c,
                              int ss,
                              java.lang.String[] nm,
                              int[][] ttm)

  This constructor for the `FiniteStateMachine` class creates a new finite state machine with the number of states corresponding to the length of the array containing the names of the states. The transition time matrix is specified explicitly. Note that this constructor DOES NOT copy the transition time matrix, so care should be taken not to modify the transition time matrix after the creation of this finite state machine.

Parameters:
  `c` - the clock that drives this finite state machine
  `ss` - the starting state of this machine
  `nm` - an array of strings that name each of the states in this machine
  `ttm` - the transition time matrix for this machine; this matrix is NOT COPIED for internal use.

Method Detail

### insertProbe

    public void insertProbe(FiniteStateMachine.Probe p)

  The `insertProbe()` method allows the insertion of a probe for each state transition of this finite state machine.

  Parameters:
    `p` - the probe to insert that will be called before and after each transition, including self-transitions (transitions from one state to the same state)

### removeProbe

    public void removeProbe(FiniteStateMachine.Probe p)

  The `removeProbe()` method removes a probe that has been inserted for all state transitions.

  Parameters:
    `p` - the probe to remove

### insertProbe

    public void insertProbe(FiniteStateMachine.Probe p,
                            int state)

  The `insertProbe()` method allows the insertion of a probe for transitions that involve a particular state, either transitioning from this state or from this state.

  Parameters:
    `p` - the probe to insert that will be called before and after each transition to or from the specified state, including self-transitions (transitions from this state to the same state)
    `state` - the state for which to insert the probe

### removeProbe

    public void removeProbe(FiniteStateMachine.Probe p,
                            int state)

  The `removeProbe()` method removes a probe that has been inserted for particular state transitions.

  Parameters:
    `p` - the probe to remove
    `state` - the state for which to remove this probe

### getNumberOfStates

    public int getNumberOfStates()

  The `getNumberOfStates()` method returns the total number of states that this machine has.

  Returns:
    the number of states in this machine

### getStartState

    public int getStartState()

  The `getStartState()` method returns the state in which the machine starts operation.

  Returns:
    an integer that represents the start state for this machine

### getCurrentState

    public int getCurrentState()

  The `getCurrentState()` method returns an integer that represents the state that the machine is currently in. If the machine is current in transition between two states, this method will return the value `IN_TRANSITION`

  Returns:
    the current the state of the machine

### transition

    public void transition(int newState)

  The `transition()` method transitions the machine from the current state to a new state. This transition is only legal if the corresponding entry in the transition time matrix is non-negative. This method should only be called by the "controller" of the machine, and not by clients interested in probing the state of the device. If the transition time matrix for this transition is greater than zero, then this method will change the state to `IN_TRANSITION` and insert a transition event into the queue of the underlying clock for this device. That event will complete the transition. This method will not allow any transitions when the machine is already in transition.

  Parameters:
    `newState` - the new state to transition to
  Throws:
    `Avrora.InternalError` - if it is illegal to transition between the current state and the new state according to the transition time matrix; or if the machine is already in a transitional state

### getTransitionTime

    public int getTransitionTime(int beforeState,
                                 int afterState)

  The `getTransitionTime()` method retrieves the transition time between the two states specified from the transition time matrix.

  Parameters:
    `beforeState` - the state transitioning from
    `afterState` - the state transitioning to
  Returns:
    the number of clock cycles required to transition between these two states (0 or more) if the transition is legal; a negative number if the transition is not legal

### getStateName

    public java.lang.String getStateName(int state)

  The `getStateName()` method retrieves the name for the specified state.

  Parameters:
    `state` - the state to get the string name for
  Returns:
    a string representation of the specified state

### getCurrentStateName

    public java.lang.String getCurrentStateName()

  The `getCurrentStateName()` method retrieves the name for the current state.

  Returns:
    a string representation of the name of the current state

### getClock

    public Clock getClock()

  The `getClock()` method gets the underlying clock driving the device.

  Returns:
    the clock driving this device

### buildUniformTTM

    public static int[][] buildUniformTTM(int size,
                                          int tt)

  The `buildUniformTTM()` method builds a transition time matrix that is uniform; the machine can transition from any state to any other state with the given transition time.

  Parameters:
    `size` - the size of the transition time matrix
    `tt` - the transition time for each edge
  Returns:
    a new transition time matrix where each entry is the given transition time

### buildSparseTTM

    public static int[][] buildSparseTTM(int size,
                                         int tt)

  The `buildSparseTTM()` method builds a transition time matrix that is uniform but sparse; the machine can transition from any state to any other state with the given transition time. However, the internal representation shares the underlying integer arrays, avoiding large space overhead. Due to this storage sharing, DO NOT ATTEMPT TO UPDATE THE SPARSE TTM AFTER CONSTRUCTING IT UNLESS YOU UNDERSTAND THAT ALL ROWS WILL BE THE SAME.

  Parameters:
    `size` - the size of the matrix
    `tt` - the transition time for each edge.
  Returns:
    a new transition time matrix where each entry is the given transition time and the representation is space efficient.

### buildBimodalTTM

    public static int[][] buildBimodalTTM(int size,
                                          int ds,
                                          int[] tf,
                                          int[] tt)

  The `buildBimodalTTM()` method builds a transition time matrix that corresponds to a finite state machine with two modes. One special state is the "default" state. The machine can transition from the default state to any other state, and from any other state back to the default state, but not between any other two states.

  Parameters:
    `size` - the size of the transition time matrix
    `ds` - the default state
    `tf` - the transition times from each state back to the default state
    `tt` - the transition times from the default state to each other state
  Returns:
    a square transition time matrix that represents a bimodal state machine

### setCircularTTM

    public static int[][] setCircularTTM(int[][] ttm,
                                         int[] perm,
                                         int[] tt)

  The `setCircularTTM()` method builds a transition time matrix that represents a finite state machine arranged in a ring; each state can transition to one other state, wrapping around. For example, a finite state machine of consisting of states S1, S2, and S3 could have a cycle S1 -> S2 -> S3 -> S1.

  Parameters:
    `ttm` - the original transition time matrix
    `perm` - an array of integers representing the order of the state transitions in the ring
    `tt` - the transition time between the corresponding states in the ring
  Returns:
    a square

### newTTM

    public static int[][] newTTM(int size)

  The `newTTM()` method is a utility function for building a new transition time matrix. It will create a new transition time matrix (TTM) where each entry is `-1`, indicating that there are no legal state transitions.

  Parameters:
    `size` - the size of matrix, i.e. the number of rows, which is equal to the number of columns
  Returns:
    a square matrix of the given size where each entry is set to -1

### setDiagonal

    public static int[][] setDiagonal(int[][] ttm,
                                      int diag)

  The `setDiagonal()` method sets the diagonal of the given transition time matrix to the specified value. This is useful for finite state machines where transitions from one state to the same state is either impossible or a no-op.

  Parameters:
    `ttm` - the original transition time matrix
    `diag` - the value to set the diagonal entries to
  Returns:
    the original transition time matrix with the diagonal entries appropriately set

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD