1. ©MAK Technologies, Inc. The Dynamic-Link-Compatible C++ RTI API for IEEE 1516 Len Granowetter MÄK Technologies lengrano@mak.com 617 876-8085 x121

2. © MÄK Technologies, Inc. The Promise of HLA Key goal of HLA: to allow simulation applications to be written independently of the mechanism they use to exchange data A federation chooses an appropriate RTI based on requirements of federation Requires federates to be easily portable among different RTI implementations In HLA 1.3, this worked reasonably well –Many federates work with MÄK RTI, Pitch RTI, or RTI NG

3. © MÄK Technologies, Inc. Federate LRC RTI Exec RTI It must be easy for federations to swap RTIs RTI is a Federation-Wide Choice

4. © MÄK Technologies, Inc. The Problem Original IEEE 1516 C++ API did not support Dynamic-Link-Compatibility among RTIs Not possible to swap among RTIs without recompiling or re-linking –End-user not empowered to choose RTI – must ask federate developer to rebuild –Federate “locked” into choice of specific RTI –Tool vendors must build separate version of each tool for each RTI they want to support API not fully-defined –RTI vendors required to “fill in the blanks” –In effect, each RTI has its own API

5. © MÄK Technologies, Inc. SISO DLC HLA API PDG Led by representatives of MÄK, Pitch, and the RTI NG Team (SAIC/VTC/DAS) Goals –Develop an alternative mapping of semantics of the IEEE 1516 Interface Specification to a C++ API – to support Dynamic Link Compatibility –Make IEEE 1516 less daunting Use more familiar C++ idioms (as in HLA 1.3) Simplify from 42 files down to 15 Used the API defined by DoD Interpretations, version 2.0, as a starting point

6. © MÄK Technologies, Inc. Other DLC APIs DLC Java API for 1516 –Additions only (back-compatible with original) –Allows choice of implementation at run-time –Adds EncodingHelpers DLC C++ and Java APIs for HLA 1.3 –Already balloted and approved by SAC –Less important because original API did not preclude Dynamic Link Compatibility

7. © MÄK Technologies, Inc. Handling Handles Handles provide a quick, easy way to refer to more complex objects –ObjectInstanceHandle, AttributeHandle, etc. HLA 1.3 API used unsigned longs In 1516: Desire for implementation flexibility –64-bit handles allow LRCs to choose handles independently –Small handles needed for low bandwidth RTI –Pointer to RTI-internal object gains efficiency

8. © MÄK Technologies, Inc. Handles in Original IEEE 1516 API template class Handle {... }; typedef Handle< ObjectClassHandleImplementationType> ObjectClassHandle; Definition of ObjectClassHandleImplementationType provided by RTI-implementation-specific header file and compiled into federate code (breaking DLC)

9. © MÄK Technologies, Inc. The Abstract Base Class Approach API defines abstract base classes for handles –RTI implementation provides subclasses –Factory used to construct right kind of handle –Similar to the way RTIambassador works Problem: Precludes passing handles by value –Derived class portion is “sliced” off –Must use pointers to handles - defeats the whole purpose of handles (avoiding memory management), and leads to confusing code

10. © MÄK Technologies, Inc. Other Template-based Approaches Several variations considered; all had same problem –Template instantiation takes place at compile time, so implementation-specific details get compiled into federate executable

11. © MÄK Technologies, Inc. Solution: The “pimpl” Idiom Each kind of handle represented in the API as a concrete class (e.g. AttributeHandle ) –Pointer to separate implementation class is included as a member variable –Operators of AttributeHandle are non- virtual; call through to implementation class –API only needs pointer to implementation class Definition of implementation class omitted (provided by implementation) Forward declaration used in its place

12. © MÄK Technologies, Inc. // Forward declaration class AttributeHandleImplementation; class AttributeHandle { public: // Should call _impl->operator== bool operator==( const AttributeHandle& rhs) const;... protected: AttributeHandleImplementation*_impl; };

13. © MÄK Technologies, Inc. Benefits of “pimpl” Solution Supports DLC and allows for flexibility in implementation Definition of implementation-specific classes kept out of API –Not compiled into federate code –AttributeHandleImplementation will be resolved at run-time to whatever version is present in RTI DLL (or DSO) Handles are compact, can be passed by value, have intuitive syntax, are efficient to copy

14. © MÄK Technologies, Inc. Values Implemented through templates in original API –Breaks DLC, just like Handles DLC PDG considered simple concrete classes –Do we really need implementation flexibility? –Yes, to allow reference counting, etc. Settled on“pimpl” solution, like Handles –Single VariableLengthData class used for all kinds of Values –API allows tradeoffs between efficiency and memory management responsibility

15. © MÄK Technologies, Inc. Logical Time and Time Intervals Do we need separate classes for LogicalTime and LogicalTimeInterval? –Yes. –Adding a LogicalTimeInterval to a LogicalTime makes sense –Adding two LogicalTimes does not

16. © MÄK Technologies, Inc. Choosing a Time Implementation In both 1.3 and 1516, implementation of Time is provided by federation In 1.3, static factory method in libfedtime In 1516, desire to support multiple Time implementations per application –A single application may join multiple federations, each with own Time implementation –In original IEEE 1516 API, federate passes factory instance to joinFederationExecution() –Problem 1: No way to pass this choice to rtiexec –Problem 2: Potential for inconsistent choices

17. © MÄK Technologies, Inc. Choosing a Time Implementation Solution: A federate passes the name of Time implementation, instead of a factory –LogicalTimeFactoryFactory returns instance of factory associated with this name –Name can be passed to rtiexec (so it can find the appropriate factory too) –To eliminate inconsistent choices by different federates, pass the name to createFederationExecution() instead of join()

18. © MÄK Technologies, Inc. Enumerations HLA Specification requires 9 enumerated types –TransportationType, OrderType, etc. Represented as C++ classes in original IEEE 1516 API –Values were global const instances –Based on incorrect assumption that C++ enumerations did not provide type safety For DLC API, used simple C++ enums Reduced complexity of API by 1500 lines of code and 18 files –With no real loss of type safety

19. © MÄK Technologies, Inc. Porting From Original 1516 API Besides namespace change, most class, file, and function names remain the same –Most implementation changes (even the major ones) are transparent to federate code –No changes to RTIambassador or FederateAmbassador function names Changes that affect federate code –Some functions return by value, not auto_ptr –AttributeValue, ParameterValue replaced by VariableLengthValue –LogicalTime::isLessThan replaced by operator<, etc.

20. © MÄK Technologies, Inc. Porting from HLA 1.3 API Porting necessary to switch to 1516 semantics –Tick() replaced by evokeMultipleCallbacks() –STL Maps used for AttributeHandle/Value pairs –FedTime is now called LogicalTime Easier to go to DLC API than to original 1516 –DLC API is closer to style of 1.3 API –Familiar pass-by-reference or value semantics, rather than auto_ptrs –LogicalTime has familiar operators –No templates or implementation-specific files –2900 lines of code, instead of 5200

21. © MÄK Technologies, Inc. Status and Future DLC API for IEEE 1516 successfully balloted by PDG (only 1 rejection out of 41 ballots cast) –Sent to SAC for approval as SISO Standard Full implementation already exists (MÄK RTI) DMSO Verification Tools have been ported –MÄK RTI currently undergoing testing HLA Evolved expected to adopt DLC API for next version of IEEE 1516 Standard –DLC API incorporates the DoD Interpretations, so no conflict exists