Using OSInet FSM

Code using the FSM revolves around the f_transitions table. This is an array of states and their associated events and transitions.

Each entry in f_transitions represents a state as an array of events.

Each entry in a f_transition state represents an event as an array of accepted results from the method handling the event, the resulting next action as a fsm_result.

The fsm_state field contains the name of the state as a string, and the fsm_action field contains an event (as a string) to fire after setting the state. If fsm_state is NULL, no state change occurs. If fsm_action is NULL, no event is fired.

Syntactic sugar: The action can also be a simple string, in which case it is the name of the next state and no action is taken. Version 1.1 only understood that syntax.

Implementing the FSM once the table is defined means implementing each event (foo) as an event-handling function called f_foo. The return values of this function must be the ones defined in the f_transitions entry for that state. Returning a non accepted value throws an exception.

A special built-in event is fsm::IDLE_EVENT (method f_idle), which always returns true, and can be used to direct the fsm to navigate between preferred states when nothing specific happens by causing events to be generated as above.

This event can be turned off by setting the FSM “$idle” property to FALSE. In that case, submitted fsm::IDLE_EVENT events are silently discarded.

Syntactic sugar: the idle() method is a shorthand for apply_events(fsm::IDLE_EVENT).

The OSInet FSM has three event processing modes, controlled by the {get|set}_event_mode methods:

• fsm::EVENT_NORMAL : receives events, processes them, and fires exit events if applicable. This is the default mode.
  • Switching from fsm::EVENT_QUEUE to fsm::EVENT_NORMAL enables the FSM to read the event queue and work on it. This can be useful when the program must first do something else, but should not lose track of what is happening.
• fsm::EVENT_QUEUE : receives events, but queues them instead of processing them.
• fsm::EVENT_SINK : receives events but throws them away.
  • Switching from fsm::EVENT_QUEUE to fsm::EVENT_SINK empties the event queue accumulated while under fsm::MODE_QUEUE

Firing of post-event actions is enabled by default, but can be disabled by setting the $allow_actions property to false.

In that case, applications can still decide to fire the event themselves by reading the fsm_action field in the fsm_result returns by fsm::apply_event().

For a very basic FSM going just from initial to final randomly, building the table and transitions can look like:

class foo extends fsm
  {
  function __construct()
    {
    $this->f_transitions = array
      (
      'initial' => array
        (
        'event' => array
          (
          TRUE     => 'final',
          FALSE    => 'initial',
          ),
        'idle'  => array
          (
          TRUE     => new fsm_result(NULL, event),
          ),
        ),
      'final'  => array(),
      );
    }
  function f_event()
    {
    return rand(0, 1) > 0 ;
    }
  }

Application code not involved in the FSM operation can use the FSM apply_event method($event_name) to submit an event to the FSM. Only allowed events for the given state the FSM is in are allowed: submitting other events throws an exception.