topsStateMachine Class Reference

Overview

A state machine for controlling flow through predefined states.

topsStateMachine may contain arbitrary states to be traversed when it run()s. Each state may invoke functions and transition to other states with specified timing. State traversal may be deterministic, or may be conditional and branching based on classifications or input functions.

Inheritance diagram for topsStateMachine:

Properties and Events
Property	allStates = struct([])
	struct array of data for each state More...
Property	startState = []
	optional argument to indicate a start state (other than the first one)... More...
Property	transitionFevalable = {}
	optional fevalable cell array to invoke during state transitions More...
Property	startTime = []
	any function that returns the current time as a number jig moved to topsFoundation clockFunction = @topsClock; More...
Property	finishTime = []
	the time when state traversal ended
Property	finishState = struct([])
	struct of information about the last state encountered during traversal. More...
Property	currentEntryTime = []
	time when the current state was entered
Property	currentTimeoutTime = []
	time when the current state will reach its timeout
	sharedEntry
	struct array of shared fevalables and names
	sharedExit
	struct array of shared fevalables and names
Property	debugFlag = false
	Debug flag – for now just prints out current state name as it is entered.
Properties and Events inherited from topsConcurrent
Property	runBrieflyString = 'runBriefly'
	string used for topsDataLog entry just before runBriefly()
Properties and Events inherited from topsRunnable
Property	startFevalable = {}
	optional fevalable cell array to invoke just before running
Property	finishFevalable = {}
	optional fevalable cell array to invoke just after running
Property	isRunning = false
	true or false, whether this object is currently busy running
Property	caller
	topsRunnable that invoked run() on this object, or empty
Property	startString = 'start'
	string used for topsDataLog entry just before run()
Property	finishString = 'finish'
	string used for topsDataLog entry just after run()
Properties and Events inherited from topsFoundation
Property	name = ''
	a string name to indentify the object
Property	clockFunction =@topsClock
	clock function, to standardize

Protected Properties
Property	currentIndex = []
	allStates array index for the current state
Property	currentInput = {}
	copy of the current state's input fevalable
Property	currentClassification = []
	copy of the current state's classification
Property	stateNameToIndex
	containers.Map of state name -> allStates array index.
Property	transitionString = 'transition'
	string used for topsDataLog entry for transitionFevalable
Property	entryString = 'enter'
	string used for topsDataLog entry during state entry
Property	exitString = 'exit'
	string used for topsDataLog entry during state exit
	stateFields
	field names of allStates struct array, defining state behaviors
Property	stateDefaults = {'', '', 0, {}, {}, {}, []}
	default values of allStates struct array fields

Methods
self	topsStateMachine (varargin)
	Constuct with name optional. More...
fig	gui (self)
	Open a GUI to view object details. More...
indexes	addMultipleStates (self, statesInfo)
	Add multiple states to the state machine. More...
index	addState (self, stateInfo)
	Add a new state to the state machine. More...
index	editStateByName (self, stateName, varargin)
	Edit fields of an existing state. More...
	addSharedFevalableWithName (self, fevalable, name, when)
	Add a function to be invoked during every state. More...
isState index	isStateName (self, stateName)
	Check whether a string is the name of a state.
stateInfo index	getStateInfoByName (self, stateName)
	Get a struct of info about a state with a given name.
	start (self)
	Prepare for state traversal. More...
	finish (self)
	Finish doing state traversal. More...
	runBriefly (self)
	Do a little flow control within the state list. More...
Methods inherited from topsConcurrent
self	topsConcurrent (varargin)
	Constuct with name optional. More...
	run (self, duration)
	Do flow control. More...
	runBriefly (self)
	Do a little flow control and return as soon as possible. More...
Methods inherited from topsRunnable
self	topsRunnable (varargin)
	Constuct with name optional. More...
	run (self)
	Do flow control. More...
g	gui (self)
	Show heirarchy of topsRunnable[Composite] objects.
	start (self)
	Log action and prepare to do flow control. More...
	finish (self)
	Log, action and finish doing flow control. More...
	logAction (self, actionName, actionData)
	Log an event of interest with topsDataLog. More...
	logFeval (self, fevalName, fevalable)
	Log a function call with topsDataLog. More...
Methods inherited from topsFoundation
self	topsFoundation (name)
	Constuct with name optional. More...
fig	gui (self)
	Open a GUI to view object details. More...
p	guiPanel (self, varargin)
	Make a topsDetailPanel with details about this object. More...

Protected Methods
	enterStateAtIndex (self, index)
	reset all the current* properties for the given state
	exitCurrentState (self)
	clear current* properties but leave currentIndex so it's checkable
	transitionToStateWithName (self, nextName)
	Invoke transitionFevalable before exiting previous state.
	logStateSharedFeval (self, state, shared)
	Add an entry to topsDataLog for an fevalable shared among states.

Static Methods
static time_	sampleTime (args)
	function time_ = sampleTime(args) More...
Static Methods inherited from topsFoundation
static c index	cellAdd (c, item, index)
	Add an item to a cell array. More...
static selector	cellContains (c, item)
	Does a cell array conatin an item? More...
static c	cellRemoveItem (c, item)
	Remove an item from a cell array. More...
static c	cellRemoveElement (c, index)
	Remove indexed elements from a cell array. More...
static index selector	findStructName (s, name)
	Where is the given name in the given struct array? More...

Constructor

topsStateMachine()

self topsStateMachine

