simgear/hla/HLAFederate.hxx

   1 // Copyright (C) 2009 - 2012  Mathias Froehlich - Mathias.Froehlich@web.de
   2 //
   3 // This library is free software; you can redistribute it and/or
   4 // modify it under the terms of the GNU Library General Public
   5 // License as published by the Free Software Foundation; either
   6 // version 2 of the License, or (at your option) any later version.
   7 //
   8 // This library is distributed in the hope that it will be useful,
   9 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  10 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11 // Library General Public License for more details.
  12 //
  13 // You should have received a copy of the GNU General Public License
  14 // along with this program; if not, write to the Free Software
  15 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  16 //
  17
  18 #ifndef HLAFederate_hxx
  19 #define HLAFederate_hxx
  20
  21 #include <map>
  22
  23 #include "HLAObjectInstance.hxx"
  24 #include "HLAObjectClass.hxx"
  25 #include "HLAInteractionClass.hxx"
  26
  27 class SGTimeStamp;
  28
  29 namespace simgear {
  30
  31 class RTIFederate;
  32
  33 class HLAFederate : public SGWeakReferenced {
  34 public:
  35     HLAFederate();
  36     virtual ~HLAFederate();
  37
  38     enum Version {
  39         RTI13,
  40         RTI1516,
  41         RTI1516E
  42     };
  43
  44     /// The rti version backend to connect
  45     Version getVersion() const;
  46     bool setVersion(HLAFederate::Version version);
  47     bool setVersion(const std::string& version);
  48
  49     /// The rti backends connect arguments, depends on the version
  50     const std::list<std::string>& getConnectArguments() const;
  51     bool setConnectArguments(const std::list<std::string>& connectArguments);
  52
  53     /// If true try to create on join and try to destroy on resign
  54     bool getCreateFederationExecution() const;
  55     bool setCreateFederationExecution(bool createFederationExecution);
  56
  57     /// The federation execution name to use on create, join and destroy
  58     const std::string& getFederationExecutionName() const;
  59     bool setFederationExecutionName(const std::string& federationExecutionName);
  60
  61     /// The federation object model name to use on create and possibly join
  62     const std::string& getFederationObjectModel() const;
  63     bool setFederationObjectModel(const std::string& federationObjectModel);
  64
  65     /// The federate type used on join
  66     const std::string& getFederateType() const;
  67     bool setFederateType(const std::string& federateType);
  68
  69     /// The federate name possibly used on join
  70     const std::string& getFederateName() const;
  71     bool setFederateName(const std::string& federateName);
  72
  73     /// connect to an rti
  74     bool connect(Version version, const std::list<std::string>& stringList);
  75     bool connect();
  76     bool disconnect();
  77
  78     /// Create a federation execution
  79     /// Semantically this methods should be static,
  80     /// but the nonstatic case could reuse the connection to the server
  81     bool createFederationExecution(const std::string& federation, const std::string& objectModel);
  82     bool destroyFederationExecution(const std::string& federation);
  83     bool createFederationExecution();
  84     bool destroyFederationExecution();
  85
  86     /// Join with federateType the federation execution
  87     bool join(const std::string& federateType, const std::string& federation);
  88     bool join();
  89     bool resign();
  90
  91     /// Try to create and join the federation execution.
  92     bool createJoinFederationExecution();
  93     bool resignDestroyFederationExecution();
  94
  95
  96     /// Time management
  97
  98     /// If set to true, time constrained mode is entered on init
  99     bool getTimeConstrained() const;
 100     bool setTimeConstrained(bool timeConstrained);
 101
 102     /// If set to true, time advance is constrained by the local system clock
 103     bool getTimeConstrainedByLocalClock() const;
 104     bool setTimeConstrainedByLocalClock(bool timeConstrainedByLocalClock);
 105
 106     /// If set to true, time regulation mode is entered on init
 107     bool getTimeRegulating() const;
 108     bool setTimeRegulating(bool timeRegulating);
 109
 110     /// If set to a non zero value, this federate leads the federations
 111     /// locical time advance by this amount of time.
 112     const SGTimeStamp& getLeadTime() const;
 113     bool setLeadTime(const SGTimeStamp& leadTime);
 114
 115     /// The time increment for use in the default update method.
 116     const SGTimeStamp& getTimeIncrement() const;
 117     bool setTimeIncrement(const SGTimeStamp& timeIncrement);
 118
 119     /// Actually enable time constrained mode.
 120     /// This method blocks until time constrained mode is enabled.
 121     bool enableTimeConstrained();
 122     /// Actually disable time constrained mode.
 123     bool disableTimeConstrained();
 124
 125     /// Actually enable time constrained by local clock mode.
 126     bool enableTimeConstrainedByLocalClock();
 127
 128     /// Actually enable time regulation mode.
 129     /// This method blocks until time regulation mode is enabled.
 130     bool enableTimeRegulation(const SGTimeStamp& lookahead);
 131     bool enableTimeRegulation();
 132     /// Actually disable time regulation mode.
 133     bool disableTimeRegulation();
 134     /// Actually modify the lookahead time.
 135     bool modifyLookahead(const SGTimeStamp& lookahead);
 136
 137     /// Advance the logical time by the given time increment.
 138     /// Depending on the time constrained mode, this might
 139     /// block until the time advance is granted.
 140     bool timeAdvanceBy(const SGTimeStamp& timeIncrement);
 141     /// Advance the logical time to the given time.
 142     /// Depending on the time constrained mode, this might
 143     /// block until the time advance is granted.
 144     bool timeAdvance(const SGTimeStamp& timeStamp);
 145     /// Advance the logical time as far as time advances are available.
 146     /// This call should not block and advance the logical time
 147     /// as far as currently possible.
 148     bool timeAdvanceAvailable();
 149
 150     /// Get the current federates time
 151     bool queryFederateTime(SGTimeStamp& timeStamp);
 152     /// Get the current federates lookahead
 153     bool queryLookahead(SGTimeStamp& timeStamp);
 154
 155     /// Process one messsage
 156     bool processMessage();
 157     /// Process one message but do not wait longer than the relative timeout.
 158     bool processMessage(const SGTimeStamp& timeout);
 159     /// Process messages until the federate can proceed with the
 160     /// next simulation step. That is flush all pending messages and
 161     /// depending on the time constrained mode process messages until
 162     /// a pending time advance is granted.
 163     bool processMessages();
 164
 165     /// Read an rti1.3 omt xml file
 166     bool readRTI13ObjectModelTemplate(const std::string& objectModel);
 167     /// Read an rti1516 omt xml file
 168     bool readRTI1516ObjectModelTemplate(const std::string& objectModel);
 169     /// Read an rti1516e omt xml file
 170     bool readRTI1516EObjectModelTemplate(const std::string& objectModel);
 171
 172     /// Is called past a successful join to populate the rti classes
 173     bool resolveObjectModel();
 174
 175     /// Access data types
 176     const HLADataType* getDataType(const std::string& name) const;
 177     // virtual const HLADataType* createDataType(const std::string& name);
 178     bool insertDataType(const std::string& name, const SGSharedPtr<HLADataType>& dataType);
 179     void recomputeDataTypeAlignment();
 180
 181     /// Get the interaction class of a given name
 182     HLAInteractionClass* getInteractionClass(const std::string& name);
 183     const HLAInteractionClass* getInteractionClass(const std::string& name) const;
 184     /// Default create function. Creates a default interaction class
 185     virtual HLAInteractionClass* createInteractionClass(const std::string& name);
 186
 187     /// Get the object class of a given name
 188     HLAObjectClass* getObjectClass(const std::string& name);
 189     const HLAObjectClass* getObjectClass(const std::string& name) const;
 190     /// Default create function. Creates a default object class
 191     virtual HLAObjectClass* createObjectClass(const std::string& name);
 192
 193     /// Get the object instance of a given name
 194     HLAObjectInstance* getObjectInstance(const std::string& name);
 195     const HLAObjectInstance* getObjectInstance(const std::string& name) const;
 196     virtual HLAObjectInstance* createObjectInstance(HLAObjectClass* objectClass, const std::string& name);
 197
 198     /// Tells the main exec loop to continue or not.
 199     void setDone(bool done);
 200     bool getDone() const;
 201
 202     /// The user overridable slot that is called to set up an object model
 203     /// By default, depending on the set up rti version, the apropriate
 204     ///  bool read{RTI13,RTI1516,RTI1516E}ObjectModelTemplate(const std::string& objectModel);
 205     /// method is called.
 206     /// Note that the RTI13 files do not contain any information about the data types.
 207     /// A user needs to set up the data types and assign them to the object classes/
 208     /// interaction classes theirselves.
 209     /// Past reading the object model, it is still possible to change the subscription/publication
 210     /// types without introducing traffic on the backend rti.
 211     virtual bool readObjectModel();
 212
 213     virtual bool subscribe();
 214     virtual bool publish();
 215
 216     virtual bool init();
 217     virtual bool update();
 218     virtual bool shutdown();
 219
 220     virtual bool exec();
 221
 222 private:
 223     HLAFederate(const HLAFederate&);
 224     HLAFederate& operator=(const HLAFederate&);
 225
 226     void _clearRTI();
 227
 228     /// Internal helpers for interaction classes
 229     bool _insertInteractionClass(HLAInteractionClass* interactionClass);
 230     /// Internal helpers for object classes
 231     bool _insertObjectClass(HLAObjectClass* objectClass);
 232     /// Internal helpers for object instances
 233     bool _insertObjectInstance(HLAObjectInstance* objectInstance);
 234     void _eraseObjectInstance(const std::string& name);
 235
 236     /// The underlying interface to the rti implementation
 237     SGSharedPtr<RTIFederate> _rtiFederate;
 238
 239     /// Parameters required to connect to an rti
 240     Version _version;
 241     std::list<std::string> _connectArguments;
 242
 243     /// Parameters for the federation execution
 244     std::string _federationExecutionName;
 245     std::string _federationObjectModel;
 246     bool _createFederationExecution;
 247
 248     /// Parameters for the federate
 249     std::string _federateType;
 250     std::string _federateName;
 251
 252     /// Time management related parameters
 253     /// If true, the federate is expected to enter time constrained mode
 254     bool _timeConstrained;
 255     /// If true, the federate is expected to enter time regulating mode
 256     bool _timeRegulating;
 257     /// The amount of time this federate leads the others.
 258     SGTimeStamp _leadTime;
 259     /// The regular time increment we do on calling update()
 260     SGTimeStamp _timeIncrement;
 261     /// The reference system time at initialization time.
 262     /// Is used to implement being time constrained on the
 263     /// local system time.
 264     bool _timeConstrainedByLocalClock;
 265     SGTimeStamp _localClockOffset;
 266
 267     /// If true the exec method returns.
 268     bool _done;
 269
 270     /// The Data Types by name
 271     typedef std::map<std::string, SGSharedPtr<HLADataType> > DataTypeMap;
 272     DataTypeMap _dataTypeMap;
 273
 274     /// The Interaction Classes by name
 275     typedef std::map<std::string, SGSharedPtr<HLAInteractionClass> > InteractionClassMap;
 276     InteractionClassMap _interactionClassMap;
 277
 278     /// The Object Classes by name
 279     typedef std::map<std::string, SGSharedPtr<HLAObjectClass> > ObjectClassMap;
 280     ObjectClassMap _objectClassMap;
 281
 282     /// The Object Instances by name
 283     typedef std::map<std::string, SGSharedPtr<HLAObjectInstance> > ObjectInstanceMap;
 284     ObjectInstanceMap _objectInstanceMap;
 285     /// The Object Instances by name, the ones that have an explicit given name, may be not yet registered
 286     // ObjectInstanceMap _explicitNamedObjectInstanceMap;
 287
 288     friend class HLAInteractionClass;
 289     friend class HLAObjectClass;
 290     friend class HLAObjectInstance;
 291 };
 292
 293 } // namespace simgear
 294
 295 #endif