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