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     /// Legacy tick call - deprecated
 166     bool tick(const double& minimum, const double& maximum);
 167
 168     class ObjectModelFactory {
 169     public:
 170         virtual ~ObjectModelFactory()
 171         { }
 172
 173         virtual HLAObjectClass* createObjectClass(const std::string& name, HLAFederate& federate)
 174         { return federate.createObjectClass(name); }
 175         virtual bool subscribeObjectClass(const std::string& objectClassName, const std::string& sharing)
 176         { return sharing.find("Subscribe") != std::string::npos; }
 177         virtual bool publishObjectClass(const std::string& objectClassName, const std::string& sharing)
 178         { return sharing.find("Publish") != std::string::npos; }
 179         virtual bool subscribeAttribute(const std::string& objectClassName, const std::string& attributeName, const std::string& sharing)
 180         { return sharing.find("Subscribe") != std::string::npos; }
 181         virtual bool publishAttribute(const std::string& objectClassName, const std::string& attributeName, const std::string& sharing)
 182         { return sharing.find("Publish") != std::string::npos; }
 183
 184     };
 185
 186     /// Read an omt xml file - deprecated
 187     bool readObjectModelTemplate(const std::string& objectModel,
 188                                  ObjectModelFactory& objectModelFactory);
 189
 190     /// Read an rti1.3 omt xml file
 191     bool readRTI13ObjectModelTemplate(const std::string& objectModel);
 192     /// Read an rti1516 omt xml file
 193     bool readRTI1516ObjectModelTemplate(const std::string& objectModel);
 194     /// Read an rti1516e omt xml file
 195     bool readRTI1516EObjectModelTemplate(const std::string& objectModel);
 196
 197     /// Is called past a successful join to populate the rti classes
 198     bool resolveObjectModel();
 199
 200     /// Access data types
 201     const HLADataType* getDataType(const std::string& name) const;
 202     // virtual const HLADataType* createDataType(const std::string& name);
 203     bool insertDataType(const std::string& name, const SGSharedPtr<HLADataType>& dataType);
 204     void recomputeDataTypeAlignment();
 205
 206     /// Get the interaction class of a given name
 207     HLAInteractionClass* getInteractionClass(const std::string& name);
 208     const HLAInteractionClass* getInteractionClass(const std::string& name) const;
 209     /// Default create function. Creates a default interaction class
 210     virtual HLAInteractionClass* createInteractionClass(const std::string& name);
 211
 212     /// Get the object class of a given name
 213     HLAObjectClass* getObjectClass(const std::string& name);
 214     const HLAObjectClass* getObjectClass(const std::string& name) const;
 215     /// Default create function. Creates a default object class
 216     virtual HLAObjectClass* createObjectClass(const std::string& name);
 217
 218     /// Get the object instance of a given name
 219     HLAObjectInstance* getObjectInstance(const std::string& name);
 220     const HLAObjectInstance* getObjectInstance(const std::string& name) const;
 221     virtual HLAObjectInstance* createObjectInstance(HLAObjectClass* objectClass, const std::string& name);
 222
 223     /// Tells the main exec loop to continue or not.
 224     void setDone(bool done);
 225     bool getDone() const;
 226
 227     /// The user overridable slot that is called to set up an object model
 228     /// By default, depending on the set up rti version, the apropriate
 229     ///  bool read{RTI13,RTI1516,RTI1516E}ObjectModelTemplate(const std::string& objectModel);
 230     /// method is called.
 231     /// Note that the RTI13 files do not contain any information about the data types.
 232     /// A user needs to set up the data types and assign them to the object classes/
 233     /// interaction classes theirselves.
 234     /// Past reading the object model, it is still possible to change the subscription/publication
 235     /// types without introducing traffic on the backend rti.
 236     virtual bool readObjectModel();
 237
 238     virtual bool subscribe();
 239     virtual bool publish();
 240
 241     virtual bool init();
 242     virtual bool update();
 243     virtual bool shutdown();
 244
 245     virtual bool exec();
 246
 247 private:
 248     HLAFederate(const HLAFederate&);
 249     HLAFederate& operator=(const HLAFederate&);
 250
 251     void _clearRTI();
 252
 253     /// Internal helpers for interaction classes
 254     bool _insertInteractionClass(const SGSharedPtr<HLAInteractionClass>& interactionClass);
 255     /// Internal helpers for object classes
 256     bool _insertObjectClass(const SGSharedPtr<HLAObjectClass>& objectClass);
 257     /// Internal helpers for object instances
 258     bool _insertObjectInstance(const SGSharedPtr<HLAObjectInstance>& objectInstance);
 259     void _eraseObjectInstance(const std::string& name);
 260
 261     /// The underlying interface to the rti implementation
 262     SGSharedPtr<RTIFederate> _rtiFederate;
 263
 264     /// Parameters required to connect to an rti
 265     Version _version;
 266     std::list<std::string> _connectArguments;
 267
 268     /// Parameters for the federation execution
 269     std::string _federationExecutionName;
 270     std::string _federationObjectModel;
 271     bool _createFederationExecution;
 272
 273     /// Parameters for the federate
 274     std::string _federateType;
 275     std::string _federateName;
 276
 277     /// Time management related parameters
 278     /// If true, the federate is expected to enter time constrained mode
 279     bool _timeConstrained;
 280     /// If true, the federate is expected to enter time regulating mode
 281     bool _timeRegulating;
 282     /// The amount of time this federate leads the others.
 283     SGTimeStamp _leadTime;
 284     /// The regular time increment we do on calling update()
 285     SGTimeStamp _timeIncrement;
 286     /// The reference system time at initialization time.
 287     /// Is used to implement being time constrained on the
 288     /// local system time.
 289     bool _timeConstrainedByLocalClock;
 290     SGTimeStamp _localClockOffset;
 291
 292     /// If true the exec method returns.
 293     bool _done;
 294
 295     /// The Data Types by name
 296     typedef std::map<std::string, SGSharedPtr<HLADataType> > DataTypeMap;
 297     DataTypeMap _dataTypeMap;
 298
 299     /// The Interaction Classes by name
 300     typedef std::map<std::string, SGSharedPtr<HLAInteractionClass> > InteractionClassMap;
 301     InteractionClassMap _interactionClassMap;
 302
 303     /// The Object Classes by name
 304     typedef std::map<std::string, SGSharedPtr<HLAObjectClass> > ObjectClassMap;
 305     ObjectClassMap _objectClassMap;
 306
 307     /// The Object Instances by name
 308     typedef std::map<std::string, SGSharedPtr<HLAObjectInstance> > ObjectInstanceMap;
 309     ObjectInstanceMap _objectInstanceMap;
 310     /// The Object Instances by name, the ones that have an explicit given name, may be not yet registered
 311     // ObjectInstanceMap _explicitNamedObjectInstanceMap;
 312
 313     friend class HLAInteractionClass;
 314     friend class HLAObjectClass;
 315     friend class HLAObjectInstance;
 316 };
 317
 318 } // namespace simgear
 319
 320 #endif