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