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
  48     /// The rti backends connect arguments, depends on the version
  49     const std::list<std::string>& getConnectArguments() const;
  50     bool setConnectArguments(const std::list<std::string>& connectArguments);
  51
  52     /// If true try to create on join and try to destroy on resign
  53     bool getCreateFederationExecution() const;
  54     bool setCreateFederationExecution(bool createFederationExecution);
  55
  56     /// The federation execution name to use on create, join and destroy
  57     const std::string& getFederationExecutionName() const;
  58     bool setFederationExecutionName(const std::string& federationExecutionName);
  59
  60     /// The federation object model name to use on create and possibly join
  61     const std::string& getFederationObjectModel() const;
  62     bool setFederationObjectModel(const std::string& federationObjectModel);
  63
  64     /// The federate type used on join
  65     const std::string& getFederateType() const;
  66     bool setFederateType(const std::string& federateType);
  67
  68     /// The federate name possibly used on join
  69     const std::string& getFederateName() const;
  70     bool setFederateName(const std::string& federateName);
  71
  72     /// connect to an rti
  73     bool connect(Version version, const std::list<std::string>& stringList);
  74     bool connect();
  75     bool disconnect();
  76
  77     /// Create a federation execution
  78     /// Semantically this methods should be static,
  79     /// but the nonstatic case could reuse the connection to the server
  80     bool createFederationExecution(const std::string& federation, const std::string& objectModel);
  81     bool destroyFederationExecution(const std::string& federation);
  82     bool createFederationExecution();
  83     bool destroyFederationExecution();
  84
  85     /// Join with federateType the federation execution
  86     bool join(const std::string& federateType, const std::string& federation);
  87     bool join();
  88     bool resign();
  89
  90     /// Try to create and join the federation execution.
  91     bool createJoinFederationExecution();
  92     bool resignDestroyFederationExecution();
  93
  94
  95     /// Time management
  96
  97     /// If set to true, time constrained mode is entered on init
  98     bool getTimeConstrained() const;
  99     bool setTimeConstrained(bool timeConstrained);
 100
 101     /// If set to true, time advance is constrained by the local system clock
 102     bool getTimeConstrainedByLocalClock() const;
 103     bool setTimeConstrainedByLocalClock(bool timeConstrainedByLocalClock);
 104
 105     /// If set to true, time regulation mode is entered on init
 106     bool getTimeRegulating() const;
 107     bool setTimeRegulating(bool timeRegulating);
 108
 109     /// If set to a non zero value, this federate leads the federations
 110     /// locical time advance by this amount of time.
 111     const SGTimeStamp& getLeadTime() const;
 112     bool setLeadTime(const SGTimeStamp& leadTime);
 113
 114     /// The time increment for use in the default update method.
 115     const SGTimeStamp& getTimeIncrement() const;
 116     bool setTimeIncrement(const SGTimeStamp& timeIncrement);
 117
 118     /// Actually enable time constrained mode.
 119     /// This method blocks until time constrained mode is enabled.
 120     bool enableTimeConstrained();
 121     /// Actually disable time constrained mode.
 122     bool disableTimeConstrained();
 123
 124     /// Actually enable time constrained by local clock mode.
 125     bool enableTimeConstrainedByLocalClock();
 126
 127     /// Actually enable time regulation mode.
 128     /// This method blocks until time regulation mode is enabled.
 129     bool enableTimeRegulation(const SGTimeStamp& lookahead);
 130     bool enableTimeRegulation();
 131     /// Actually disable time regulation mode.
 132     bool disableTimeRegulation();
 133     /// Actually modify the lookahead time.
 134     bool modifyLookahead(const SGTimeStamp& lookahead);
 135
 136     /// Advance the logical time by the given time increment.
 137     /// Depending on the time constrained mode, this might
 138     /// block until the time advance is granted.
 139     bool timeAdvanceBy(const SGTimeStamp& timeIncrement);
 140     /// Advance the logical time to the given time.
 141     /// Depending on the time constrained mode, this might
 142     /// block until the time advance is granted.
 143     bool timeAdvance(const SGTimeStamp& timeStamp);
 144     /// Advance the logical time as far as time advances are available.
 145     /// This call should not block and advance the logical time
 146     /// as far as currently possible.
 147     bool timeAdvanceAvailable();
 148
 149     /// Get the current federates time
 150     bool queryFederateTime(SGTimeStamp& timeStamp);
 151     /// Get the current federates lookahead
 152     bool queryLookahead(SGTimeStamp& timeStamp);
 153
 154     /// Process one messsage
 155     bool processMessage();
 156     /// Process one message but do not wait longer than the relative timeout.
 157     bool processMessage(const SGTimeStamp& timeout);
 158     /// Process messages until the federate can proceed with the
 159     /// next simulation step. That is flush all pending messages and
 160     /// depending on the time constrained mode process messages until
 161     /// a pending time advance is granted.
 162     bool processMessages();
 163
 164     /// Legacy tick call - deprecated
 165     bool tick(const double& minimum, const double& maximum);
 166
 167     class ObjectModelFactory {
 168     public:
 169         virtual ~ObjectModelFactory()
 170         { }
 171
 172         virtual HLAObjectClass* createObjectClass(const std::string& name, HLAFederate& federate)
 173         { return federate.createObjectClass(name); }
 174         virtual bool subscribeObjectClass(const std::string& objectClassName, const std::string& sharing)
 175         { return sharing.find("Subscribe") != std::string::npos; }
 176         virtual bool publishObjectClass(const std::string& objectClassName, const std::string& sharing)
 177         { return sharing.find("Publish") != std::string::npos; }
 178         virtual bool subscribeAttribute(const std::string& objectClassName, const std::string& attributeName, const std::string& sharing)
 179         { return sharing.find("Subscribe") != std::string::npos; }
 180         virtual bool publishAttribute(const std::string& objectClassName, const std::string& attributeName, const std::string& sharing)
 181         { return sharing.find("Publish") != std::string::npos; }
 182
 183     };
 184
 185     /// Read an omt xml file - deprecated
 186     bool readObjectModelTemplate(const std::string& objectModel,
 187                                  ObjectModelFactory& objectModelFactory);
 188
 189     /// Read an rti1.3 omt xml file
 190     bool readRTI13ObjectModelTemplate(const std::string& objectModel);
 191     /// Read an rti1516 omt xml file
 192     bool readRTI1516ObjectModelTemplate(const std::string& objectModel);
 193     /// Read an rti1516e omt xml file
 194     bool readRTI1516EObjectModelTemplate(const std::string& objectModel);
 195
 196     /// Is called past a successful join to populate the rti classes
 197     bool resolveObjectModel();
 198
 199     /// Access data types
 200     const HLADataType* getDataType(const std::string& name) const;
 201     // virtual const HLADataType* createDataType(const std::string& name);
 202     bool insertDataType(const std::string& name, const SGSharedPtr<HLADataType>& dataType);
 203     void recomputeDataTypeAlignment();
 204
 205     /// Get the interaction class of a given name
 206     HLAInteractionClass* getInteractionClass(const std::string& name);
 207     const HLAInteractionClass* getInteractionClass(const std::string& name) const;
 208     /// Default create function. Creates a default interaction class
 209     virtual HLAInteractionClass* createInteractionClass(const std::string& name);
 210
 211     /// Get the object class of a given name
 212     HLAObjectClass* getObjectClass(const std::string& name);
 213     const HLAObjectClass* getObjectClass(const std::string& name) const;
 214     /// Default create function. Creates a default object class
 215     virtual HLAObjectClass* createObjectClass(const std::string& name);
 216
 217     /// Get the object instance of a given name
 218     HLAObjectInstance* getObjectInstance(const std::string& name);
 219     const HLAObjectInstance* getObjectInstance(const std::string& name) const;
 220     virtual HLAObjectInstance* createObjectInstance(HLAObjectClass* objectClass, const std::string& name);
 221
 222     /// Tells the main exec loop to continue or not.
 223     void setDone(bool done);
 224     bool getDone() const;
 225
 226     /// The user overridable slot that is called to set up an object model
 227     /// By default, depending on the set up rti version, the apropriate
 228     ///  bool read{RTI13,RTI1516,RTI1516E}ObjectModelTemplate(const std::string& objectModel);
 229     /// method is called.
 230     /// Note that the RTI13 files do not contain any information about the data types.
 231     /// A user needs to set up the data types and assign them to the object classes/
 232     /// interaction classes theirselves.
 233     /// Past reading the object model, it is still possible to change the subscription/publication
 234     /// types without introducing traffic on the backend rti.
 235     virtual bool readObjectModel();
 236
 237     virtual bool subscribe();
 238     virtual bool publish();
 239
 240     virtual bool init();
 241     virtual bool update();
 242     virtual bool shutdown();
 243
 244     virtual bool exec();
 245
 246 private:
 247     HLAFederate(const HLAFederate&);
 248     HLAFederate& operator=(const HLAFederate&);
 249
 250     void _clearRTI();
 251
 252     /// Internal helpers for interaction classes
 253     bool _insertInteractionClass(const SGSharedPtr<HLAInteractionClass>& interactionClass);
 254     /// Internal helpers for object classes
 255     bool _insertObjectClass(const SGSharedPtr<HLAObjectClass>& objectClass);
 256     /// Internal helpers for object instances
 257     bool _insertObjectInstance(const SGSharedPtr<HLAObjectInstance>& objectInstance);
 258     void _eraseObjectInstance(const std::string& name);
 259
 260     /// The underlying interface to the rti implementation
 261     SGSharedPtr<RTIFederate> _rtiFederate;
 262
 263     /// Parameters required to connect to an rti
 264     Version _version;
 265     std::list<std::string> _connectArguments;
 266
 267     /// Parameters for the federation execution
 268     std::string _federationExecutionName;
 269     std::string _federationObjectModel;
 270     bool _createFederationExecution;
 271
 272     /// Parameters for the federate
 273     std::string _federateType;
 274     std::string _federateName;
 275
 276     /// Time management related parameters
 277     /// If true, the federate is expected to enter time constrained mode
 278     bool _timeConstrained;
 279     /// If true, the federate is expected to enter time regulating mode
 280     bool _timeRegulating;
 281     /// The amount of time this federate leads the others.
 282     SGTimeStamp _leadTime;
 283     /// The regular time increment we do on calling update()
 284     SGTimeStamp _timeIncrement;
 285     /// The reference system time at initialization time.
 286     /// Is used to implement being time constrained on the
 287     /// local system time.
 288     bool _timeConstrainedByLocalClock;
 289     SGTimeStamp _localClockOffset;
 290
 291     /// If true the exec method returns.
 292     bool _done;
 293
 294     /// The Data Types by name
 295     typedef std::map<std::string, SGSharedPtr<HLADataType> > DataTypeMap;
 296     DataTypeMap _dataTypeMap;
 297
 298     /// The Interaction Classes by name
 299     typedef std::map<std::string, SGSharedPtr<HLAInteractionClass> > InteractionClassMap;
 300     InteractionClassMap _interactionClassMap;
 301
 302     /// The Object Classes by name
 303     typedef std::map<std::string, SGSharedPtr<HLAObjectClass> > ObjectClassMap;
 304     ObjectClassMap _objectClassMap;
 305
 306     /// The Object Instances by name
 307     typedef std::map<std::string, SGSharedPtr<HLAObjectInstance> > ObjectInstanceMap;
 308     ObjectInstanceMap _objectInstanceMap;
 309     /// The Object Instances by name, the ones that have an explicit given name, may be not yet registered
 310     // ObjectInstanceMap _explicitNamedObjectInstanceMap;
 311
 312     friend class HLAInteractionClass;
 313     friend class HLAObjectClass;
 314     friend class HLAObjectInstance;
 315 };
 316
 317 } // namespace simgear
 318
 319 #endif