5.9 - General HLA Issues

Table of Contents

• 5.9.1 Time Stamps
• 5.9.2 Registering and Responding to Synchronization Points
  • 5.9.2.1 Responding to Synchronization Points Automatically
• 5.9.3 Time Management
  • 5.9.3.1 Federation Time
  • 5.9.3.2 Sending Time Stamp Order (TSO) Messages
  • 5.9.3.3 Receiving TSO Messages
  • 5.9.3.4 Using Callbacks
  • 5.9.3.5 Converting FedTime to DtTime
• 5.9.4 VR-Link Calls to RTI Services

The following sections discuss general HLA issues.

5.9.1 Time Stamps

You can set and inspect an HLA DtStateMsg or DtInteraction's time stamp with the setTimeStamp() and timeStamp() functions. These work the same way as the DIS DtPdu's function – taking a time, and a time stamp type (either DtTimeStampRelative or DtTimeStampAbsolute).

DtExerciseConn::sendStamped() sets the time stamp of an outgoing HLA message to the current time, with the type returned by DtExerciseConn::timeStampType().

Consistent with the RPR FOM convention, VR-Link's sending functions encode the time in the "tag" string argument to the RTI's sendInteraction() and updateAttribute-Values() calls. The time is encoded as the 8-byte ASCII representation of the hex number that would have been sent in a DIS time stamp.

If you do not want to use this convention, use DtInteraction::setTagIsAsciiTime(false) and DtStateMsg::setTagIsAsciiTime(false). If you do this, your time stamps will not be sent, because the RTI does not provide a mechanism for sending time stamps along with your messages unless you are using RTI time management. Real-time simulations typically do not use RTI time management.

5.9.2 Registering and Responding to Synchronization Points

The HLA DtExerciseConn class can register synchronization points and register user-defined callbacks for synchronization points. To register a synchronization point named, "point1," with the RTI, call:

exConn.registerSynchronizationPoint("point1");

You can register user-defined callbacks that will be called upon receiving a callback from the RTI. The available callbacks are:

• synchronizationPointRegistrationSucceeded()
• synchronizationPointRegistrationFailed()
• federationSynchronized()
• announceSynchronizationPoint().

To add or remove user-defined callbacks, use the following member functions:

• addSynchPointRegistrationSucceededCb()
• removeSynchPointRegistrationSucceededCb()
• addSynchPointRegistrationFailedCb()
• removeSynchPointRegistrationFailedCb()
• addFederationSynchedCb()
• removeFederationSynchedCb()
• addAnnounceSynchPointCb()
• removeAnnounceSynchPointCb().

Each member function takes a string (optional), function, and a pointer to user data that may be passed to the callback when called. If the string is provided, the callback is called for that particular label. If it is not provided, that callback is called for all labels.

For example:

exConn.addFederationSynchedCb("point1", userFunction, NULL);

causes userFunction to be called when the federation is synchronized at "point1", and:

exConn.addFederationSynchedCb(userFunction, NULL);

causes userFunction to be called when the federation is synchronized at any point.

Example:

#include <vl/exerciseConn.h>

void fedsSynched(const char* label, void* /*usr*/)
{
   std::cout << "Federates synched at: " << label << std::endl;
}

void announcePoint(const char* label, const char* tag, void* usr)
{
   DtExerciseConn* exConn = (DtExerciseConn*)usr;
   std::cout << "Announce point: " << label << std::endl;
   std::cout << "Tag: " << tag << std::endl;
   usr->replyToSynchronizationPoint(label);
}

int main(int argc, char** argv)
{
   DtExerciseConn exConn(...);

   ...
   // fedsSynched is called whenever the federation is synched
   exConn.addFederationSynchedCb(fedsSynched, NULL);

   // announcePoint is called when the label "point2" is announced.
   // The exercise connection automatically replies to all synch points
   // excluding "point2"
   exConn.addAnnounceSynchPointCb("point2", announcePoint, &exConn);

   ... 
}

5.9.2.1 Responding to Synchronization Points Automatically

VR-Link applications, by default, automatically respond to announced synchronization points by immediately indicating that the point has been achieved. This means that VR-Link-based applications will not hold up a federation execution when the application developer has not done anything special to respond to synchronization points. You can enable or disable this automatic response by calling:

exConn.setReplyingToSynchronizationPoints(false);

Note

Registering an announceSynchronizationPoint() callback disables VR-Link's automatic response to announcements for the specified synchronization points.

5.9.3 Time Management

VR-Link supports HLA Time Management. The use of Time Management in an exercise allows federates to synchronize and order events with a timeline maintained by the RTI. Typically, federates use time management when they are interacting with other federates that have a different rate of simulation. However, federates do not have to use Time Management, even if other federates in a federation use it. This description of Time Management in VR-Link assumes that you are familiar with Time Management terms and concepts. For more information, please see your HLA and RTI documentation.

5.9.3.1 Federation Time

Federation Time (FedTime) is the managed simulation time for an exercise. In a time-managed federation execution, the progression of time is accomplished by federates making time requests and receiving time grants from the RTI. Regulating federates control the advancement of FedTime. Constrained federates can advance only as quickly as FedTime allows. At any point in the simulation, FedTime may be different for different federates.

