state_controller.h

Go to the documentation of this file.

// State Controller Library
// Author: Philipp Allgeuer <pallgeuer@ais.uni-bonn.de>

// Ensure header is only included once
#ifndef STATE_CONTROLLER_H
#define STATE_CONTROLLER_H

// Includes
#include <boost/shared_ptr.hpp>
#include <boost/make_shared.hpp>
#include <boost/type_traits/is_base_of.hpp>
#include <boost/static_assert.hpp>
#include <cstddef> // For std::size_t
#include <vector>  // For std::vector
#include <string> // For std::string

// Macro to create a new state instance
// Use like this: StatePtr s = NewStateInstance<MyState>(arg1, arg2, ...);
// Note: MyState should be a class derived either directly or indirectly from the State class.
//       arg1, arg2, ... is the parameter list to pass to the MyState constructor. arg1 will
//       generally be 'this' (when used from inside a state controller) or 'sc' (when used from
//       within another state instance), as it is generally used by the constructor to pass a
//       pointer to the owning state controller object.
#define NewStateInstance boost::make_shared

namespace statecontroller
{
    // Class declarations
    class State;
    template <class SCClass> class GenState;
    class StateQueue;
    class StateController;

    // Enumerations
    enum SCReturnID       
    {                     //  Programming hint: If foo() returns a ret_t then if(foo()) {...} executes when the return was *not* SCR_OK
        SCR_OK = 0,       
        SCR_TERMINATED,   
        SCR_NULL_STATE,   
        SCR_NOT_MY_STATE, 
        SCR_BAD_CALLBACK  
    };

    // Type definitions
    typedef boost::shared_ptr<State> StatePtr;            
    typedef boost::shared_ptr<State const> StateConstPtr; 
    typedef std::size_t index_t;                          
    typedef unsigned int cycle_t;                         
    typedef bool action_t;                                
    typedef int ret_t;                                    

    // Constants
    const StatePtr nullStatePtr = boost::shared_ptr<State>(); 
    const index_t nullIndex = (index_t) -1;                   
    const action_t HOLD_THIS_STATE = true;                    
    const action_t PROCEED_NEXT_STATE = false;                

    class State
    {
    public:
        // Constructors
        State(int id, const std::string& name, const std::string& scname)
            : id(id)
            , name(name)
            , scname(scname)
            , m_wasActivated(false)
            , m_wasExecuted(false)
            , m_wasDeactivated(false)
            , m_firstExecCycle(0)
        {}                                      
        virtual ~State() { callDeactivate(0); } 

        // State properties
        const int id;             
        const std::string name;   
        const std::string scname; 

        // Helper functions
        static bool isNull(StateConstPtr state) { return !((bool) state); } 

    protected:
        // Friend classes
        friend class StateController;

        // Protected state properties
        virtual StateController* scref() const = 0;               

        // State callbacks
        virtual void activate(cycle_t cyc) {}                     
        virtual action_t execute(cycle_t cyc) = 0;                
        virtual void deactivate(cycle_t cyc, bool wasExecuted) {} 

        // Get functions
        inline StateQueue* Queue() const;                                              
        cycle_t firstExecCycle() const          { return m_firstExecCycle; }           
        cycle_t execCycleNum(cycle_t cyc) const { return cyc - m_firstExecCycle + 1; } 

    private:
        // State callback wrappers
        void callActivate(cycle_t cyc);    
        action_t callExecute(cycle_t cyc); 
        void callDeactivate(cycle_t cyc);  

        // Callback execution flags
        bool m_wasActivated;
        bool m_wasExecuted;
        bool m_wasDeactivated;

        // Cycle of first call to execute()
        cycle_t m_firstExecCycle; // Equals zero before the first call to execute()
    };

    template <class SCClass>
    class GenState : public State
    {
    public:
        // Ensure SCClass is a derived class of StateController
        typedef boost::is_base_of<StateController, SCClass> Assert;
        BOOST_STATIC_ASSERT_MSG(Assert::value, "SCClass template parameter must be a derived class of statecontroller::StateController");

        // Constructors
        GenState(SCClass* sc, int id, const std::string& name) : State(id, name, sc->name), sc(sc) {} 
        virtual ~GenState() {} 

    protected:
        // Protected state properties
        virtual StateController* scref() const { return static_cast<StateController*>(sc); }

        // State controller pointer
        SCClass* const sc; 
    };

    class StateQueue
    {
    public:
        // Constants
        static const index_t DEF_QUEUE_CAPACITY = 16; 

        // Constructors
        StateQueue()          { reset(); }      
        virtual ~StateQueue() { clear_hard(); } 

        // Reset function
        void reset(); 

        //
        // Queue manipulation functions
        //

        // Clearing
        void clear()                                   { QueueVec.resize(0); }                                                            
        void clear_hard()                              { QueueVec.clear(); }                                                              
        void reserveCapacity(index_t n)                { if(n <= QueueVec.max_size()) QueueVec.reserve(n); }                              

