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