In VR-Link most calls to the RTI are made using the RTI Ambassador directly and are not wrapped by VR-Link. Time Regulation can be turned on and off at any time in an exercise. Many other aspects of time management can be configured such as the LookAhead. For more information about these methods please consult your RTI documentation.

Some example calls are as follows:

DtExerciseConn exConn(. . .);
. . .
exConn.rtiAmb()->enableTimeRegulation(mySuggestedFedTime, myLookAhead);
exConn.rtiAmb()->enableTimeConstrained();
exConn.rtiAmb()->disableTimeConstrained();
exConn.rtiAmb()->timeAdvanceRequest(RequestedFedTime);
exConn.rtiAmb()->disableTimeRegulation();
. . .

5.9.3.2 Sending Time Stamp Order (TSO) Messages

To send time stamp order (TSO) messages in VR-Link, tell VR-Link to attach a FedTime to outgoing messages, as follows:

exConn.setSendFedTime(true);

When sendFedTime() is true, all messages are sent TSO. When sendFedTime() is false (the default), messages are sent read order (RO). This flag can be toggled at any time, but it must be toggled before the message is sent. VR-Link uses VR-Link simTime when it sends FedTime:

ExConn.clock()->simTime();

You need to maintain simTime as FedTime + LookAhead for the message to be delivered. If simTime is less than this, the RTI throws an exception. You can run simTime ahead of FedTime + Lookahead, because a Regulator can send messages with any time in the future, as long as the time is at least FedTime + Lookahead.

5.9.3.3 Receiving TSO Messages

VR-Link handles incoming TSO messages transparently. The RTI makes sure the messages are delivered at the correct FedTime. VR-Link uses the FedTime, when available, to perform dead reckoning computations.

5.9.3.4 Using Callbacks

When the RTI needs to update FedTime for a federate by granting a request, or enable some type of time regulation, it invokes a method in the Federate Ambassador. VR-Link provides callbacks for these methods. You can write functions that handle these RTI events. Then you can register them for callbacks.

The following examples demonstrate callbacks as well as the functions that register them.

void timeAdvanceRequestCb(const RTI::FedTime &theFedTime, void *userData)
{

   // The time we request might not be the time we get back!
   GlobalFedTime = theFedTime;
   // do something
   cout << "Time Advance Grant to: " << GlobalFedTime.getTime() << endl;
}

void timeConstrainedEnabledCb(const RTI::FedTime &theFedTime, void *userData)
{
   GlobalFedTime = theFedTime;
   // do something
   cout << "Time Constrained Enabled at time: "
      << GlobalFedTime.getTime() << endl;
}

// Call this when our time request is granted. timeAdvanceRequestCb is
// the callback. The 0 is data.
exConn.fedAmb()->addTimeAdvanceGrantCb(timeAdvanceRequestCb, 0);  

// This callback lets me know I have become constrained. I must
// remember that until I receive it, I am not time constrained
// and should not ask for a time advance. timeConstrainedEnabledCb is
// the callback. The 0 is data.
exConn.fedAmb()->addTimeConstrainedEnabledCb(timeConstrainedEnabledCb, 0);

// This callback lets me know I have become time regulating. It also 
// lets me know what FedTime it is. I must use that fed time.
// timeRegulationEnabledCb is the callback. The 0 is data.
exConn.fedAmb()->addTimeRegulationEnabledCb(timeRegulationEnabledCb, 0);

5.9.3.5 Converting FedTime to DtTime

Occasionally, VR-Link needs to convert from RTI::FedTime to DtTime. RTI::FedTime is an abstract base class and the federate needs to provide an implementation of this class. Most RTIs, including the MAK RTI, provide a subclass for federates to use. It is typically in the library libFedTime. The base class provides no method for converting RTI::FedTime to a double (DtTime), but the sub-classed method provided by many RTI's (including the MAK RTI) does. Because it is possible, and even likely, that you will use a different subclass of RTI::FedTime, VR-Link will not always know how to do this conversion. Therefore, VR-Link provides member functions in DtExerciseConn that allow you to register conversion functions for VR-Link to use.

static void DtExerciseConn::setFedTimeToVrlTimeConverter(DtFedTimeToVrlTimeConverter func);
static void DtExerciseConn::setVrlTimeToFedTimeConverter(DtVrlTimeToFedTimeConverter func);

DtExerciseConn has default conversion functions for the MAK RTI. If you need to set the conversion functions back to the default, pass a NULL value to either DtExerciseConn::setFedTimeToVrlTimeConverter() or DtExerciseConn::setVrlTimeToFedTimeConverter().

When a federate needs to convert between RTI::FedTime and DtTime, it can use the member functions:

• static DtFedTimeToVrlTimeConverter DtExerciseConn::fedTimeToVrlTimeConverter();
• static DtVrlTimeToFedTimeConverter DtExerciseConn::vrlTimeToFedTimeConverter();

Use them as in the following example:

