synopsis.
this object contains a transition table - an N X M matrix (N is the rows, M is the columns) that defines what state can be reached from any given state. M represents the maximum number of exit choices. It can be set to less than N, strictly for space efficiency considerations. For example, if there are 1,000 states, and each state can transition to at most 3 other states, one need allocate only a 3,000-element array, instead of one with 1 million elements.

member functions (primary)

state_o()
SIGNATURE: state_o
SYNOPSIS: creates a a new state object, internal table is empty (0-length / degenerate)
 

state_o(<args>)
SIGNATURE: state_o (int m, int n)
SYNOPSIS: creates a a new state object, containing an internal table of size m x n
 

register_states()
SIGNATURE: int register_states (state_t *, int (*)(), int)
SYNOPSIS: registers a set of functions (which could be null), allowing usage of the "run ()" command.
RETURNS:
0: success
-1: memory allocation failure
 

register_transition()
SIGNATURE: int register_transition (state_t i, state_t next)
SYNOPSIS: sets a single transition from one state to another
PARAMETERS

i - the index into the matrix. treat the matrix as a single-dimensional array of size m x n.

 

register_transitions()
SIGNATURE: int register_transitions (state_t, state_t *, int)
SYNOPSIS: define valid state-state transitions
RETURNS: 0
 

register_states()
SIGNATURE: int state_o::register_states (state_t *mylist, int my_n)
SYNOPSIS: this provides a set of keys for each index element of the transition table.
RETURNS:
0: success
-1: memory allocation failure
TRAITS: this function is unwieldy
 

set_initial()
SIGNATURE: void set_initial (state_t)
SYNOPSIS: set the initial state
 

run()
SIGNATURE: int run ()
SYNOPSIS: Executes the callback functions, provided by register_states() as a closed-loop system.
 

reset()
SIGNATURE: int reset ()
SYNOPSIS: reset the object to empty (wipes out all internal data)
 

usage.

1. derive a class from the state object, in order to define the virtual function "get_nextstate()".


2. make the object. you should know how many maximum states and transitions are involved.


3. register all states (by calling "register_states()").


4. provide a list of exit values for each state; use "register_transition()" or "register_transitions()".


5. set the initial state ("set_initial()").


6. build a dispatcher-like function that gets the next state; it decides what to do given the current state.

note.
A possible, but not yet implemented, extension to this class (maybe this will be made as a derived class) is to register callback-style functions that could get called by the state object directly upon receiving a state change. Then the application need only call "run()", and off it goes.

bugs.
This class is very old (dating to the early 90's), somewhat hard to use, and of questionable value. state_o is currently categorized as "unsupported". whether this object will be improved, reworked, or discarded will depend on the demand for it in the future.

history:   ??? 06/21/1996: state_o [grudgingly] re-installed to the z dir