Macho.cpp

// Macho - C++ Machine Objects
//
// The Machine Objects class library (in short Macho) allows the creation of
// state machines based on the "State" design pattern in straight C++. It
// extends the pattern with the option to create hierarchical state machines,
// making it possible to convert the popular UML statechart notation to working
// code in a straightforward way. Other features are entry and exit actions,
// state histories and state variables.
//
// Copyright (c) 2005 by Eduard Hiti (feedback to macho@ehiti.de)
//
// Version 0.9.7 (released 2007-12-1)
//
// See Macho.hpp for more information.

#include "Macho.hpp"
using namespace Macho;

////////////////////////////////////////////////////////////////////////////////
// Helper functions for tracing.
#ifdef MACHO_TRACE
#include <iostream>

void MACHO_TRC1(const char *msg) { std::cout << msg << std::endl; }
void MACHO_TRC2(const char *state, const char *msg) {
  std::cout << "State " << state << ": " << msg << std::endl;
}
void MACHO_TRC3(const char *state, const char *msg1, const char *msg2) {
  std::cout << "State " << state << ": " << msg1 << " " << msg2 << std::endl;
}
#else
#define MACHO_TRC1(MSG)
#define MACHO_TRC2(STATE, MSG)
#define MACHO_TRC3(STATE, MSG1, MSG2)
#endif

////////////////////////////////////////////////////////////////////////////////
// Box for states which don't declare own Box class.
_EmptyBox _EmptyBox::theEmptyBox;

////////////////////////////////////////////////////////////////////////////////
// Helper functions for box creation
template <> void *Macho::_createBox<_EmptyBox>(void *&place) {
  return &_EmptyBox::theEmptyBox;
}

template <> void Macho::_deleteBox<_EmptyBox>(void *&box, void *&place) {}

#ifdef MACHO_SNAPSHOTS
template <> void *Macho::_cloneBox<_EmptyBox>(void *other) {
  return &_EmptyBox::theEmptyBox;
}
#endif

////////////////////////////////////////////////////////////////////////////////
// Implementation for Alias
void Alias::setState(_MachineBase &machine) const {
  machine.setPendingState(key()->instanceGenerator(machine),
                          myInitializer->clone());
}

////////////////////////////////////////////////////////////////////////////////
// Implementation for StateSpecification
_StateInstance &_StateSpecification::_getInstance(_MachineBase &machine) {
  // Look first in machine for existing StateInstance.
  _StateInstance *&instance = machine.getInstance(0);
  if (!instance)
    instance = new _RootInstance(machine, 0);

  return *instance;
}

void _StateSpecification::_shutdown() { _myStateInstance.machine().shutdown(); }

void _StateSpecification::_restore(_StateInstance &current) {
  _myStateInstance.machine().myCurrentState = &current;
}

void _StateSpecification::setState(const Alias &state) {
  state.setState(_myStateInstance.machine());
}

#ifdef MACHO_SNAPSHOTS
void _StateSpecification::setState(_StateInstance &current) {
  _myStateInstance.machine().setPendingState(current, &_theDefaultInitializer);
}
#endif

////////////////////////////////////////////////////////////////////////////////
// StateInstance implementation
_StateInstance::_StateInstance(_MachineBase &machine, _StateInstance *parent)
    : myMachine(machine), mySpecification(0), myHistory(0), myParent(parent),
      myBox(0), myBoxPlace(0) {}

_StateInstance::~_StateInstance() {
  if (myBoxPlace)
    ::operator delete(myBoxPlace);

  delete mySpecification;
}

void _StateInstance::entry(_StateInstance &previous, bool first) {
  // Only Root has no parent
  if (!myParent)
    return;

  // first entry or previous state is not substate -> perform entry
  if (first || !previous.isChild(*this)) {
    myParent->entry(previous, false);

    createBox();

    MACHO_TRC2(name(), "Entry");
    mySpecification->entry();
  }
}

void _StateInstance::exit(_StateInstance &next) {
  // Only Root has no parent
  if (!myParent)
    return;

  // self transition or next state is not substate -> perform exit
  if (this == &next || !next.isChild(*this)) {
    MACHO_TRC2(name(), "Exit");
    mySpecification->exit();

    // EmptyBox should be most common box, so optimize for this case.
    if (myBox != &_EmptyBox::theEmptyBox)
      mySpecification->_deleteBox(*this);

    myParent->exit(next);
  }
}

void _StateInstance::init(bool history) {
  if (history && myHistory) {
    MACHO_TRC3(name(), "History transition to", myHistory->name());
    myMachine.setPendingState(*myHistory, &_theDefaultInitializer);
  } else {
    MACHO_TRC2(name(), "Init");
    mySpecification->init();
  }

  myHistory = 0;
}

#ifdef MACHO_SNAPSHOTS
void _StateInstance::copy(_StateInstance &original) {
  if (original.myHistory) {
    _StateInstance *history = myMachine.getInstance(original.myHistory->id());
    assert(history);
    setHistory(history);
  }

  if (original.myBox)
    cloneBox(original.myBox);
}

_StateInstance *_StateInstance::clone(_MachineBase &newMachine) {
  assert(!newMachine.getInstance(id()));

  _StateInstance *parent = 0;
  if (myParent)
    // Tell other machine to clone parent first.
    parent = newMachine.createClone(myParent->id(), myParent);

  _StateInstance *clone = create(newMachine, parent);
  return clone;
}
#endif