RTI::FedTime *fedTimePtr =(*DtExerciseConn::vrlTimeToFedTimeConverter()) (myDtTimeVariable);

5.9.4 VR-Link Calls to RTI Services

The following table lists Federate-initiated services that may be called by VR-Link. The next table lists RTI-initiated services for which VR-Link provides non-NULL definitions.

Federate-initiated Service Called by VR-Link
RTI Service	How it is invoked
createFederationExecution	Invoked from within the DtExerciseConn constructor.
destroyFederationExecution	Invoked from within the DtExerciseConn destructor if the DtExerciseConn's destroyFedExec flag is true (the default).
joinFederationExecution	Invoked from within the DtExerciseConn constructor.
resignFederationExecution	Invoked from within the DtExerciseConn destructor.
publishInteractionClass	Invoked from within the DtExerciseConn::send() or sendStamped() whenever it is called with an interaction whose class has not been published yet.
publishObjectClass	Invoked from within an object publisher's constructor if its object class has not already been published.
subscribeInteractionClass	Invoked when registering a callback function with VR-Link on a particular interaction class using a DtInteraction subclass's addCallback() function.
subscribeObjectClassAttri- butes	Invoked from within a reflected object list's constructor.
unsubscribeInteractionClass	Called by DtObjClassDesc::deregisterInterest(). That function is not called by other VR-Link code, so if application code does not call it, this service is never invoked.
unsubscribeObjectClass	Called by DtInterClassDesc::deregisterInterest(). That function is not called by other VR-Link code. So if application code does not call it, this service is never invoked.
deleteObjectInstance	Invoked from an object publisher's destructor.
localDeleteObjectInstance	Invoked only from DtReflectedObjectList::removeObject(), which is not typically called by applications.
registerObjectInstance	Invoked from an object publisher's constructor.
requestClassAttributeValue-Update	Invoked from a reflected object list's constructor, if the list's requestClassUpdate flag is true (the default).
requestObjectAttributeValue-Update	If DtReflectedEntityList's (or any other reflected object list's) requestObjectUpdate flag is true (the default), then this service is invoked shortly after each reflected object is discovered and created. Since we cannot call the service from within our discover object callback (it would be a concurrent access violation), the service is not called until just before DtExerciseConn::drainInput() returns.
sendInteraction	Invoked from within DtExerciseConn::send() or sendStamped().
sendInteractionWithRegion	Invoked from within DtExerciseConn::send() or sendStamped() if you are using DDM.
updateAttributeValues	Invoked from within an object publisher's tick() function, if we judge that data needs to be sent based on update conditions and remote subscriptions and requests.
RTIambassador	DtExerciseConn's constructor constructs an RTI ambassador.
~RTIambassador	DtExerciseConn's destructor deletes its RTI ambassador.
enableAttributeRelevanceAdvisorySwitch	Invoked by the DtExerciseConn constructor.
enableClassRelevanceAdvisorySwitch	Invoked by the DtExerciseConn constructor.
enableInteractionRelevanceAdvisorySwitch	Invoked by the DtExerciseConn constructor.
disableAttributeRelevanceAdvisorySwitch	Invoked by the DtExerciseConn constructor.
disableClassRelevanceAdvisorySwitch	Invoked by the DtExerciseConn constructor.
disableInteractionRelevanceAdvisorySwitch	Invoked by the DtExerciseConn constructor.
synchronizationPointAchieved	Invoked from DtExerciseConn::replyToSynchPointCallback().
tick	Called from within DtExerciseConn::drainInput().

RTI-initiated Services with Non-NULL Definitions
RTI Service	VR-Link Response
startRegistrationForObjectClass	VR-Link maintains information about which object classes are needed by the federation.
stopRegistrationForObjectClass	VR-Link does not maintain information about which object classes are needed by the federation.
turnInteractionsOff	VR-Link does not maintain information about which interaction classes are needed by the federation.
turnInteractionsOn	VR-Link maintains information about which interaction classes are needed by the federation.
discoverObjectInstance	If any reflected object list has registered interest in the object's class or a super class, VR-Link creates a new reflected object and adds it to the list.
provideAttributeValueUpdate	VR-Link notes that the attribute set has been requested. The next time the object's publisher calls its tick() function, the request attribute updates are sent.
receiveInteraction	If any user callbacks have been registered with VR-Link for the received interaction type, those callbacks are invoked.
reflectAttributeValues	The reflected object's state repository is updated based on the contents of the received attribute update.
removeObjectInstance	The reflected object is removed from the reflected object list, and deleted.
turnUpdatesOffForObjectInstance	VR-Link does not maintain information about which attributes are needed by the federation.
turnUpdatesOnForObjectInstance	VR-Link maintains information about which attributes are needed by the federation.

The following ancillary services are called at various points within VR-Link:

• getAttributeHandle
• getAttributeName
• getInteractionClassHandle
• getObjectClassHandle
• getObjectInstanceName
• getParameterHandle
• getParameterName.

[<< Using the DtInteraction Class] [Home] [Top of Page] [Interoperability Between HLA 1.3 and IEEE 1516 Federates >>]