source: trunk/FACT++/src/StateMachineImp.h @ 10309

Last change on this file since 10309 was 10309, checked in by tbretz, 9 years ago
Added typedef for StateNames; changed the getter such that they can now be declared const.
File size: 8.7 KB
Line 
1#ifndef FACT_StateMachineImp
2#define FACT_StateMachineImp
3
4#include <map>
5#include <queue>
6#include <mutex>
7#include <vector>
8
9#include "MessageImp.h"
10
11class Event;
12class EventImp;
13
14class StateMachineImp : public MessageImp
15{
16public:
17    /// A list of default states available to any state machine.
18    /// Derived classes must define different state-number for
19    /// their purpose
20    enum
21    {
22        kSM_NotReady   =     -1,  ///< Mainloop not running, state machine stopped
23        kSM_Ready      =      0,  ///< Mainloop running, state machine in operation
24        kSM_Error      =  0x100,  ///< Error states should be between 0x100 and 0xffff
25        kSM_FatalError = 0xffff,  ///< Fatal error: stop program
26    } defaultstates_t;
27
28private:
29    std::string fName;   /// Name of the state-machine / server (e.g. DRIVE)
30
31    int fCurrentState;   /// Current state of the state machine
32
33    typedef std::map<const int, std::pair<std::string, std::string>> StateNames;
34
35    /// Human readable names associated with the states
36    StateNames fStateNames;
37
38    std::vector<EventImp*> fListOfEvents; /// List of available commands as setup by user
39    std::queue<Event*>     fEventQueue;   /// Event queue (fifo) for the received commands
40
41    std::mutex fMutex;   /// Mutex to ensure thread-safe access to the command fifo
42
43    bool fRunning;       /// Machine is in main-loop
44    int  fExitRequested; /// This is a flag which is set true if the main loop should stop
45
46    /// Push a command into the fifo. The fifo takes over ownership
47    void PushEvent(Event *cmd);
48    /// Pop a command from the fifo. You take over owenership
49    Event *PopEvent();
50
51    bool HandleNewState(int newstate, const EventImp *evt, const char *txt, const char *alt=0);
52    bool HandleNewState(int newstate, const char *txt)
53    {
54        return HandleNewState(newstate, 0, txt);
55    }
56
57    virtual EventImp *CreateEvent(int targetstate, const char *name, const char *fmt);
58
59    /// Is called continously to execute actions in the current state
60    virtual int Execute() { return fCurrentState; }
61    /// Is called when a configuration event is to be processed (no transition of state)
62    virtual int Configure(const Event &) { return kSM_FatalError; }
63    /// Is called when a transition change event is to be processed (from one state to another) is received
64    virtual int Transition(const Event &) { return kSM_FatalError; }
65
66protected:
67
68    bool HandleEvent(const EventImp &evt);
69
70    /// This is an internal function to do some action in case of
71    /// a state change, like updating the corresponding service.
72    virtual std::string SetCurrentState(int state, const char *txt="", const std::string &cmd="");
73
74    EventImp &AddTransition(int targetstate, const char *name, const char *states, const char *fmt);
75    EventImp &AddTransition(int targetstate, const char *name, int s1=-1, int s2=-1, int s3=-1, int s4=-1, int s5=-1);
76    EventImp &AddTransition(int targetstate, const char *name, const char *fmt, int s1=-1, int s2=-1, int s3=-1, int s4=-1, int s5=-1);
77
78    EventImp &AddConfiguration(const char *name, const char *states, const char *fmt);
79    EventImp &AddConfiguration(const char *name, int s1=-1, int s2=-1, int s3=-1, int s4=-1, int s5=-1);
80    EventImp &AddConfiguration(const char *name, const char *fmt, int s1=-1, int s2=-1, int s3=-1, int s4=-1, int s5=-1);
81
82    void AddStateName(const int state, const std::string &name, const std::string &doc="");
83
84public:
85    StateMachineImp(std::ostream &out=std::cout, const std::string &name="");
86    ~StateMachineImp();
87
88    const std::string &GetName() const { return fName; }
89
90    /// return the current state of the machine
91    int GetCurrentState() const { return fCurrentState; }
92
93    void SetReady()    { SetCurrentState(kSM_Ready, "set manually");    }
94    void SetNotReady() { SetCurrentState(kSM_NotReady, "set manually"); }
95
96    /// Start the mainloop
97    int Run(bool dummy);
98    int Run() { return Run(false); }
99
100    /// Request to stop the mainloop
101    void Stop(int code=1);
102
103    /// Used to check if the main loop is already running or still running
104    bool IsRunning() const { return fRunning; }
105
106    /// Post an event to the event queue
107    bool PostEvent(std::ostream &lout, const std::string &str);
108    bool PostEvent(const std::string &evt) { return PostEvent(std::cout, evt); }
109    bool PostEvent(const EventImp &evt);
110    bool PostEvent(const EventImp &evt, const char *ptr, size_t siz);
111
112    // Event handling
113    bool HasEvent(const EventImp *cmd) const;
114    EventImp *FindEvent(const std::string &evt) const;
115
116    bool IsQueueEmpty() const { return fEventQueue.size()==0; }
117
118    const std::vector<EventImp*> &GetListOfEvents() const { return fListOfEvents; }
119    const std::vector<std::string> GetEventNames() const;
120
121    void PrintListOfEvents(std::ostream &out);
122    void PrintListOfEvents();
123
124
125    const std::string GetStateName(int state) const;
126    const std::string GetStateName() const { return GetStateName(fCurrentState); }
127
128    const std::string GetStateDesc(int state) const;
129    const std::string GetStateDesc() const { return GetStateDesc(fCurrentState); }
130
131    const std::string GetStateDescription(int state) const;
132    const std::string GetStateDescription() const { return GetStateDescription(fCurrentState); }
133};
134
135#endif
136
137// ***************************************************************************
138/** @fn StateMachineImp::Execute()
139
140This is what the state machine is doing in a certain state
141continously. In an idle state this might just be doing nothing.
142
143In the tracking state of the drive system this might be sending
144new command values to the drive based on its current position.
145
146The current state of the state machine can be accessed by GetCurrentState()
147
148@returns
149   Usually it should just return the current state. However, sometimes
150   execution might lead to a new state, e.g. when a hardware error
151   is detected. In this case a new state can be returned to put the state
152   machine into a different state. Note, that the function is responsible
153   of doing all actions connected with the state change itself.
154   If not overwritten it returns the current status.
155
156**/
157// ***************************************************************************
158/** @fn StateMachineImp::Configure(const Event &evt)
159
160This function is called when a configuration event is to be processed.
161
162The current state of the state machine is accessible via GetCurrentState().
163
164The issued event and its corresponding data is accessible through
165evn. (see Event and DimEvent for details) Usually such an event
166will not change the state. In this case fCurrentState will be returned.
167However, to allow the machine to go into an error state it is possible
168to change the state by giving a different return value. When the
169Configure function is called the validity of the state transition has
170already been checked.
171
172@param evt
173   A reference to an Event object with the event which should
174   be processed. Note that the cmd-object will get deleted after the
175   function has returned.
176
177@returns
178   Usually it should just return the current state. However, sometimes
179   a configuration command which was not intended to change the state
180   has to change the state, e.g. to go to an error state. Return any
181   other state than GetCurrentState() can put the state machine into
182   a different state.  Note, that the function is responsible
183   of doing all actions connected with the state change itself.
184   If not overwritten it returns kSM_FatalError.
185
186**/
187// ***************************************************************************
188/** @fn StateMachineImp::Transition(const Event &evt)
189
190This function is called if a state transision was requested.
191
192The current state of the state machine is accessible via GetCurrentState().
193
194The new state is accessible via evt.GetTargetState().
195
196The event and its corresponding data is accessible through evt.
197(see DimCommand and DimEvent for details) If the transition was
198successfull the new status should be returned. If it was unsuccessfull
199either the old or any other new status will be returned.
200
201When the Transition function is called the validity of the state
202transition has already been checked.
203
204@param evt
205   A reference to an Event object with the event which should
206   be processed. Note that the cmd-object will get deleted after the
207   function has returned.
208
209@returns
210   Usually it should return the new state. However, sometimes
211   a transition command might has to change the state to a different
212   state than the one requested (e.g. an error has occured) In this
213   case it is also allowed to return a different state.  Note, that the
214   function is responsible of doing all actions connected with the
215   state change itself.
216   If not overwritten it returns kSM_FatalError.
217
218**/
219// ***************************************************************************
Note: See TracBrowser for help on using the repository browser.