1. Time Management
1. Introduction

This chapter introduces the RTIambassador service and FederateAmbassador callback methods that support time management functionality. The RTI provides a variety of optional time management services. Though optional, it is important to understand the time management models available in the RTI and the implication of exchanging events between federates with different time management policies. Chapter 3, The Role of Time, provides a philosophical introduction to time management. The focus here is on the mechanics required to implement time management policies and negotiate time advances.

 

2. Toggling "regulating" and "constrained" Status

Chapter 3, The Role of Time, presented the definitions for "regulating" and "constrained." Figure 6-1 identifies the RTIambassador and FederateAmbassador member functions associated with establishing whether a federate is regulating or not, and whether a federate is constrained or not. Key methods are presented briefly below and discussed in detail in the appendices.



 

Figure 6-1. Toggling "regulating" and "constrained" Status

 

1. Regulation Policy

Federates have regulation disabled by default. A federate utilizes the RTIambassador member function enableTimeRegulation() to request that the federate be acknowledged as a regulating federate. The Local RTI Component (LRC) calls the FederateAmbassador callback timeRegulationEnabled() to inform a federate that the enableTimeRegulation() request has been granted and informs the federate of its (possibly new) logical time. In Section 3.4, Advancing Time, the effect of a late arriving federate wishing to be time regulating was discussed. In synopsis, such a federate is obligated to advance to a time such that the current LBTS of existing federates is guaranteed to be honored.

It is possible to change the regulation policy dynamically. The RTIambassador method disableTimeRegulation() is the counterpart to enableTimeRegulation(). Unlike enableTimeRegulation(), disableTimeRegulation() takes effect immediately.

2. Constrained Policy

Federates have constrained disabled by default. A federate utilizes the RTIambassador member function enableTimeConstrained() to request that the federate be acknowledged as a constrained federate. The timeConstrainedEnabled() callback informs a federate that the enableTimeConstrained() request has been granted. It is possible to change the constrained policy dynamically. The RTIambassador method disableTimeConstrained() is the counterpart to enableTimeConstrained().

3. Time Advance Requests

Three variants of the time advancement service exist to provide the requisite functionality for time-step, event-based, and optimistic federates. Typically, a federate will employ only one of the time advancement services; however, some federates may find it useful to use more than one of the services throughout the federate’s execution.

1. Time-Stepped Federates

Time-stepped federates will calculate values based on a point in time and then process all events that occur up to the next point in time (current time + time step). Figure 6-2 illustrates the functions used to advance a federate's logical time for a time-stepped simulation.

When a timeAdvanceRequest() or timeAdvanceRequestAvailable() service is used, the federate’s LRC will be eligible to release any receive order messages from the FIFO Queue and all time-stamp ordered messages that have a time stamp less than or equal to the time requested from the TSO queue. After all TSO messages in a federation execution with time less than or equal to the requested time have been received, the federate will receive a timeAdvanceGrant() callback via the FederateAmbassador. See the man pages for a more detailed discussion of the released events and the granted time for the timeAdvanceRequest() and timeAdvanceRequestAvailable() services.



Figure 6-2. Logical Time Advancement for a Time-Step Federate

 

2. Event-Based Federates

Event-based federates will calculate values based on each event received from the federation execution. After an event is processed, the federate may need to send new events to the federation execution. This implies that the events may not happen on set time intervals but the times of events will be based on the time of the received events. Figure 6-3 illustrates the functions used to advance a federate's logical time for an event-based simulation.

When a nextEventRequest() or nextEventRequestAvailable() service is used, the federate’s LRC will be eligible to release any receive order messages from the FIFO Queue and all time-stamp ordered messages that have a time stamp equal to the minimum next event time from the TSO queue.

After all TSO messages with time equal to the minimum next event time have been received, the federate will receive a timeAdvanceGrant() callback via the FederateAmbassador. See the man pages for a more detailed discussion of the released events and the granted time for the nextEventRequest() and nextEventRequestAvailable() services.



