]> git.mxchange.org Git - simgear.git/blob - simgear/structure/subsystem_mgr.hxx
f1e2ad9af5e1ef0a0df572ba1aa30e28f22a35d9
[simgear.git] / simgear / structure / subsystem_mgr.hxx
1
2 // Written by David Megginson, started 2000-12
3 //
4 // Copyright (C) 2000  David Megginson, david@megginson.com
5 //
6 // This program is free software; you can redistribute it and/or
7 // modify it under the terms of the GNU General Public License as
8 // published by the Free Software Foundation; either version 2 of the
9 // License, or (at your option) any later version.
10 //
11 // This program is distributed in the hope that it will be useful, but
12 // WITHOUT ANY WARRANTY; without even the implied warranty of
13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14 // General Public License for more details.
15 //
16 // You should have received a copy of the GNU General Public License
17 // along with this program; if not, write to the Free Software
18 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
19 //
20 // $Id$
21
22
23 #ifndef __SUBSYSTEM_MGR_HXX
24 #define __SUBSYSTEM_MGR_HXX 1
25
26
27 #include <simgear/compiler.h>
28
29 #include <string>
30 #include <map>
31 #include <vector>
32
33 #include <simgear/timing/timestamp.hxx>
34 #include <simgear/structure/SGSharedPtr.hxx>
35
36
37 class TimingInfo
38 {
39 private:
40     std::string eventName;
41     SGTimeStamp time;
42
43 public: 
44     TimingInfo(const std::string& name, const SGTimeStamp &t) :
45         eventName(name), time(t)
46     { }
47     const std::string& getName() const { return eventName; }
48     const SGTimeStamp& getTime() const { return time; }
49 };
50
51 typedef std::vector<TimingInfo> eventTimeVec;
52 typedef std::vector<TimingInfo>::iterator eventTimeVecIterator;
53
54
55 \f
56 /**
57  * Basic interface for all FlightGear subsystems.
58  *
59  * <p>This is an abstract interface that all FlightGear subsystems
60  * will eventually implement.  It defines the basic operations for
61  * each subsystem: initialization, property binding and unbinding, and
62  * updating.  Interfaces may define additional methods, but the
63  * preferred way of exchanging information with other subsystems is
64  * through the property tree.</p>
65  *
66  * <p>To publish information through a property, a subsystem should
67  * bind it to a variable or (if necessary) a getter/setter pair in the
68  * bind() method, and release the property in the unbind() method:</p>
69  *
70  * <pre>
71  * void MySubsystem::bind ()
72  * {
73  *   fgTie("/controls/flight/elevator", &_elevator);
74  *   fgSetArchivable("/controls/flight/elevator");
75  * }
76  *
77  * void MySubsystem::unbind ()
78  * {
79  *   fgUntie("/controls/flight/elevator");
80  * }
81  * </pre>
82  *
83  * <p>To reference a property (possibly) from another subsystem, there
84  * are two alternatives.  If the property will be referenced only
85  * infrequently (say, in the init() method), then the fgGet* methods
86  * declared in fg_props.hxx are the simplest:</p>
87  *
88  * <pre>
89  * void MySubsystem::init ()
90  * {
91  *   _errorMargin = fgGetFloat("/display/error-margin-pct");
92  * }
93  * </pre>
94  *
95  * <p>On the other hand, if the property will be referenced frequently
96  * (say, in the update() method), then the hash-table lookup required
97  * by the fgGet* methods might be too expensive; instead, the
98  * subsystem should obtain a reference to the actual property node in
99  * its init() function and use that reference in the main loop:</p>
100  *
101  * <pre>
102  * void MySubsystem::init ()
103  * {
104  *   _errorNode = fgGetNode("/display/error-margin-pct", true);
105  * }
106  *
107  * void MySubsystem::update (double delta_time_sec)
108  * {
109  *   do_something(_errorNode.getFloatValue());
110  * }
111  * </pre>
112  *
113  * <p>The node returned will always be a pointer to SGPropertyNode,
114  * and the subsystem should <em>not</em> delete it in its destructor
115  * (the pointer belongs to the property tree, not the subsystem).</p>
116  *
117  * <p>The program may ask the subsystem to suspend or resume
118  * sim-time-dependent operations; by default, the suspend() and
119  * resume() methods set the protected variable <var>_suspended</var>,
120  * which the subsystem can reference in its update() method, but
121  * subsystems may also override the suspend() and resume() methods to
122  * take different actions.</p>
123  */
124 class SGSubsystem : public SGReferenced
125 {
126 public:
127
128   /**
129    * Default constructor.
130    */
131   SGSubsystem ();
132
133   /**
134    * Virtual destructor to ensure that subclass destructors are called.
135    */
136   virtual ~SGSubsystem ();
137
138
139   /**
140    * Initialize the subsystem.
141    *
142    * <p>This method should set up the state of the subsystem, but
143    * should not bind any properties.  Note that any dependencies on
144    * the state of other subsystems should be placed here rather than
145    * in the constructor, so that FlightGear can control the
146    * initialization order.</p>
147    */
148   virtual void init ();
149
150
151   /**
152    * Initialize parts that depend on other subsystems having been initialized.
153    *
154    * <p>This method should set up all parts that depend on other
155    * subsystems. One example is the scripting/Nasal subsystem, which
156    * is initialized last. So, if a subsystem wants to execute Nasal
157    * code in subsystem-specific configuration files, it has to do that
158    * in its postinit() method.</p>
159    */
160   virtual void postinit ();
161
162
163   /**
164    * Reinitialize the subsystem.
165    *
166    * <p>This method should cause the subsystem to reinitialize itself,
167    * and (normally) to reload any configuration files.</p>
168    */
169   virtual void reinit ();
170
171
172   /**
173    * Shutdown the subsystem.
174    *
175    * <p>Release any state associated with subsystem. Shutdown happens in
176    * the reverse order to init(), so this is the correct place to do
177    * shutdown that depends on other subsystems.
178    * </p>
179    */
180   virtual void shutdown ();
181    
182   /**
183    * Acquire the subsystem's property bindings.
184    *
185    * <p>This method should bind all properties that the subsystem
186    * publishes.  It will be invoked after init, but before any
187    * invocations of update.</p>
188    */
189   virtual void bind ();
190
191
192   /**
193    * Release the subsystem's property bindings.
194    *
195    * <p>This method should release all properties that the subsystem
196    * publishes.  It will be invoked by FlightGear (not the destructor)
197    * just before the subsystem is removed.</p>
198    */
199   virtual void unbind ();
200
201
202   /**
203    * Update the subsystem.
204    *
205    * <p>FlightGear invokes this method every time the subsystem should
206    * update its state.</p>
207    *
208    * @param delta_time_sec The delta time, in seconds, since the last
209    * update.  On first update, delta time will be 0.
210    */
211   virtual void update (double delta_time_sec) = 0;
212
213
214   /**
215    * Suspend operation of this subsystem.
216    *
217    * <p>This method instructs the subsystem to suspend
218    * sim-time-dependent operations until asked to resume.  The update
219    * method will still be invoked so that the subsystem can take any
220    * non-time-dependent actions, such as updating the display.</p>
221    *
222    * <p>It is not an error for the suspend method to be invoked when
223    * the subsystem is already suspended; the invocation should simply
224    * be ignored.</p>
225    */
226   virtual void suspend ();
227
228
229   /**
230    * Suspend or resum operation of this subsystem.
231    *
232    * @param suspended true if the subsystem should be suspended, false
233    * otherwise.
234    */
235   virtual void suspend (bool suspended);
236
237
238   /**
239    * Resume operation of this subsystem.
240    *
241    * <p>This method instructs the subsystem to resume
242    * sim-time-depended operations.  It is not an error for the resume
243    * method to be invoked when the subsystem is not suspended; the
244    * invocation should simply be ignored.</p>
245    */
246   virtual void resume ();
247
248
249   /**
250    * Test whether this subsystem is suspended.
251    *
252    * @return true if the subsystem is suspended, false if it is not.
253    */
254   virtual bool is_suspended () const;
255
256
257   /**
258    * Keep track of execution time.
259    *
260    * <p>This method keeps track of timing statistics for each subsystem.</p>
261    * 
262    * @param time execution time in ms of last call.
263    */
264   void updateExecutionTime(double time);
265
266   /**
267    * Print details of execution time.
268    *
269    * <p>For debugging purposes, developers can place stamp() calls
270    * at strategic points in the update() function of each subsystem, which 
271    * record the time between the successive calls to stamp. This method,
272    * printExecutionTime() is called after exectution of the subsystem
273    * update function itself to conduct a post-hoc analysis of excecution
274    * time</p>
275    */ 
276   void printTimingInformation();
277
278   /**
279    * Place time stamps at strategic points in the execution of subsystems 
280    * update() member functions. Predominantly for debugging purposes.
281    */
282   void stamp(const std::string& name);
283   
284
285
286 protected:
287
288   bool _suspended;
289
290   eventTimeVec timingInfo;
291   //int test;
292
293 };
294
295
296 \f
297 /**
298  * A group of FlightGear subsystems.
299  */
300 class SGSubsystemGroup : public SGSubsystem
301 {
302 public:
303
304     SGSubsystemGroup ();
305     virtual ~SGSubsystemGroup ();
306
307     virtual void init ();
308     virtual void postinit ();
309     virtual void reinit ();
310     virtual void shutdown ();
311     virtual void bind ();
312     virtual void unbind ();
313     virtual void update (double delta_time_sec);
314     virtual void suspend ();
315     virtual void resume ();
316     virtual bool is_suspended () const;
317
318     virtual void set_subsystem (const std::string &name,
319                                 SGSubsystem * subsystem,
320                                 double min_step_sec = 0);
321     virtual SGSubsystem * get_subsystem (const std::string &name);
322     virtual void remove_subsystem (const std::string &name);
323     virtual bool has_subsystem (const std::string &name) const;
324
325     void collectDebugTiming(bool collect);
326     void printTimingStatistics(double minMaxTime=0.0,double minJitter=0.0);
327
328     /**
329      * 
330      */
331     void set_fixed_update_time(double fixed_dt);
332 private:
333
334     class Member;
335     Member* get_member (const std::string &name, bool create = false);
336
337     std::vector<Member *> _members;
338     
339     double _fixedUpdateTime;
340     double _updateTimeRemainder;
341 };
342
343
344 \f
345 /**
346  * Manage subsystems for FlightGear.
347  *
348  * This top-level subsystem will eventually manage all of the
349  * subsystems in FlightGear: it broadcasts its life-cycle events
350  * (init, bind, etc.) to all of the subsystems it manages.  Subsystems
351  * are grouped to guarantee order of initialization and execution --
352  * currently, the only two groups are INIT and GENERAL, but others
353  * will appear in the future.
354  *
355  * All subsystems are named as well as grouped, and subsystems can be
356  * looked up by name and cast to the appropriate subtype when another
357  * subsystem needs to invoke specialized methods.
358  *
359  * The subsystem manager owns the pointers to all the subsystems in
360  * it.
361  */
362 class SGSubsystemMgr : public SGSubsystem
363 {
364 public:
365
366     /**
367      * Types of subsystem groups.
368      */
369     enum GroupType {
370         INIT = 0,
371         GENERAL,
372         FDM,  ///< flight model, autopilot, instruments that run coupled
373         POST_FDM,   ///< certain subsystems depend on FDM data
374         DISPLAY,    ///< view, camera, rendering updates
375         MAX_GROUPS
376     };
377
378     SGSubsystemMgr ();
379     virtual ~SGSubsystemMgr ();
380
381     virtual void init ();
382     virtual void postinit ();
383     virtual void reinit ();
384     virtual void shutdown ();
385     virtual void bind ();
386     virtual void unbind ();
387     virtual void update (double delta_time_sec);
388     virtual void suspend ();
389     virtual void resume ();
390     virtual bool is_suspended () const;
391
392     virtual void add (const char * name,
393                       SGSubsystem * subsystem,
394                       GroupType group = GENERAL, 
395                       double min_time_sec = 0);
396
397     /**
398      * remove a subsystem, and return a pointer to it.
399      * returns NULL if the subsystem was not found.
400      */
401     virtual SGSubsystem* remove(const char* name);
402
403     virtual SGSubsystemGroup * get_group (GroupType group);
404
405     virtual SGSubsystem * get_subsystem(const std::string &name) const;
406
407    void collectDebugTiming(bool collect);
408    void printTimingStatistics(double minMaxTime=0.0,double minJitter=0.0);
409
410 private:
411
412     SGSubsystemGroup* _groups[MAX_GROUPS];
413     
414     typedef std::map<std::string, SGSubsystem*> SubsystemDict;
415     SubsystemDict _subsystem_map;
416
417 };
418
419
420
421 #endif // __SUBSYSTEM_MGR_HXX
422