////////////////////////////////////////////////////////////////////////////////
// Base class for Machine objects.
_MachineBase::_MachineBase()
    : myCurrentState(0), myPendingState(0), myPendingInit(0),
      myPendingBox(0) // Deprecated!
      ,
      myPendingEvent(0) {}

_MachineBase::~_MachineBase() {
  assert(!myPendingInit);

  delete[] myInstances;
  delete myPendingEvent;
}

Alias _MachineBase::currentState() const {
  return Alias(myCurrentState->key());
}

void _MachineBase::setState(_StateInstance &instance, _Initializer *init) {
  setPendingState(instance, init);
  rattleOn();
}

void _MachineBase::setState(const Alias &state) {
  state.setState(*this);
  rattleOn();
}

void _MachineBase::start(_StateInstance &instance) {
  MACHO_TRC1("Starting Machine");

  // Start with Root state
  myCurrentState = &_StateSpecification::_getInstance(*this);
  // Then go to state
  setState(instance, &_theDefaultInitializer);
}

void _MachineBase::start(const Alias &state) {
  MACHO_TRC1("Starting Machine");

  // Start with Root state
  myCurrentState = &_StateSpecification::_getInstance(*this);
  // Then go to state
  setState(state);
}

void _MachineBase::shutdown() {
  assert(!myPendingState);

  MACHO_TRC1("Shutting down Machine");

  // Performs exit actions by going to Root (=StateSpecification) state.
  setState(_StateSpecification::_getInstance(*this), &_theDefaultInitializer);

  myCurrentState = 0;
}

void _MachineBase::allocate(unsigned int count) {
  myInstances = new _StateInstance *[count];
  for (unsigned int i = 0; i < count; ++i)
    myInstances[i] = 0;
}

void _MachineBase::free(unsigned int count) {
  // Free from end of list, so that child states are freed first
  unsigned int i = count;
  while (i > 0) {
    --i;
    delete myInstances[i];
    myInstances[i] = 0;
  }
}

// Clear history of state and children.
void _MachineBase::clearHistoryDeep(unsigned int count,
                                    const _StateInstance &instance) {
  for (unsigned int i = 0; i < count; ++i) {
    _StateInstance *s = myInstances[i];
    if (s && s->isChild(instance))
      s->setHistory(0);
  }
}

#ifdef MACHO_SNAPSHOTS
void _MachineBase::copy(_StateInstance **others, unsigned int count) {
  // Create StateInstance objects
  for (ID i = 0; i < count; ++i)
    createClone(i, others[i]);

  // Copy StateInstance object's state
  for (ID i = 0; i < count; ++i) {
    _StateInstance *state = myInstances[i];
    if (state) {
      assert(others[i]);
      state->copy(*others[i]);
    }
  }
}

_StateInstance *_MachineBase::createClone(ID id, _StateInstance *original) {
  _StateInstance *&clone = getInstance(id);

  // Object already created?
  if (!clone && original)
    clone = original->clone(*this);

  return clone;
}
#endif

// Performs a pending state transition.
void _MachineBase::rattleOn() {
  assert(myCurrentState);

  while (myPendingState || myPendingEvent) {

    // Loop here because init actions might change state again.
    while (myPendingState) {
      MACHO_TRC3(myCurrentState->name(), "Transition to",
                 myPendingState->name());

#ifndef NDEBUG
      // Entry/Exit actions may not dispatch events: set dummy event.
      if (!myPendingEvent)
        myPendingEvent = (_IEventBase *)&myPendingEvent;
#endif

      // Perform exit actions (which exactly depends on new state).
      myCurrentState->exit(*myPendingState);

      // Store history information for previous state now.
      // Previous state will be used for deep history.
      myCurrentState->setHistorySuper(*myCurrentState);

      _StateInstance *previous = myCurrentState;
      myCurrentState = myPendingState;

      // Deprecated!
      if (myPendingBox) {
        myCurrentState->setBox(myPendingBox);
        myPendingBox = 0;
      }

      // Perform entry actions on next state's parents (which exactly depends on
      // previous state).
      myCurrentState->entry(*previous);

      // State transition complete.
      // Clear 'pending' information just now so that setState would assert in
      // exits and entries, but not in init.
      myPendingState = 0;

      // Use initializer to call proper "init" action.
      _Initializer *init = myPendingInit;
      myPendingInit = 0;

      init->execute(*myCurrentState);
      init->destroy();

      assert("Init may only transition to proper substates" &&
             (!myPendingState || (myPendingState->isChild(*myCurrentState) &&
                                  (myCurrentState != myPendingState))));

#ifndef NDEBUG
      // Clear dummy event if need be
      if (myPendingEvent == (_IEventBase *)&myPendingEvent)
        myPendingEvent = 0;
#endif
    } // while (myPendingState)

    if (myPendingEvent) {
      _IEventBase *event = myPendingEvent;
      myPendingEvent = 0;
      event->dispatch(*myCurrentState);
      delete event;
    }

  } // while (myPendingState || myPendingEvent)

} // rattleOn

////////////////////////////////////////////////////////////////////////////////
// Implementation for _AdaptingInitializer

Key _AdaptingInitializer::adapt(Key key) {
  ID id = static_cast<_KeyData *>(key)->id;
  const _StateInstance *instance = myMachine.getInstance(id);
  _StateInstance *history = 0;

  if (instance)
    history = instance->history();

  return history ? history->key() : key;
}

////////////////////////////////////////////////////////////////////////////////
// Singleton initializers.
_DefaultInitializer _theDefaultInitializer;
_HistoryInitializer _theHistoryInitializer;