1 // Written by David Megginson, started 2000-12
3 // Copyright (C) 2000 David Megginson, david@megginson.com
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.
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.
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.
22 #ifndef __SUBSYSTEM_MGR_HXX
23 #define __SUBSYSTEM_MGR_HXX 1
26 #include <simgear/compiler.h>
32 #include <simgear/props/props.hxx>
33 #include <simgear/timing/timestamp.hxx>
34 #include "SGSmplstat.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 typedef std::vector<TimingInfo> eventTimeVec;
52 typedef std::vector<TimingInfo>::iterator eventTimeVecIterator;
57 * Basic interface for all FlightGear subsystems.
59 * <p>This is an abstract interface that all FlightGear subsystems
60 * will eventually implement. It defines the basic operations for
61 * each subsystem: initialization, property binding and unbinding, and
62 * updating. Interfaces may define additional methods, but the
63 * preferred way of exchanging information with other subsystems is
64 * through the property tree.</p>
66 * <p>To publish information through a property, a subsystem should
67 * bind it to a variable or (if necessary) a getter/setter pair in the
68 * bind() method, and release the property in the unbind() method:</p>
71 * void MySubsystem::bind ()
73 * fgTie("/controls/flight/elevator", &_elevator);
74 * fgSetArchivable("/controls/flight/elevator");
77 * void MySubsystem::unbind ()
79 * fgUntie("/controls/flight/elevator");
83 * <p>To reference a property (possibly) from another subsystem, there
84 * are two alternatives. If the property will be referenced only
85 * infrequently (say, in the init() method), then the fgGet* methods
86 * declared in fg_props.hxx are the simplest:</p>
89 * void MySubsystem::init ()
91 * _errorMargin = fgGetFloat("/display/error-margin-pct");
95 * <p>On the other hand, if the property will be referenced frequently
96 * (say, in the update() method), then the hash-table lookup required
97 * by the fgGet* methods might be too expensive; instead, the
98 * subsystem should obtain a reference to the actual property node in
99 * its init() function and use that reference in the main loop:</p>
102 * void MySubsystem::init ()
104 * _errorNode = fgGetNode("/display/error-margin-pct", true);
107 * void MySubsystem::update (double delta_time_sec)
109 * do_something(_errorNode.getFloatValue());
113 * <p>The node returned will always be a pointer to SGPropertyNode,
114 * and the subsystem should <em>not</em> delete it in its destructor
115 * (the pointer belongs to the property tree, not the subsystem).</p>
117 * <p>The program may ask the subsystem to suspend or resume
118 * sim-time-dependent operations; by default, the suspend() and
119 * resume() methods set the protected variable <var>_suspended</var>,
120 * which the subsystem can reference in its update() method, but
121 * subsystems may also override the suspend() and resume() methods to
122 * take different actions.</p>
124 class SGSubsystem : public SGReferenced
129 * Default constructor.
134 * Virtual destructor to ensure that subclass destructors are called.
136 virtual ~SGSubsystem ();
140 * Initialize the subsystem.
142 * <p>This method should set up the state of the subsystem, but
143 * should not bind any properties. Note that any dependencies on
144 * the state of other subsystems should be placed here rather than
145 * in the constructor, so that FlightGear can control the
146 * initialization order.</p>
148 virtual void init ();
152 * Initialize parts that depend on other subsystems having been initialized.
154 * <p>This method should set up all parts that depend on other
155 * subsystems. One example is the scripting/Nasal subsystem, which
156 * is initialized last. So, if a subsystem wants to execute Nasal
157 * code in subsystem-specific configuration files, it has to do that
158 * in its postinit() method.</p>
160 virtual void postinit ();
164 * Reinitialize the subsystem.
166 * <p>This method should cause the subsystem to reinitialize itself,
167 * and (normally) to reload any configuration files.</p>
169 virtual void reinit ();
173 * Acquire the subsystem's property bindings.
175 * <p>This method should bind all properties that the subsystem
176 * publishes. It will be invoked after init, but before any
177 * invocations of update.</p>
179 virtual void bind ();
183 * Release the subsystem's property bindings.
185 * <p>This method should release all properties that the subsystem
186 * publishes. It will be invoked by FlightGear (not the destructor)
187 * just before the subsystem is removed.</p>
189 virtual void unbind ();
193 * Update the subsystem.
195 * <p>FlightGear invokes this method every time the subsystem should
196 * update its state.</p>
198 * @param delta_time_sec The delta time, in seconds, since the last
199 * update. On first update, delta time will be 0.
201 virtual void update (double delta_time_sec) = 0;
205 * Suspend operation of this subsystem.
207 * <p>This method instructs the subsystem to suspend
208 * sim-time-dependent operations until asked to resume. The update
209 * method will still be invoked so that the subsystem can take any
210 * non-time-dependent actions, such as updating the display.</p>
212 * <p>It is not an error for the suspend method to be invoked when
213 * the subsystem is already suspended; the invocation should simply
216 virtual void suspend ();
220 * Suspend or resum operation of this subsystem.
222 * @param suspended true if the subsystem should be suspended, false
225 virtual void suspend (bool suspended);
229 * Resume operation of this subsystem.
231 * <p>This method instructs the subsystem to resume
232 * sim-time-depended operations. It is not an error for the resume
233 * method to be invoked when the subsystem is not suspended; the
234 * invocation should simply be ignored.</p>
236 virtual void resume ();
240 * Test whether this subsystem is suspended.
242 * @return true if the subsystem is suspended, false if it is not.
244 virtual bool is_suspended () const;
248 * Keep track of execution time.
250 * <p>This method keeps track of timing statistics for each subsystem.</p>
252 * @param time execution time in ms of last call.
254 void updateExecutionTime(double time);
257 * Print details of execution time.
259 * <p>For debugging purposes, developers can place stamp() calls
260 * at strategic points in the update() function of each subsystem, which
261 * record the time between the successive calls to stamp. This method,
262 * printExecutionTime() is called after exectution of the subsystem
263 * update function itself to conduct a post-hoc analysis of excecution
266 void printTimingInformation();
269 * Place time stamps at strategic points in the execution of subsystems
270 * update() member functions. Predominantly for debugging purposes.
272 void stamp(const std::string& name);
280 eventTimeVec timingInfo;
288 * A group of FlightGear subsystems.
290 class SGSubsystemGroup : public SGSubsystem
295 virtual ~SGSubsystemGroup ();
297 virtual void init ();
298 virtual void postinit ();
299 virtual void reinit ();
300 virtual void bind ();
301 virtual void unbind ();
302 virtual void update (double delta_time_sec);
303 virtual void suspend ();
304 virtual void resume ();
305 virtual bool is_suspended () const;
307 virtual void set_subsystem (const std::string &name,
308 SGSubsystem * subsystem,
309 double min_step_sec = 0);
310 virtual SGSubsystem * get_subsystem (const std::string &name);
311 virtual void remove_subsystem (const std::string &name);
312 virtual bool has_subsystem (const std::string &name) const;
314 void collectDebugTiming(bool collect);
319 void set_fixed_update_time(double fixed_dt);
325 Member (const Member &member);
330 virtual void update (double delta_time_sec);
331 void printTimingInformation(double time);
332 void printTimingStatistics();
333 void updateExecutionTime(double time);
334 double getTimeWarningThreshold();
335 void collectDebugTiming (bool collect) { collectTimeStats = collect; };
337 SampleStatistic timeStat;
339 SGSubsystem * subsystem;
342 bool collectTimeStats;
346 Member * get_member (const std::string &name, bool create = false);
348 std::vector<Member *> _members;
350 double _fixedUpdateTime;
351 double _updateTimeRemainder;
357 * Manage subsystems for FlightGear.
359 * This top-level subsystem will eventually manage all of the
360 * subsystems in FlightGear: it broadcasts its life-cycle events
361 * (init, bind, etc.) to all of the subsystems it manages. Subsystems
362 * are grouped to guarantee order of initialization and execution --
363 * currently, the only two groups are INIT and GENERAL, but others
364 * will appear in the future.
366 * All subsystems are named as well as grouped, and subsystems can be
367 * looked up by name and cast to the appropriate subtype when another
368 * subsystem needs to invoke specialized methods.
370 * The subsystem manager owns the pointers to all the subsystems in
373 class SGSubsystemMgr : public SGSubsystem
378 * Types of subsystem groups.
383 FDM, ///< flight model, autopilot, instruments that run coupled
384 POST_FDM, ///< certain subsystems depend on FDM data
385 DISPLAY, ///< view, camera, rendering updates
390 virtual ~SGSubsystemMgr ();
392 virtual void init ();
393 virtual void postinit ();
394 virtual void reinit ();
395 virtual void bind ();
396 virtual void unbind ();
397 virtual void update (double delta_time_sec);
398 virtual void suspend ();
399 virtual void resume ();
400 virtual bool is_suspended () const;
402 virtual void add (const char * name,
403 SGSubsystem * subsystem,
404 GroupType group = GENERAL,
405 double min_time_sec = 0);
408 * remove a subsystem, and return a pointer to it.
409 * returns NULL if the subsystem was not found.
411 virtual SGSubsystem* remove(const char* name);
413 virtual SGSubsystemGroup * get_group (GroupType group);
415 virtual SGSubsystem * get_subsystem(const std::string &name) const;
417 void collectDebugTiming(bool collect);
421 SGSubsystemGroup _groups[MAX_GROUPS];
423 typedef std::map<std::string, SGSubsystem*> SubsystemDict;
424 SubsystemDict _subsystem_map;
430 #endif // __SUBSYSTEM_MGR_HXX