(

varargin

)

Constuct with name optional.

Parameters

name	optional name for this object

If name is provided, assigns name to this object.

Methods

gui()

fig gui

(

self

)

Open a GUI to view object details.

Opens a new GUI with components suitable for viewing objects of this class. Returns a topsFigure object which contains the GUI.

addMultipleStates()

indexes addMultipleStates	(	self	,
		statesInfo
	)

Add multiple states to the state machine.

Parameters

statesInfo

a cell array with information defining multiple states.

statesInfo should resemble a table, with a row for each new state a column for each state field.

The first row of statesInfo shoud contain field names that correspond to the fields of allStates. See addState() for field descriptions. Only the name field is mandatory. Fields may appear in any order.

Each additional row of statesInfo shoud contain values aligned with the field names in the first row. A new state will be added using each row of values. Default values will be used where fields are omitted. The name field is mandatory.

The values in the name column should be unique with respect to each other and any existing states. When names collide, new states will replace existing states.

Returns an array of indexes into allStates where the new states were appended or inserted.

addState()

index addState	(	self	,
		stateInfo
	)

Add a new state to the state machine.

Parameters

stateInfo

a struct with information defining a state.

stateInfo should have the same fields as allStates:

• name unique name to identify the state
• timeout time that may elapse before transitioning to the next state, in units of clockFunction. If cell array, calls fevalable to get a random pick.
• next the name of the state to transition to once timeout has elapsed
• entry fevalable cell array invoked when entering the state
• input fevalable cell array invoked after entering the state, during each call to runBriefly(). If the returned value is the name of a state, transitions to that state immediately.
• exit fevalable cell array invokes when exiting the state
• classification topsClassification object to query after entering the state, during each call to runBriefly(). If the returned output is the name of a state, transitions to that state immediately.

Each state must have a unique name. Any existing state with the same name will be replaced.

Other fields of stateInfo may be omitted, in which case default values will be used.

Fields of stateInfo may correspond to one of the names in sharedEntry or sharedExit. Values in these fields will be passed as state-specific arguments to the shared fevalable.

Returns the index into allStates where the new state was appended or inserted.

editStateByName()

index editStateByName	(	self	,
		stateName	,
		varargin
	)

Edit fields of an existing state.

Parameters

stateName	string name of an existing state in allStates
varargin	flexible number of field-value paris to edit the fields of the stateName state.

Assigns the given values to the given fields of the existing state that has the name stateName. varargin represents a flexible number of trailing arguments passed to editStateByName(). The first argument in each pair should be one of the field names of the allStates struct, which include the default state fields described for addField() and the names of any sharedEntry or sharedExit fevalables. The second argument in each pair should be a value to assign to the named field.

Editing the name field of a state might cause the state machine to misbehave.

Returns the index into allStates of the stateName state. If stateName is not the name of an existing state, returns [].

addSharedFevalableWithName()

addSharedFevalableWithName	(	self	,
		fevalable	,
		name	,
		when
	)

Add a function to be invoked during every state.

Parameters

fevalable	fevalable cell array to invoke for every state
name	string name to give to fcn
when	the string 'entry' or 'exit' specifying when to invoke fevalable. For 'entry', fevalable will be invoked just after each state's own entry. For 'exit', fevalable will be invoked just before each state's own exit.

Adds fevalable to the state machine's sharedEntry or sharedExit fevalables. These functions are called for every state, in addition to each state's own entry and exit.

Each state may specify additional arguments to pass to fevalable. These may be specified like other state data, using name as the state field. See addState() and addMultipleStates() for details on specifying state data.

name must be unique with respect to other sharedEntry or sharedExit fevalables. If name matches an existing sharedEntry or sharedExit, fevalable will replace the existing function.

start()

start

(

self

)

Prepare for state traversal.

topsStateMachine extends the start() method of topsConcurrent to record the startTime and enter the first state in allStates.

finish()

finish

(

self

)

Finish doing state traversal.

topsStateMachine extends the finish() method of topsConcurrent to record the finishState and finishTime.

runBriefly()

runBriefly

(

self

)

Do a little flow control within the state list.

topsStateMachine extends the runBriefly() method of topsConcurrent to do state traversal. It checks the input fevalable and classification for the current state. If input or classification returns a state name, transitions to that state immediately. If not, checks whether the current state's timeout has expired. If timeout has expired, transitions to the next state immediately. If there is no next state, traversal ends.

sampleTime()

static time_ sampleTime ( args  )

static

function time_ = sampleTime(args)

State Machine utility to sample from different distributions, typically to set the timeout field in a topsStateMachine state

Properties and Events

allStates

Property allStates = struct([])

struct array of data for each state

Each element of allStates represents a single state. See addState() for details about the struct fields and state properties.

startState

Property startState = []

optional argument to indicate a start state (other than the first one)...

string name or index

transitionFevalable

Property transitionFevalable = {}

optional fevalable cell array to invoke during state transitions

The function should expect as the first argument a 1x2 struct array of information about the previous state and the next state, with elements in that order. Any other arguments in the cell array will be passed to the function starting at the second place. See addState() for details of the struct state information.

startTime

Property startTime = []

any function that returns the current time as a number jig moved to topsFoundation clockFunction = @topsClock;

the time when state traversal began

finishState

Property finishState = struct([])

struct of information about the last state encountered during traversal.

See addState() for details of the struct state information.

---

The documentation for this class was generated from the following file:

• topsStateMachine.m