A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
synchronizer.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2008 University of Washington
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 */
6
7#ifndef SYNCHRONIZER_H
8#define SYNCHRONIZER_H
9
10#include "nstime.h"
11#include "object.h"
12
13#include <stdint.h>
14
15/**
16 * @file
17 * @ingroup realtime
18 * ns3::Synchronizer declaration.
19 */
20
21namespace ns3
22{
23
24/**
25 * @ingroup realtime
26 * @brief Base class used for synchronizing the simulation events to some
27 * real time "wall clock."
28 *
29 * The simulation clock is maintained as a 64-bit integer in a unit specified
30 * by the user through the Time::SetResolution function. This means that
31 * it is not possible to specify event expiration times with anything better
32 * than this user-specified accuracy. We use this clock for the simulation
33 * time.
34 *
35 * The real-time clock is maintained as a 64-bit integer count of nanoseconds.
36 *
37 * The synchronization between the simulation clock and the real-time clock
38 * is maintained using a combination of sleep-waiting, busy-waiting and a
39 * feedback loop.
40 */
41class Synchronizer : public Object
42{
43 public:
44 /**
45 * Get the registered TypeId for this class.
46 * @returns The TypeId.
47 */
48 static TypeId GetTypeId();
49
50 /** Constructor. */
52 /** Destructor. */
53 ~Synchronizer() override;
54
55 /**
56 * @brief Return true if this synchronizer is actually synchronizing to a
57 * realtime clock.
58 *
59 * The simulator sometimes needs to know this.
60 *
61 * @returns @c true if locked with realtime, @c false if not.
62 */
63 bool Realtime();
64
65 /**
66 * @brief Retrieve the value of the origin of the underlying normalized wall
67 * clock time in simulator timestep units.
68 *
69 * @returns The normalized wall clock time (in Time resolution units).
70 * @see SetOrigin
71 */
72 uint64_t GetCurrentRealtime();
73
74 /**
75 * @brief Establish a correspondence between a simulation time and the
76 * synchronizer real time.
77 *
78 * This method is expected to be called at the "instant" before simulation
79 * begins. At this point, simulation time = 0, and a
80 * set = 0 in this method. We then associate this time with the current
81 * value of the real time clock that will be used to actually perform the
82 * synchronization.
83 *
84 * Subclasses are expected to implement the corresponding DoSetOrigin pure
85 * virtual method to do the actual real-time-clock-specific work
86 * of making the correspondence mentioned above.
87 *
88 * @param [in] ts The simulation time we should use as the origin (in
89 * Time resolution units).
90 * @see DoSetOrigin
91 */
92 void SetOrigin(uint64_t ts);
93
94 /**
95 * @brief Retrieve the value of the origin of the simulation time in
96 * Time.resolution units.
97 *
98 * @returns The simulation time used as the origin (in Time resolution units).
99 * @see SetOrigin
100 */
101 uint64_t GetOrigin();
102
103 /**
104 * @brief Retrieve the difference between the real time clock used to
105 * synchronize the simulation and the simulation time (in
106 * Time resolution units).
107 *
108 * @param [in] ts Simulation time in Time resolution units.
109 * @returns Simulation Time (in Time resolution units)
110 * minus the origin time (stored internally in nanosecond units).
111 * @see SetOrigin
112 * @see DoGetDrift
113 */
114 int64_t GetDrift(uint64_t ts);
115
116 /**
117 * @brief Wait until the real time is in sync with the specified simulation
118 * time or until the synchronizer is Signalled.
119 *
120 * This is where the real work of synchronization is done. The @c tsCurrent
121 * argument is the simulation time. The job of Synchronize is to
122 * translate from simulation time to synchronizer time (in a perfect world
123 * this is the same time) and then figure out how long in real-time it needs
124 * to wait until that synchronizer / simulation time comes around.
125 *
126 * Subclasses are expected to implement the corresponding DoSynchronize pure
127 * virtual method to do the actual real-time-clock-specific work of waiting
128 * (either busy-waiting or sleeping, or some combination thereof) until the
129 * requested simulation time.
130 *
131 * @param [in] tsCurrent The current simulation time (in Time resolution units).
132 * @param [in] tsDelay The simulation time we need to wait for (in Time
133 * resolution units).
134 * @returns @c true if the function ran to completion,
135 * @c false if it was interrupted by a Signal.
136 * @see DoSynchronize
137 * @see Signal
138 */
139 bool Synchronize(uint64_t tsCurrent, uint64_t tsDelay);
140
141 /**
142 * @brief Tell a possible simulator thread waiting in the Synchronize method
143 * that an event has happened which demands a reevaluation of the wait time.
144 *
145 * This will cause the thread to wake and return to the simulator proper
146 * where it can get its bearings.
147 *
148 * @see Synchronize
149 * @see DoSignal
150 */
151 void Signal();
152
153 /**
154 * @brief Set the condition variable that tells a possible simulator thread
155 * waiting in the Synchronize method that an event has happened which demands
156 * a reevaluation of the wait time.
157 *
158 * @param [in] cond The new value for the condition variable.
159 *
160 * @see Signal
161 */
162 void SetCondition(bool cond);
163
164 /**
165 * @brief Ask the synchronizer to remember what time it is.
166 *
167 * Typically used with EventEnd to determine the real execution time
168 * of a simulation event.
169 *
170 * @see EventEnd
171 */
172 void EventStart();
173
174 /**
175 * @brief Ask the synchronizer to return the time step between the instant
176 * remembered during EventStart and now.
177 *
178 * Used in conjunction with EventStart to determine the real execution time
179 * of a simulation event.
180 *
181 * @returns The elapsed real time, in ns.
182 * @see EventStart
183 */
184 uint64_t EventEnd();
185
186 protected:
187 /**
188 * @brief Establish a correspondence between a simulation time and a
189 * wall-clock (real) time.
190 *
191 * There are three timelines involved here: the simulation (virtual) time,
192 * the (absolute) wall-clock time and the (relative) synchronizer real time.
193 * Calling this method makes a correspondence between the origin of the
194 * synchronizer time and the current wall-clock time.
195 *
196 * This method is expected to be called at the "instant" before simulation
197 * begins. At this point, simulation time = 0, and synchronizer time is
198 * set = 0 in this method. We then associate this time with the current
199 * value of the real time clock that will be used to actually perform the
200 * synchronization.
201 *
202 * Subclasses are expected to implement this method to do the actual
203 * real-time-clock-specific work of making the correspondence mentioned above.
204 * for example, this is where the differences between Time parameters and
205 * parameters to clock_nanosleep would be dealt with.
206 *
207 * @param [in] ns The simulation time we need to use as the origin (normalized to
208 * nanosecond units).
209 * @see SetOrigin
210 */
211 virtual void DoSetOrigin(uint64_t ns) = 0;
212
213 /**
214 * @brief Return @c true if this synchronizer is actually synchronizing to a
215 * realtime clock.
216 *
217 * The simulator sometimes needs to know this.
218 *
219 * Subclasses are expected to implement this method to tell the outside world
220 * whether or not they are synchronizing to a realtime clock.
221 *
222 * @returns @c true if locked with realtime, @c false if not.
223 */
224 virtual bool DoRealtime() = 0;
225
226 /**
227 * @brief Retrieve the value of the origin of the underlying normalized wall
228 * clock time in Time resolution units.
229 *
230 * Subclasses are expected to implement this method to do the actual
231 * real-time-clock-specific work of getting the current time.
232 *
233 * @returns The normalized wall clock time (in nanosecond units).
234 * @see SetOrigin
235 */
236 virtual uint64_t DoGetCurrentRealtime() = 0;
237
238 /**
239 * @brief Wait until the real time is in sync with the specified simulation
240 * time.
241 *
242 * This is where the real work of synchronization is done. The
243 * @c nsCurrent argument is the simulation time (in ns). The job of
244 * DoSynchronize is to translate from simulation time to synchronizer time
245 * (in a perfect world these are the same time) and then figure out
246 * how long in real-time it needs to wait until that
247 * synchronizer / simulation time comes around.
248 *
249 * Subclasses are expected to implement this method to do the actual
250 * real-time-clock-specific work of waiting (either busy-waiting or sleeping,
251 * or some combination) until the requested simulation time.
252 *
253 * @param [in] nsCurrent The current simulation time (in nanosecond units).
254 * @param [in] nsDelay The simulation time we need to wait for (normalized to
255 * nanosecond units).
256 * @returns @c true if the function ran to completion,
257 * @c false if it was interrupted by a Signal.
258 * @see Synchronize
259 * @see Signal
260 */
261 virtual bool DoSynchronize(uint64_t nsCurrent, uint64_t nsDelay) = 0;
262
263 /**
264 * @brief Tell a possible simulator thread waiting in the
265 * DoSynchronize method that an event has happened which
266 * demands a reevaluation of the wait time.
267 *
268 * @see Signal
269 */
270 virtual void DoSignal() = 0;
271
272 /**
273 * @brief Set the condition variable to tell a possible simulator thread
274 * waiting in the Synchronize method that an event has happened which
275 * demands a reevaluation of the wait time.
276 *
277 * @param [in] cond The new value for the condition variable.
278 * @see SetCondition
279 */
280 virtual void DoSetCondition(bool cond) = 0;
281
282 /**
283 * @brief Get the drift between the real time clock used to synchronize
284 * the simulation and the current simulation time.
285 *
286 * @param [in] ns Simulation time in ns.
287 * @returns Drift in ns units.
288 * @see SetOrigin
289 * @see GetDrift
290 */
291 virtual int64_t DoGetDrift(uint64_t ns) = 0;
292
293 /**
294 * @brief Record the normalized real time at which the current
295 * event is starting execution.
296 */
297 virtual void DoEventStart() = 0;
298 /**
299 * @brief Return the amount of real time elapsed since the last call
300 * to EventStart.
301 *
302 * @returns The elapsed real time, in ns.
303 */
304 virtual uint64_t DoEventEnd() = 0;
305
306 /** The real time, in ns, when SetOrigin was called. */
308 /** The simulation time, in ns, when SetOrigin was called. */
310
311 private:
312 /**
313 * @brief Convert a simulator time step (in Time resolution units)
314 * to a normalized time step in nanosecond units.
315 *
316 * @param [in] ts The simulation time step to be normalized.
317 * @returns The simulation time step normalized to nanosecond units.
318 */
319 uint64_t TimeStepToNanosecond(uint64_t ts);
320
321 /**
322 * @brief Convert a normalized nanosecond time step into a
323 * simulator time step (in Time resolution units).
324 *
325 * @param [in] ns The nanosecond count step to be converted
326 * @returns The simulation time step to be interpreted in appropriate units.
327 */
328 uint64_t NanosecondToTimeStep(uint64_t ns);
329};
330
331} // namespace ns3
332
333#endif /* SYNCHRONIZER_H */
A base class which provides memory management and object aggregation.
Definition object.h:78
Base class used for synchronizing the simulation events to some real time "wall clock....
virtual void DoSignal()=0
Tell a possible simulator thread waiting in the DoSynchronize method that an event has happened which...
void Signal()
Tell a possible simulator thread waiting in the Synchronize method that an event has happened which d...
void SetOrigin(uint64_t ts)
Establish a correspondence between a simulation time and the synchronizer real time.
virtual void DoSetCondition(bool cond)=0
Set the condition variable to tell a possible simulator thread waiting in the Synchronize method that...
virtual void DoEventStart()=0
Record the normalized real time at which the current event is starting execution.
uint64_t GetCurrentRealtime()
Retrieve the value of the origin of the underlying normalized wall clock time in simulator timestep u...
virtual uint64_t DoEventEnd()=0
Return the amount of real time elapsed since the last call to EventStart.
bool Realtime()
Return true if this synchronizer is actually synchronizing to a realtime clock.
void EventStart()
Ask the synchronizer to remember what time it is.
virtual bool DoSynchronize(uint64_t nsCurrent, uint64_t nsDelay)=0
Wait until the real time is in sync with the specified simulation time.
uint64_t TimeStepToNanosecond(uint64_t ts)
Convert a simulator time step (in Time resolution units) to a normalized time step in nanosecond unit...
static TypeId GetTypeId()
Get the registered TypeId for this class.
uint64_t GetOrigin()
Retrieve the value of the origin of the simulation time in Time.resolution units.
uint64_t m_realtimeOriginNano
The real time, in ns, when SetOrigin was called.
uint64_t NanosecondToTimeStep(uint64_t ns)
Convert a normalized nanosecond time step into a simulator time step (in Time resolution units).
~Synchronizer() override
Destructor.
virtual int64_t DoGetDrift(uint64_t ns)=0
Get the drift between the real time clock used to synchronize the simulation and the current simulati...
virtual uint64_t DoGetCurrentRealtime()=0
Retrieve the value of the origin of the underlying normalized wall clock time in Time resolution unit...
int64_t GetDrift(uint64_t ts)
Retrieve the difference between the real time clock used to synchronize the simulation and the simula...
virtual bool DoRealtime()=0
Return true if this synchronizer is actually synchronizing to a realtime clock.
uint64_t m_simOriginNano
The simulation time, in ns, when SetOrigin was called.
uint64_t EventEnd()
Ask the synchronizer to return the time step between the instant remembered during EventStart and now...
bool Synchronize(uint64_t tsCurrent, uint64_t tsDelay)
Wait until the real time is in sync with the specified simulation time or until the synchronizer is S...
void SetCondition(bool cond)
Set the condition variable that tells a possible simulator thread waiting in the Synchronize method t...
virtual void DoSetOrigin(uint64_t ns)=0
Establish a correspondence between a simulation time and a wall-clock (real) time.
Synchronizer()
Constructor.
a unique identifier for an interface.
Definition type-id.h:48
Every class exported by the ns3 library is enclosed in the ns3 namespace.
Declaration of classes ns3::Time and ns3::TimeWithUnit, and the TimeValue implementation classes.
ns3::Object class declaration, which is the root of the Object hierarchy and Aggregation.