StateMachine.hpp

/***************************************************************************
  tag: Peter Soetens  Tue Dec 21 22:43:07 CET 2004  StateMachineTree.hpp

                        StateMachineTree.hpp -  description
                           -------------------
    begin                : Tue December 21 2004
    copyright            : (C) 2004 Peter Soetens
    email                : peter.soetens@mech.kuleuven.ac.be

 ***************************************************************************
 *   This library 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;                 *
 *   version 2 of the License.                                             *
 *                                                                         *
 *   As a special exception, you may use this file as part of a free       *
 *   software library without restriction.  Specifically, if other files   *
 *   instantiate templates or use macros or inline functions from this     *
 *   file, or you compile this file and link it with other files to        *
 *   produce an executable, this file does not by itself cause the         *
 *   resulting executable to be covered by the GNU General Public          *
 *   License.  This exception does not however invalidate any other        *
 *   reasons why the executable file might be covered by the GNU General   *
 *   Public License.                                                       *
 *                                                                         *
 *   This library is distributed in the hope that it will be useful,       *
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU     *
 *   Lesser General Public License for more details.                       *
 *                                                                         *
 *   You should have received a copy of the GNU General Public             *
 *   License along with this library; if not, write to the Free Software   *
 *   Foundation, Inc., 59 Temple Place,                                    *
 *   Suite 330, Boston, MA  02111-1307  USA                                *
 *                                                                         *
 ***************************************************************************/


#ifndef HIERARCHICAL_STATE_MACHINE_HPP
#define HIERARCHICAL_STATE_MACHINE_HPP

#include "StateInterface.hpp"
#include "ConditionInterface.hpp"
#include "CommandInterface.hpp"
#include "DataSourceBase.hpp"
#include "Handle.hpp"
#include "EventProcessor.hpp"

#include <map>
#include <vector>
#include <string>
#include <utility>
#include <boost/tuple/tuple.hpp>
#include <boost/weak_ptr.hpp>
#include <boost/shared_ptr.hpp>

namespace RTT
{



    class TaskContext;
    class EventService;
    class StateMachineProcessor;

    class StateMachine;
    typedef boost::shared_ptr<StateMachine> StateMachinePtr;
    typedef boost::weak_ptr<StateMachine> StateMachineWPtr;

    class RTT_API StateMachine
    {
        enum PrivateStatus { nill, gostop, goreset, pausing } smpStatus;

        static std::string emptyString;
    public:
        struct RTT_API Status {
            enum StateMachineStatus {inactive, activating, active, requesting, running, stopping, stopped, resetting, deactivating, paused, error, unloaded };
        };
    protected:
        typedef std::vector< boost::tuple<ConditionInterface*, StateInterface*, int, int, boost::shared_ptr<ProgramInterface> > > TransList;
        typedef std::map< StateInterface*, TransList > TransitionMap;
        typedef std::multimap< StateInterface*, std::pair<ConditionInterface*, int> > PreConditionMap;
        typedef std::vector< boost::tuple<EventService*,
                                          std::string, std::vector<DataSourceBase::shared_ptr>,
                                          StateInterface*,
                                          ConditionInterface*, boost::shared_ptr<ProgramInterface>,
                                          Handle,
                                          StateInterface*, boost::shared_ptr<ProgramInterface> > > EventList;
        typedef std::map< StateInterface*, EventList > EventMap;
        std::vector<StateMachinePtr> _children;
        typedef boost::weak_ptr<StateMachine> StateMachineParentPtr;
        StateMachineParentPtr _parent;

        std::string _name;
        EventProcessor* eproc;
        Status::StateMachineStatus smStatus;
        StateMachineProcessor* smp;

        // Hook to denote to subclasses that we are unloaded.
        virtual void handleUnload();
    public:

        typedef std::vector<StateMachinePtr> ChildList;

        virtual ~StateMachine();

        StateMachine(StateMachinePtr parent, const std::string& name="Default");

        StateMachine(StateMachinePtr parent, EventProcessor* ep, const std::string& name="Default");

        void setStateMachineProcessor(StateMachineProcessor* smproc) {
            smp = smproc;
            if (smp)
                smStatus = Status::inactive;
            else {
                smStatus = Status::unloaded;
                this->handleUnload();
            }
        }

        void setEventProcessor(EventProcessor* smproc) {
            eproc = smproc;
        }

        bool requestState(const std::string& statename) {
            StateInterface* tmp = this->getState(statename);
            if (tmp) {
                return this->requestStateChange( tmp );
            }
            return false;
        }

        bool inState(const std::string& state) const {
            StateInterface* copy = this->currentState();
            if (copy == 0)
                return false;
            return copy->getName() == state;
        }

        bool inStrictState(const std::string& state) const {
            StateInterface* copy = this->currentState();
            if (copy == 0)
                return false;
            return copy->getName() == state && !this->inTransition();
        }

