state_machine.h

Go to the documentation of this file.

#ifndef STATE_MACHINE_CLASS
#define STATE_MACHINE_CLASS

/*****************************************************************************\
*                                                                             *
*  Name   : state_machine                                                     *
*  Author : Chris Koeritz                                                     *
*                                                                             *
*******************************************************************************
* Copyright (c) 1992-$now By Author.  This program is free software; you can  *
* redistribute it and/or modify it under the terms of the GNU General Public  *
* License as published by the Free Software Foundation; either version 2 of   *
* the License or (at your option) any later version.  This is online at:      *
*     http://www.fsf.org/copyleft/gpl.html                                    *
* Please send any updates to: fred@gruntose.com                               *
\*****************************************************************************/

#include <basis/contracts.h>
#include <timely/time_stamp.h>

namespace processes {

class state_machine_override_array;
class state_machine_state_array;


class state_machine : public virtual basis::root_object
{
public:
  state_machine();

  state_machine(const state_machine &to_copy);

  virtual ~state_machine();

  DEFINE_CLASS_NAME("state_machine");

  state_machine &operator =(const state_machine &to_copy);

  virtual int update();

  int current() const { return _current; }

  int last() const { return _last; }

  int trigger() const { return _trig; }

  enum transition_types { SIMPLE, RANGE, TIMED };

  bool simple() const { return _type == SIMPLE; }
  bool ranged() const { return _type == RANGE; }
  bool timed() const { return _type == TIMED; }

  void set_state(int new_current, int new_last, int trigger,
          transition_types type);

  timely::time_stamp start() const;

  void set_name(const basis::astring &name);

  basis::astring get_name() const;

  void override_timing(int current, int next, int duration);

  int duration_override(int current, int next) const;

private:
  friend class transition_map;
  int _current;  
  int _last;  
  int _trig;  
  transition_types _type;  
  timely::time_stamp *_start;  
  basis::astring *_name;  
  state_machine_override_array *_overrides;  

  int duration_index(int current, int next) const;

};



class transition_map : public virtual basis::root_object
{
public:
  transition_map();
  virtual ~transition_map();

  // informational functions...

  DEFINE_CLASS_NAME("transition_map");

  bool valid() const { return _valid; }

  int states() const;

  // validation functions...

  enum outcomes {
    OKAY = basis::common::OKAY,
    DEFINE_OUTCOME(BAD_START, -49, "The start state has not been properly "
        "specified"),
    DEFINE_OUTCOME(OVERLAPPING_RANGES, -50, "The ranges overlap for two "
        "transitions from a state"),
    DEFINE_OUTCOME(UNREACHABLE, -51, "There is an unreachable state in the map")
  };
  basis::outcome validate(int &examine);

  void reconfigure();

  // configuration functions...

  // NOTE: all of the functions below will fail if the transition_map has
  // already been validated previously and reconfigure() has not been called.

  // NOTE: a zero value for a state means that it is uninitialized.  thus, zero
  // is never allowed as a value for a state or a transition endpoint.  zero is
  // grudgingly allowed as a trigger value, although that interferes with the
  // state_machine object's update() method.

  bool add_state(int state_number);

  bool set_start(int starting_state);

  bool add_simple_transition(int current, int next);

  bool add_range_transition(int current, int next, int low, int high);

  bool add_timed_transition(int current, int next, int duration);

  // transition functions...

  // NOTE: all of these actions will fail if the transition_map has not been
  // validated yet.

  bool make_transition(state_machine &m, int next);

  bool pulse(state_machine &m, int trigger);

  bool time_slice(state_machine &m);
    // allows the transition_map to process any timed transitions that may be
    // required for the state_machine "m".  the return value is true if such
    // a transition was found.

  bool reset(state_machine &m);
    // resets the state_machine to the starting state in the transition_map.
    // the update function is NOT invoked at the time of the reset.  true is
    // returned if the reset was successful; it would fail if the transition
    // map has not been validated yet.

private:
  bool _valid;  
  int _start_state;  
  state_machine_state_array *_state_list;

  bool check_overlapping(int &examine);

  bool check_reachability(int &examine);

  int state_index(int state_id) const;

  int transition_index(int state_index, int next, int &start);

  bool check_states();

  // disallowed functions for now:
  transition_map(const transition_map &);
  transition_map &operator =(const transition_map &);
};

} //namespace.

#endif