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