hTimeMgmtControl.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2006 MAK Technologies, Inc.
** All rights reserved.
*******************************************************************************/
/*******************************************************************************
** $RCSfile: hTimeMgmtControl.h,v $ $Revision: 1.5 $ $State: Exp $
*******************************************************************************/

// \file hTimeMgmtControl.h
// \brief DtHlaTimeManagementControl provides controls for enabling/disabling
// HLA time constrained/time regulating mode, and the means to advance federate
// (logical) time.

#ifndef hTimeMgmtControl_H_
#define hTimeMgmtControl_H_

#if DtHLA

#if !DtHLA_1516
#include "fedtime.hh"
#include <vl/vrlRtiAmb13.h>
#else
#if DtHLA_1516_EVOLVED
   #include "RTI/LogicalTime.h"
   #include "RTI/LogicalTimeInterval.h"
   #include "RTI/RTIambassador.h"
#else
   #include "RTI/LogicalTime.h"
   #include "RTI/logicalTimeImpl.h"
   #include "RTI/logicalTimeIntervalImpl.h"
   #include "RTI/RTIambassador.h"
#endif
#endif
#include <vl/hExerciseConn.h>
#include <vl/vrlFedAmb.h>
#include <vrfExtObjects/vrfExtObjectsDefines.h>
#include <list>

class DtHlaTimeManagementControl;

// Signature for time advance grant callback functions.
typedef void (*DtTimeAdvanceGrantedCb)(DtHlaTimeManagementControl* tmControl,
                                       void* usr);

typedef struct DtTimeAdvanceGrantedCbData
{
   DtTimeAdvanceGrantedCb func;
   void* usr;
} DtTimeAdvanceGrantedCbData;


// DtHlaTimeManagementControl provides controls for enabling/disabling
// the HLA Time Management time-constrained mode for a federate.
class DT_DLL_vrfExtObjects DtHlaTimeManagementControl
{
public:

   // constructor
   DtHlaTimeManagementControl(DtExerciseConn& exConn);

   // destructor
   virtual ~DtHlaTimeManagementControl();

   // -------------------------------------------------------------------------
   // Time Constrained Interface-----------------------------------------------
   // -------------------------------------------------------------------------

   // Enables HLA time constrained mode for the federate.  You must call
   // this before making any calls to advanceFedTime().  This call will repeatedly
   // call drainInput on the exConn until time constrained status is granted.
   virtual bool enableTimeConstrained();

   // Disable HLA time constrained mode.  Federate is free to advance time
   // indepenedent of the federation.  This call will repeatedly
   // call drainInput on the exConn until time constrained status is disabled.
   virtual bool disableTimeConstrained();

   // Is federate currently time constrained?
   virtual bool isTimeConstrained() const;

   // -------------------------------------------------------------------------
   // Time Regulating Interface------------------------------------------------
   // -------------------------------------------------------------------------

   // Enable time regulating mode.
   // \param exerciseConn
   // \param lookaheadInterval Time interval when added to current logical
   // time represents the earliest time the federate will send out any
   // TSO (time stamp ordered) events.
#if !DtHLA_1516
   virtual bool enableTimeRegulation(
      const RTI::FedTime& requestedFederationTime,
      const RTI::FedTime& lookahead,
      RTI::FedTime& federationTime);
#else
   virtual bool enableTimeRegulation(
      const RTI::LogicalTime& requestedFederationTime,
      const RTI::LogicalTimeInterval& lookahead,
      RTI::LogicalTime& federationTime);
#endif

   // Set new value for lookahead (assuming time regulating mode is already
   // enabled) and returns true.  Otherwise prints warning and returns false.
#if !DtHLA_1516
   virtual bool modifyLookahead(
      const RTI::FedTime& lookahead);
#else
   virtual bool modifyLookahead(
      const RTI::LogicalTimeInterval& lookahead);
#endif

   // Disable time regulating mode.
   virtual bool disableTimeRegulation();

   // \return Is this federate in time regulating mode?
   virtual bool isTimeRegulating() const;

   // -------------------------------------------------------------------------
   // Advancing Time-----------------------------------------------------------
   // -------------------------------------------------------------------------