        const std::string& getCurrentStateName() const {
            StateInterface* copy = this->currentState();
            if (copy == 0)
                return emptyString;
            return copy->getName();
        }

        inline bool isStrictlyActive() const {
            return this->isActive() && !this->inTransition();
        }

        inline bool inInitialState() const {
            return initstate == current;// && !_sc->inTransition();
        }

        inline bool inFinalState() const {
            return finistate == current;// && !this->inTransition();
        }

        bool stepDone() const {
            if ( isPaused() )
                return !mstep;
            return isStrictlyActive();
        }

        inline bool isActive() const { return current != 0; }

        inline bool isStopped() const { return smStatus == Status::stopped; }

        inline bool inError() const { return smStatus == Status::error; }

        inline bool isReactive() const { return current != 0 && smStatus != Status::running; }

        inline bool isAutomatic() const { return smStatus == Status::running; }

        inline bool isPaused() const { return smStatus == Status::paused; }

        bool activate();

        bool pause();

        bool step();

        bool automatic();

        bool start();

        bool stop();

        bool reset();

        bool reactive();

        bool deactivate();

        bool execute();

        StateInterface* requestNextState(bool stepping = false);

        StateInterface* requestNextStateStep();

        bool requestFinalState();

        bool requestInitialState();

        StateInterface* nextState();

        std::vector<std::string> getStateList() const;

        StateInterface* getState( const std::string & name ) const;

        Status::StateMachineStatus getStatus() const;

        void addState( StateInterface* s );

        bool requestStateChange( StateInterface * s_n );

        bool executePending( bool stepping = false );

        void preconditionSet( StateInterface* state, ConditionInterface* cnd, int line);

        void transitionSet( StateInterface* from, StateInterface* to, ConditionInterface* cnd, int priority, int line);

        void transitionSet( StateInterface* from, StateInterface* to,
                            ConditionInterface* cnd, boost::shared_ptr<ProgramInterface> transprog,
                            int priority, int line);

        bool createEventTransition( EventService* es,
                                    const std::string& ename, std::vector<DataSourceBase::shared_ptr> args,
                                    StateInterface* from, StateInterface* to,
                                    ConditionInterface* guard, boost::shared_ptr<ProgramInterface> transprog,
                                    StateInterface* elseto = 0, boost::shared_ptr<ProgramInterface> elseprog =
                                    boost::shared_ptr<ProgramInterface>() );

        void setInitialState( StateInterface* s );

        void setFinalState( StateInterface* s );

        StateInterface* currentState() const;

        ProgramInterface* currentProgram() const;

        StateInterface* getInitialState() const {
            return initstate;
        }

        StateInterface* getFinalState() const {
            return finistate;
        }

        void setInitCommand( CommandInterface* c)
        {
            initc = c;
        }

        CommandInterface* getInitCommand() const
        {
            return initc;
        }

        StateMachinePtr getParent() const
        {
            return _parent.lock();
        }

        void setParent(StateMachinePtr parent)
        {
            _parent = parent;
        }

        const ChildList& getChildren() const
        {
            return _children;
        }

        void addChild( StateMachinePtr child ) {
            _children.push_back( child );
        }

        const std::string& getName() const {
            return _name;
        }

        int getLineNumber() const;

        virtual std::string getText() const;

        bool inTransition() const;

        bool interruptible() const;

    protected:
        TransitionMap stateMap;

        PreConditionMap precondMap;

        EventMap eventMap;


        void changeState( StateInterface* s, ProgramInterface* tprog, bool stepping = false );

        void leaveState( StateInterface* s );

        void enterState( StateInterface* s );

        void runState( StateInterface* s );

        void handleState( StateInterface* s );

        bool executeProgram(ProgramInterface*& cp, bool stepping);

        int checkConditions( StateInterface* state, bool stepping = false );

        void enableEvents( StateInterface* s );
        void disableEvents( StateInterface* s );
    private:

        void eventTransition( StateInterface* from, ConditionInterface* c,
                              ProgramInterface* p, StateInterface* to,
                              ProgramInterface* elsep, StateInterface* elseto );

        StateInterface* initstate;

        StateInterface* finistate;

        StateInterface* current;

        StateInterface* next;

        CommandInterface* initc;

        ProgramInterface* currentProg;
        ProgramInterface* currentExit;
        ProgramInterface* currentHandle;
        ProgramInterface* currentEntry;
        ProgramInterface* currentRun;
        ProgramInterface* currentTrans;

        TransList::iterator reqstep;
        TransList::iterator reqend;

        std::pair<PreConditionMap::const_iterator,PreConditionMap::const_iterator> prec_it;
        bool checking_precond;
        bool mstep;

        int evaluating;
    };
}

#endif