Figure 6-3. Logical Time Advancement for an Event-Based Federate

 

3. Optimistic Federates

Optimistic federates do not want to be constrained by the time advancement of regulating federates but instead will proceed ahead of LBTS to calculate and send events in the future. These federates will want to receive all of the events that have been sent in the federation execution regardless of the time-stamp ordering. A federate that uses the flushQueueRequest() service is likely to generate events that are in the future of messages that it has yet to receive. The messages that are received with a time-stamp less than messages already sent may invalidate the previous messages. In this case, the optimistic federate will need to retract the messages that have been invalidated and all federates that have received the invalid messages will receive a requestRetraction() callback on their FederateAmbassador. See the man pages for a detailed discussion of the retract() and requestRetraction() services.

When the flushQueueRequest() service is used, the federate’s LRC will be eligible to release all receive order messages from the FIFO Queue and all time-stamp ordered messages from the TSO queue. After all TSO messages that were in the queue at the time of the flushQueueRequest() invocation have been released, the federate will receive a timeAdvanceGrant() callback via the FederateAmbassador. See the man pages for a more detailed discussion of the released events and the granted time for the flushQueueRequest() service. Figure 6-4 illustrates the functions used to advance a federate's logical time for an optimistic simulation.



Figure 6-4. Logical Time Advancement for an Optimistic Federate

4. FoodFight Example

1. #ifndef globals_h
2. #define globals_h
4. #include <RTI.hh>
5. :
6. // The time of the last time advance grant.
7. extern RTI::FedTime* p_current_time;
9. // The lookahead period promised by this federate. Set when federate
10. // attempts to become regulating.
11. extern RTI::FedTime* p_lookahead;
13. // Variable indicating whether we currently have a pending time advance
14. extern int time_advance_outstanding;
16. // Flag indicating if federate is constrained.
17. extern int regulation_enabled;
19. // Flag indicating if federate is constrained.
20. extern int constrain_enabled;
21. :
22. #endif
23. // globals_h

globals.cxx

24. #include "globals.h"
25. :
26. RTI::FedTime* p_current_time = new RTIfedTime(0.0);
27. RTI::FedTime* p_lookahead = 0; // Not set yet.
28. int time_advance_outstanding = 0;
29. int regulation_enabled = 0; // Disabled by default.
30. int constrain_enabled = 0; // Disabled by default.
31. :

::PrimarySimulation()

32. void
33. PrimarySimulation (int regulating_flag,
34. int constrained_flag)
35. {
36. // Abstract
37. // This function produces the FoodFight simulation.
39. Pstring federation_name("FoodFight");
40. Pstring federate_name("ExampleFederate");
42. // Create and join the FoodFight federation.
43. ::CreateAndJoinFederation(federation_name, federate_name);
45. // Set up time-management services.
46. if (regulating_flag)
47. {
48. ::p_lookahead = new RTIfedTime(1.0); // One second.
49. ::rti_ambassador.enableTimeRegulation(*::p_current_time, *::lookahead);
51. // A request to become regulating is, effectively, a time advance
52. // request.
53. ::time_advance_outstanding = 1;
54. }
56. if (constrained_flag)
57. {
58. cout << "Federate is constrained!" << endl;
59. ::rti_ambassador.enableTimeConstrained();
60. }
61. :
62. :
63. // The time interval for this federate has been set (arbitrarily) to the
64. // lookahead value.
65. RTI::FedTime* p_interval = new RTIfedTime(0.0);
66. *p_interval = *::p_lookahead;
68. while (::local_students.entries())
69. {
70. if (!::time_advance_outstanding)
71. {
72. // Do one interval's worth of simulation.
73. :
74. :
75. // Attempt to advance federate's logical time. The logical time
76. // isn't officially advanced until a time advance grant is
77. // received. If a regulating federate is still attempting to
78. // generate events, it should pretend like the time advance has
79. // been granted for the purpose of observing its lookahead promise.
80. *::p_current_time += *p_interval;
81. ::rti_ambassador.timeAdvanceRequest(*::p_current_time);
82. ::time_advance_outstanding = 1;
83. }
84. :
85. :
86. // Work to be interleaved with tick only!
87. :
88. :
89. // Tick the RTI, initiating federate ambassador callbacks.
90. ::rti_ambassador.tick(1.0, 1.0);
91. }
93. // Resign from the federation execution and attempt to destroy.
94. ::ResignAndDestroyFederation(federation_name, federate_name);
95. }

