simgear/structure/subsystem_mgr.hxx

   1 // Written by David Megginson, started 2000-12
   2 //
   3 // Copyright (C) 2000  David Megginson, david@megginson.com
   4 //
   5 // This program is free software; you can redistribute it and/or
   6 // modify it under the terms of the GNU General Public License as
   7 // published by the Free Software Foundation; either version 2 of the
   8 // License, or (at your option) any later version.
   9 //
  10 // This program is distributed in the hope that it will be useful, but
  11 // WITHOUT ANY WARRANTY; without even the implied warranty of
  12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 // General Public License for more details.
  14 //
  15 // You should have received a copy of the GNU General Public License
  16 // along with this program; if not, write to the Free Software
  17 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  18 //
  19 // $Id$
  20
  21
  22 #ifndef __SUBSYSTEM_MGR_HXX
  23 #define __SUBSYSTEM_MGR_HXX 1
  24
  25
  26 #include <simgear/compiler.h>
  27
  28 #include <string>
  29 #include <map>
  30 #include <vector>
  31
  32 #include <simgear/timing/timestamp.hxx>
  33 #include <simgear/structure/SGSharedPtr.hxx>
  34 #include "SGSmplstat.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
 336     private:
 337         Member (const Member &member);
 338     public:
 339         Member ();
 340         virtual ~Member ();
 341
 342         virtual void update (double delta_time_sec);
 343         void printTimingInformation(double time);
 344         void printTimingStatistics(double minMaxTime=0.0,double minJitter=0.0);
 345         void updateExecutionTime(double time);
 346         double getTimeWarningThreshold();
 347         void collectDebugTiming (bool collect) { collectTimeStats = collect; };
 348
 349         SampleStatistic timeStat;
 350         std::string name;
 351         SGSubsystem * subsystem;
 352         double min_step_sec;
 353         double elapsed_sec;
 354         bool collectTimeStats;
 355         int exceptionCount;
 356     };
 357
 358     Member * get_member (const std::string &name, bool create = false);
 359
 360     std::vector<Member *> _members;
 361
 362     double _fixedUpdateTime;
 363     double _updateTimeRemainder;
 364 };
 365
 366
 367 \f
 368 /**
 369  * Manage subsystems for FlightGear.
 370  *
 371  * This top-level subsystem will eventually manage all of the
 372  * subsystems in FlightGear: it broadcasts its life-cycle events
 373  * (init, bind, etc.) to all of the subsystems it manages.  Subsystems
 374  * are grouped to guarantee order of initialization and execution --
 375  * currently, the only two groups are INIT and GENERAL, but others
 376  * will appear in the future.
 377  *
 378  * All subsystems are named as well as grouped, and subsystems can be
 379  * looked up by name and cast to the appropriate subtype when another
 380  * subsystem needs to invoke specialized methods.
 381  *
 382  * The subsystem manager owns the pointers to all the subsystems in
 383  * it.
 384  */
 385 class SGSubsystemMgr : public SGSubsystem
 386 {
 387 public:
 388
 389     /**
 390      * Types of subsystem groups.
 391      */
 392     enum GroupType {
 393         INIT = 0,
 394         GENERAL,
 395         FDM,  ///< flight model, autopilot, instruments that run coupled
 396         POST_FDM,   ///< certain subsystems depend on FDM data
 397         DISPLAY,    ///< view, camera, rendering updates
 398         MAX_GROUPS
 399     };
 400
 401     SGSubsystemMgr ();
 402     virtual ~SGSubsystemMgr ();
 403
 404     virtual void init ();
 405     virtual void postinit ();
 406     virtual void reinit ();
 407     virtual void shutdown ();
 408     virtual void bind ();
 409     virtual void unbind ();
 410     virtual void update (double delta_time_sec);
 411     virtual void suspend ();
 412     virtual void resume ();
 413     virtual bool is_suspended () const;
 414
 415     virtual void add (const char * name,
 416                       SGSubsystem * subsystem,
 417                       GroupType group = GENERAL,
 418                       double min_time_sec = 0);
 419
 420     /**
 421      * remove a subsystem, and return a pointer to it.
 422      * returns NULL if the subsystem was not found.
 423      */
 424     virtual SGSubsystem* remove(const char* name);
 425
 426     virtual SGSubsystemGroup * get_group (GroupType group);
 427
 428     virtual SGSubsystem * get_subsystem(const std::string &name) const;
 429
 430    void collectDebugTiming(bool collect);
 431    void printTimingStatistics(double minMaxTime=0.0,double minJitter=0.0);
 432
 433 private:
 434
 435     SGSubsystemGroup* _groups[MAX_GROUPS];
 436
 437     typedef std::map<std::string, SGSubsystem*> SubsystemDict;
 438     SubsystemDict _subsystem_map;
 439
 440 };
 441
 442
 443
 444 #endif // __SUBSYSTEM_MGR_HXX
 445