   // \param Request an advance to given federation time.  Federation time
   // may be different than requested time following this call, even if
   // blockUntilAdvanceIsGranted is true (federation time may exceed requested
   // time).
   // If blockUntilAdvanceIsGranted is true, call will not return until 
   // actualTime exceeds requestedTime.
   // \param requestedFederationTime Desired federation time to advance to.
   // \param blockUntilAdvanceIsGranted Indicates whether this function should
   // wait until request is granted.
#if !DtHLA_1516
   virtual bool timeAdvanceRequest(
      const RTI::FedTime& requestedFederateTime, 
      bool blockUntilAdvanceIsGranted = true);
#else
   virtual bool timeAdvanceRequest(
      const RTI::LogicalTime& requestedFederateTime,
      bool blockUntilAdvanceIsGranted = true);
#endif

   // Add/remove callbacks to be executed immediately following a time advance
   // request grant.
   virtual void addTimeAdvanceGrantedCallback(DtTimeAdvanceGrantedCb cb, void *usr);
   virtual void removeTimeAdvanceGrantedCallback(DtTimeAdvanceGrantedCb cb, void *usr);

   // -------------------------------------------------------------------------
   // Querying Time------------------------------------------------------------
   // -------------------------------------------------------------------------

   // Get the lower bound time stamp (LBTS)
   // \param Returns current LBTS for the federate
   // \return true if call is successful, false otherwise
#if !DtHLA_1516
   virtual bool queryLBTS(RTI::FedTime& federateTime) const;
#else
   virtual bool queryLBTS(RTI::LogicalTime& federateTime) const;
#endif

   // Get the current federation (logical) time
   // \param Returns current federation time for the federate
   // \return true if call is successful, false otherwise
#if !DtHLA_1516
   virtual bool queryFederateTime(RTI::FedTime& federateTime) const;
#else
   virtual bool queryFederateTime(RTI::LogicalTime& federateTime) const;
#endif

public:

   // Callbacks registered with federate ambassador to advance federation time,
   // enable time constrained mode, and enable time regulating mode.
   // timeAdvanceRequestCb calls processTimeAdvanceRequest to actually perform
   // the work in the callback.
#if !DtHLA_1516   
   static void timeAdvanceRequestCb( const RTI::FedTime&, void* );
   static void timeConstrainedEnableCb( const RTI::FedTime&, void* );
   static void timeRegulationEnableCb( const RTI::FedTime&, void* );
#else
   static void timeAdvanceRequestCb( const RTI::LogicalTime&, void* );
   static void timeConstrainedEnableCb( const RTI::LogicalTime&, void* );
   static void timeRegulationEnableCb( const RTI::LogicalTime&, void* );
#endif

protected:

   // \return The exercise connection this class has been handed in to use.
   virtual DtExerciseConn& exerciseConn() const;

   // \return New instance of a federation time object.
#if !DtHLA_1516
   virtual RTI::FedTime* createFederationTime() const; 
#else
   virtual RTI::LogicalTime* createFederationTime() const;
#endif

   // Sets myFederationTime to the new time given by the RTI and sets
   // myTimeAdvanceGrantPending to false.
#if !DtHLA_1516
   virtual void processTimeAdvanceRequest( const RTI::FedTime& fTime );
#else
   virtual void processTimeAdvanceRequest( const RTI::LogicalTime& fTime );
#endif

   virtual void invokeTimeAdvanceGrantedCallbacks();

   void removeAllTimeAdvanceGrantedCallbacks();

private:

   // copy constructor - not implemented
   DtHlaTimeManagementControl(const DtHlaTimeManagementControl& orig);

   // assignment operator - not implemented
   DtHlaTimeManagementControl& operator=(const DtHlaTimeManagementControl& orig);

protected:

   DtExerciseConn& myExerciseConn;

   // Used in callback functions
   bool myTimeAdvanceGrantPending;
   bool myIsTimeConstrained;
   bool myIsTimeRegulating;
   bool myNeedToRegisterTimeAdvanceGrant;

#if !DtHLA_1516
   RTI::FedTime* myFederationTime; 
#else
   RTI::LogicalTime* myFederationTime; 
#endif

   std::list<DtTimeAdvanceGrantedCbData> myTimeAdvanceGrantedCbs;
};

#endif // DtHLA

#endif