2 // Written by David Megginson, started 2000-12
4 // Copyright (C) 2000 David Megginson, david@megginson.com
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.
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.
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.
23 #ifndef __SUBSYSTEM_MGR_HXX
24 #define __SUBSYSTEM_MGR_HXX 1
27 #include <simgear/compiler.h>
33 #include <simgear/timing/timestamp.hxx>
34 #include <simgear/structure/SGSharedPtr.hxx>
40 std::string eventName;
44 TimingInfo(const std::string& name, const SGTimeStamp &t) :
45 eventName(name), time(t)
47 const std::string& getName() const { return eventName; }
48 const SGTimeStamp& getTime() const { return time; }
51 class SampleStatistic;
53 typedef std::vector<TimingInfo> eventTimeVec;
54 typedef std::vector<TimingInfo>::iterator eventTimeVecIterator;
56 typedef void (*SGSubsystemTimingCb)(void* userData, const std::string& name, SampleStatistic* pStatistic);
60 * Basic interface for all FlightGear subsystems.
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>
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>
74 * void MySubsystem::bind ()
76 * fgTie("/controls/flight/elevator", &_elevator);
77 * fgSetArchivable("/controls/flight/elevator");
80 * void MySubsystem::unbind ()
82 * fgUntie("/controls/flight/elevator");
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>
92 * void MySubsystem::init ()
94 * _errorMargin = fgGetFloat("/display/error-margin-pct");
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>
105 * void MySubsystem::init ()
107 * _errorNode = fgGetNode("/display/error-margin-pct", true);
110 * void MySubsystem::update (double delta_time_sec)
112 * do_something(_errorNode.getFloatValue());
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>
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>
127 class SGSubsystem : public SGReferenced
132 * Default constructor.
137 * Virtual destructor to ensure that subclass destructors are called.
139 virtual ~SGSubsystem ();
143 * Initialize the subsystem.
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>
151 virtual void init ();
155 INIT_DONE, ///< subsystem is fully initialised
156 INIT_CONTINUE ///< init should be called again
159 virtual InitStatus incrementalInit ();
162 * Initialize parts that depend on other subsystems having been initialized.
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>
170 virtual void postinit ();
174 * Reinitialize the subsystem.
176 * <p>This method should cause the subsystem to reinitialize itself,
177 * and (normally) to reload any configuration files.</p>
179 virtual void reinit ();
183 * Shutdown the subsystem.
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.
190 virtual void shutdown ();
193 * Acquire the subsystem's property bindings.
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>
199 virtual void bind ();
203 * Release the subsystem's property bindings.
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>
209 virtual void unbind ();
213 * Update the subsystem.
215 * <p>FlightGear invokes this method every time the subsystem should
216 * update its state.</p>
218 * @param delta_time_sec The delta time, in seconds, since the last
219 * update. On first update, delta time will be 0.
221 virtual void update (double delta_time_sec) = 0;
225 * Suspend operation of this subsystem.
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>
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
236 virtual void suspend ();
240 * Suspend or resume operation of this subsystem.
242 * @param suspended true if the subsystem should be suspended, false
245 virtual void suspend (bool suspended);
249 * Resume operation of this subsystem.
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>
256 virtual void resume ();
260 * Test whether this subsystem is suspended.
262 * @return true if the subsystem is suspended, false if it is not.
264 virtual bool is_suspended () const;
267 * Trigger the callback to report timing information for all subsystems.
269 void reportTiming(void);
272 * Place time stamps at strategic points in the execution of subsystems
273 * update() member functions. Predominantly for debugging purposes.
275 void stamp(const std::string& name);
281 eventTimeVec timingInfo;
283 static SGSubsystemTimingCb reportTimingCb;
284 static void* reportTimingUserData;
290 * A group of FlightGear subsystems.
292 class SGSubsystemGroup : public SGSubsystem
297 virtual ~SGSubsystemGroup ();
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;
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;
318 void reportTiming(void);
323 void set_fixed_update_time(double fixed_dt);
327 Member* get_member (const std::string &name, bool create = false);
329 std::vector<Member *> _members;
331 double _fixedUpdateTime;
332 double _updateTimeRemainder;
334 /// index of the member we are currently init-ing
335 unsigned int _initPosition;
341 * Manage subsystems for FlightGear.
343 * This top-level subsystem will eventually manage all of the
344 * subsystems in FlightGear: it broadcasts its life-cycle events
345 * (init, bind, etc.) to all of the subsystems it manages. Subsystems
346 * are grouped to guarantee order of initialization and execution --
347 * currently, the only two groups are INIT and GENERAL, but others
348 * will appear in the future.
350 * All subsystems are named as well as grouped, and subsystems can be
351 * looked up by name and cast to the appropriate subtype when another
352 * subsystem needs to invoke specialized methods.
354 * The subsystem manager owns the pointers to all the subsystems in
357 class SGSubsystemMgr : public SGSubsystem
362 * Types of subsystem groups.
367 FDM, ///< flight model, autopilot, instruments that run coupled
368 POST_FDM, ///< certain subsystems depend on FDM data
369 DISPLAY, ///< view, camera, rendering updates
370 SOUND/*I want to be last!*/, ///< needs to run AFTER display, to allow concurrent GPU/sound processing
375 virtual ~SGSubsystemMgr ();
377 virtual void init ();
378 virtual InitStatus incrementalInit ();
379 virtual void postinit ();
380 virtual void reinit ();
381 virtual void shutdown ();
382 virtual void bind ();
383 virtual void unbind ();
384 virtual void update (double delta_time_sec);
385 virtual void suspend ();
386 virtual void resume ();
387 virtual bool is_suspended () const;
389 virtual void add (const char * name,
390 SGSubsystem * subsystem,
391 GroupType group = GENERAL,
392 double min_time_sec = 0);
395 * remove a subsystem, and return a pointer to it.
396 * returns NULL if the subsystem was not found.
398 virtual SGSubsystem* remove(const char* name);
400 virtual SGSubsystemGroup * get_group (GroupType group);
402 virtual SGSubsystem * get_subsystem(const std::string &name) const;
405 void setReportTimingCb(void* userData,SGSubsystemTimingCb cb) {reportTimingCb = cb;reportTimingUserData = userData;}
408 SGSubsystemGroup* _groups[MAX_GROUPS];
409 unsigned int _initPosition;
411 typedef std::map<std::string, SGSubsystem*> SubsystemDict;
412 SubsystemDict _subsystem_map;
417 #endif // __SUBSYSTEM_MGR_HXX