The two-argument form of tick is called in the preceding example. In the example, the goal is to slow the simulation so students can observe simulation progress. As an alternative to line 87, the one-argument version of tick() might be used. Between calls to tick() and prior to receiving a time advance grant, the federate may choose to interleave some preparatory work.

96. ::rti_ambassador.tick(); // Alternative to line 87 above.

FoodFightFedAmb.h

97. class FoodFightFedAmb : public DefaultFedAmb
98. {
99. // Abstract
100. // The DefaultFedAmb defines all the federate ambassador methods
101. // to "do nothing". Here, we override the ones we're interested
102. // in.
104. public:
105. virtual void timeRegulationEnabled (const FedTime&)
106. throw (InvalidFederationTime, EnableTimeRegulationWasNotPending,
107. FederateInternalError);
109. virtual void timeConstrainedEnabled (const FedTime&)
110. throw (InvalidFederationTime, EnableTimeConstrainedWasNotPending,
111. FederateInternalError);
113. virtual void timeAdvanceGrant (const RTI::FedTime&)
114. throw (RTI::InvalidFederationTime, RTI::TimeAdvanceWasNotInProgress,
115. RTI::FederateInternalError);
117. :

FoodFightFedAmb.cxx

118. :
119. void
120. FoodFightFedAmb::
121. timeRegulationEnabled (const FedTime& time)
122. throw (InvalidFederationTime, EnableTimeRegulationWasNotPending,
123. FederateInternalError)
124. {
125. cout << "Federate acknowledged as regulating!" << endl;
126. ::regulation_enabled = 1;
127. ::time_advance_outstanding = 0;
128. *::p_current_time = time;
129. }
131. void
132. FoodFightFedAmb::
133. timeConstrainedEnabled (const FedTime&) // Argument ignored below.
134. throw (InvalidFederationTime, EnableTimeConstrainedWasNotPending,
135. FederateInternalError)
136. {
137. cout << "Federate acknowledged as constrained!" << endl;
138. ::constrain_enabled = 1;
139. }
141. void
142. FoodFightFedAmb::
143. timeAdvanceGrant (const RTI::FedTime& time)
144. throw (RTI::InvalidFederationTime,
145. RTI::TimeAdvanceWasNotInProgress, RTI::FederateInternalError)
146. {
147. if (!::time_advance_outstanding)
148. {
149. const char* err_msg = "Unexpected timeAdvanceGrant().";
150. cerr << err_msg;
151. throw RTI::TimeAdvanceWasNotInProgress(err_msg);
152. }
154. if (time < *::p_current_time)
155. {
156. const char* err_msg = "Old time passed in timeAdvanceGrant().";
157. cerr << err_msg;
158. throw RTI::InvalidFederationTime(err_msg);
159. }
161. try
162. {
163. *::p_current_time = time;
164. ::time_advance_outstanding = 0;
166. // Display current time.
168. char* p_string(0);
169. p_current_time.getPrintableString(p_string);
171. cout << "t = " << p_string << endl;
173. delete p_string;
174. }
175. catch (...)
176. {
177. const char* err_msg = "Exception caught in timeAdvanceGrant().";
178. cerr << err_msg;
179. throw RTI::FederateInternalError(err_msg);
180. }
181. }
182. :

1. Time-Related Queries

Several additional time management functions are available to query or fine tune time policy. Figure 6-4, Time Queries, shows additional functions. Consult the man pages for these functions for detailed descriptions.