        // Get and set
        StatePtr get(index_t ind) const                { return (ind < QueueVec.size() ? QueueVec.at(ind) : nullStatePtr); }              
        void     set(index_t ind, StatePtr state)      { if(ind < QueueVec.size()) QueueVec.at(ind) = state; }                            

        // Element insertion and removal
        void     setNextState(StatePtr state)          { QueueVec.assign(1,state); }                                                      
        StatePtr getNextState() const                  { return (QueueVec.size() > 0 ? QueueVec.at(0) : nullStatePtr); }                  
        void append (StatePtr state)                   { QueueVec.push_back(state); }                                                     
        void prepend(StatePtr state)                   { QueueVec.insert(QueueVec.begin(), state); }                                      
        void insertBefore(index_t ind, StatePtr state) { if(ind <= QueueVec.size()) QueueVec.insert(QueueVec.begin() + ind, state); }     
        void insertAfter (index_t ind, StatePtr state) { if(ind <  QueueVec.size()) QueueVec.insert(QueueVec.begin() + ind + 1, state); } 
        void remove(index_t ind)                       { if(ind <  QueueVec.size()) QueueVec.erase (QueueVec.begin() + ind); }            

        // Queue information
        index_t length() const                         { return QueueVec.size(); }                                                        
        bool    isEmpty() const                        { return QueueVec.empty(); }                                                       
        bool    validIndex(index_t ind) const          { return ind < QueueVec.size(); }                                                  

        // Head and tail items
        index_t headIndex() const                      { return (QueueVec.size() > 0 ? 0 : nullIndex); }                                  
        index_t tailIndex() const                      { return (QueueVec.size() > 0 ? QueueVec.size()-1 : nullIndex); }                  
        StatePtr headItem() const                      { return (QueueVec.size() > 0 ? QueueVec.at(0) : nullStatePtr); }                  
        StatePtr tailItem() const                      { return (QueueVec.size() > 0 ? QueueVec.at(QueueVec.size()-1) : nullStatePtr); }  

        // Queue advance function (pops and returns the state sitting at the head of the queue)
        StatePtr advance();                                                                                                               

        // Queue state and index search functions
        bool containsID(int id) const                  { return (indexOf(id) != nullIndex); }                                             
        bool containsState(StatePtr state) const       { return (indexOf(state) != nullIndex); }                                          

        // Queue state and index retrieval functions
        StatePtr stateOf(int id, index_t start = 0) const;                                                                                
        index_t  indexOf(int id, index_t start = 0) const;                                                                                
        index_t  indexOf(StatePtr state, index_t start = 0) const;                                                                        

    private:
        // Internal queue vector object
        std::vector<StatePtr> QueueVec; 
    };

    class StateController
    {
    public:
        //
        // Constructors
        //

        // Constructors and destructors
        explicit StateController(const std::string& name) : name(name), m_inCallback(false) { reset(); } 
        virtual ~StateController() { freeResources(); } 

        // State controller properties
        const std::string name; 

        //
        // Public functions (permitted in callbacks)
        //

        // State control functions
        action_t goToState(StatePtr state); 
        action_t terminate();               

        // Helper functions
        bool belongsToMe(StateConstPtr state) const { return (state->scref() == this); }   
        bool isActive() const                       { return !State::isNull(m_curState); } 
        cycle_t getCycle() const                    { return m_cycle; }                    
        StateConstPtr getCurState() const           { return m_curState; }                 

        //
        // Public functions (callback-protected)
        //

        // Initialisation and state change functions
        ret_t init(StatePtr state);       
        ret_t forceState(StatePtr state); 

        // Step functions
        ret_t step();                     
        ret_t loop();                     

    protected:
        //
        // Callbacks
        //

        // Step callbacks
        virtual bool preStepCallback() { return false; }           
        virtual void preActivateCallback(bool willCallActivate) {} 
        virtual void preExecuteCallback() {}                       
        virtual bool postExecuteCallback() { return false; }       
        virtual void onTerminateCallback() {}                      
        virtual void postStepCallback() {}                         

    private:
        //
        // Private members
        //

        // Friend classes
        friend class State; // However, all derived classes of State are NOT friends for privacy reasons!

        // Internal functions
        ret_t reset();
        void freeResources(); // This function clears m_curState, m_stateAction, m_inCallback and Q, but not anything else. In particular, m_cycle retains its value, so getCycle() can still be used. Calling step() again after the resources have been freed returns SCR_TERMINATED (but still increments m_cycle). The user needs to call init() again (or forceState()) in order to be able to step() again.
        void setCurState(StatePtr state, action_t hold = PROCEED_NEXT_STATE);

        // Internal variables
        bool m_terminate;
        bool m_inCallback;
        action_t m_stateAction;
        cycle_t m_cycle;

        // Current state
        StatePtr m_curState;

        // State queue
        StateQueue Q;
    };

    //
    // State class
    //

    // Get functions
    inline StateQueue* State::Queue() const // Defined here as inline (but cannot be defined before StateController class)
    {
        // Return the required reference
        return &(scref()->Q);
    }
}

#endif /* STATE_CONTROLLER_H */
// EOF