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