View | Details | Raw Unified | Return to bug 3002
Collapse All | Expand All

(-)i/doc/manual/source/events.rst (-1 / +68 lines)
 Lines 190-197   context. Link Here 
190
Time
190
Time
191
****
191
****
192
192
193
*To be completed*
193
The entire purpose of the simulator is to have a notion of time that passes and
194
to discover what is happening at certain moments. In simulation mode, such time
195
can be magnified to look in the internals: indeed, during the debugging of a
196
simulation, if we break into simulator functions to analyze the code
197
step-by-step, we are "freezing" the simulated time. That is not happening in
198
the emulation mode, in which the simulator tries to stay in real time. However,
199
in both modes, ns-3 has only one way to express the notion of time: class Time.
194
200
201
Each instance of Time class has a huge counter that contains integers, that
202
represents the ticks in a pre-defined resolution. By default, such resolution
203
is in nanoseconds: each tick represents a single nanosecond. So, how many
204
nanoseconds we can represents? The ticks are stored in a 64-bit value:
205
therefore, with 2^64 nanoseconds you can range from now to ~584 years in the
206
future. Of course, if you increase the global resolution, you also implicitly
207
decrease the range of your simulation. If you use picoseconds instead of
208
nanoseconds, the simulation range decrease to 2^64 ps = 7 months.
209
210
It is possible to use helper functions to create a Time. For instance, to
211
create a time value that contains 2 seconds, we can do the following:
212
213
::
214
    auto t = ns3::Seconds (2);
215
216
That is equivalent to the following:
217
218
::
219
    auto t1 = ns3::MilliSeconds (2000);
220
    auto t2 = ns3::MicroSeconds (2000000);
221
222
What if we want to specify a value of 20 nanoseconds?
223
224
::
225
    auto t3 = ns3::NanoSeconds (20);
226
227
For historical reasons, the API also provides the conversion from doubles when
228
using seconds. For instance, to indicate a value of 75 milliseconds, it is
229
possible to do the following:
230
231
::
232
    auto t4 = ns3::Seconds (0.075);
233
234
Even if this is allowed, you must wonder if it is the right thing to do. The
235
float/double representation based on IEEE 754 model is not precise (but no one
236
in the world has come up with a better proposal). That means that it is not
237
possible to represent all the values, and many of them will naturally be
238
rounded to the nearest representable amount. For instance, the value 0.075
239
cannot be represented precisely and for this reason, if you print out the t4
240
variable, you will find that internally it has stored 74999999 nanoseconds
241
(assuming you are using the default resolution in nanoseconds).
242
243
It is impossible to avoid rounding problems with double and floats types: for
244
this reason, it is important to avoid, when possible, to use double and float.
245
In this specific case, ns-3 provides methods that do the hard job of converting
246
the values for you. So, everything you have to say is to specify the correct
247
unit of measure:
248
249
::
250
    // auto t4 = ns3::Seconds (0.075); // Wrong
251
    auto t4 = ns3::MilliSeconds (75); // Right
252
253
Again, the correct ns-3 way to store times is to use the Time class. If you see
254
a double or a float used as a Time, that could be a bug and must be changed to
255
the right unit of measure. Moreover, in some places, the results of a
256
double-based division or multiplication will be stored as a Time. As we have
257
seen before, the result is often not precise: therefore, it is imperative to
258
switch to integer-based operations. As a pre-condition, the developer must
259
choose the resolution, and depending from case to case, a good option could be
260
to ask the simulator what is the current resolution, assuming the default value
261
of nanoseconds.
195
262
196
Scheduler
263
Scheduler
197
*********
264
*********

Return to bug 3002