--- a/doc/manual/manual.texi Sat Sep 20 15:45:31 2008 -0700
+++ b/doc/manual/manual.texi Sun Sep 21 13:10:08 2008 -0700
@@ -81,6 +81,7 @@
* Random variables::
* Callbacks::
* Attributes::
+* RealTime::
* Packets::
* Sockets APIs::
* Node and Internet Stack::
@@ -92,6 +93,7 @@
@include random.texi
@include callbacks.texi
@include attributes.texi
+@include realtime.texi
@include packets.texi
@include sockets.texi
@include node.texi
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/realtime.texi Sun Sep 21 13:10:08 2008 -0700
@@ -0,0 +1,100 @@
+@node RealTime
+@chapter Real-Time Scheduler
+@anchor{chap:RealTime}
+
+ns-3 has been designed for integration into testbed and virtual machine
+environments. To integrate with real network stacks and emit/consume
+packets, a real-time scheduler is needed to try to lock the simulation
+clock with the hardware clock. We describe here a component of this:
+the RealTime scheduler.
+
+The purpose of the realtime scheduler is to cause the progression of
+the simulation clock to occur synchronously with respect to some
+external time base. Without the presence of an external time base
+(wall clock), simulation time jumps instantly from one simulated time to
+the next.
+
+@section Behavior
+
+When using a non-realtime scheduler (the default in ns-3), the simulator
+advances the simulation time to the next scheduled event. During event
+execution, simulation time is frozen. With the realtime scheduler, the
+behavior is similar from the perspective of simulation models (i.e.,
+simulation time is frozen during event execution), but between events,
+the simulator will attempt to keep the simulation clock aligned with
+the machine clock.
+
+When an event is finished executing, and the scheduler moves to the next
+event, the scheduler compares the next event execution time with the
+machine clock. If the next event is scheduled for a future time,
+the simulator sleeps until that realtime is reached and then executes
+the next event.
+
+It may happen that, due to the processing inherent in the execution
+of simulation events, that the simulator cannot keep up with realtime.
+In such a case, it is up to the user configuration what to do. There
+are two ns-3 attributes that govern the behavior. The first is
+@code{ns3::RealTimeSimulatorImpl::SynchronizationMode}. The two
+entries possible for this attribute are @code{BestEffort} (the default)
+or @code{HardLimit}. In "BestEffort" mode, the simulator will just
+try to catch up to realtime by executing events until it reaches
+a point where the next event is in the (realtime) future, or else
+the simulation ends. In BestEffort mode, then, it is possible for
+the simulation to consume more time than the wall clock time. The
+other option "HardLimit" will cause the simulation to abort if the tolerance
+threshold is exceeded. This attribute is
+@code{ns3::RealTimeSimulatorImpl::HardLimit} and the default is 0.1 seconds.
+
+A different mode of operation is one in which simulated time is @strong{not}
+frozen during an event execution. This mode of realtime simulation was
+implemented but removed from the ns-3 tree because of questions of whether
+it would be useful. If users are interested in a realtime simulator
+for which simulation time does not freeze during event execution (i.e.,
+every call to @code{Simulator::Now()} returns the current wall clock time,
+not the time at which the event started executing), please contact the
+ns-developers mailing list.
+
+@section Usage
+
+The usage of the realtime simulator is straightforward, from a scripting
+perspective. Users just need to set the attribute
+@code{SimulatorImplementationType} to the Realtime simulator, such as follows:
+@verbatim
+ GlobalValue::Bind ("SimulatorImplementationType",
+ StringValue ("ns3::RealtimeSimulatorImpl"));
+@end verbatim
+
+There is a script in @code{examples/realtime-udp-echo.cc} that has an
+example of how to configure the realtime behavior. Try:
+@verbatim
+./waf --run realtime-udp-echo
+@end verbatim
+
+Whether the simulator will work in a best effort or hard limit policy
+fashion is governed by the attributes explained in the previous section.
+
+@section Implementation
+
+The implementation is contained in the following files:
+@itemize @bullet
+@item @code{src/simulator/realtime-simulator-impl.{cc,h}}
+@item @code{src/simulator/wall-clock-synchronizer.{cc,h}}
+@end itemize
+
+In order to create a realtime scheduler, to a first approximation you
+just want to cause simulation time jumps to consume real time. We propose
+doing this using a combination of sleep- and busy- waits. Sleep-waits cause
+the calling process (thread) to yield the processor for some amount of time.
+Even though this specified amount of time can be passed to nanosecond
+resolution, it is actually converted to an OS-specific granularity.
+In Linux, the granularity is called a Jiffy. Typically this resolution is
+insufficient for our needs (on the order of a ten milliseconds), so we
+round down and sleep for some smaller number of Jiffies. The process is
+then awakened after the specified number of Jiffies has passed. At this
+time, we have some residual time to wait. This time is generally smaller
+than the minimum sleep time, so we busy-wait for the remainder of the time.
+This means that the thread just sits in a for loop consuming cycles until
+the desired time arrives. After the combination of sleep- and busy-waits,
+the elapsed realtime (wall) clock should agree with the simulation time
+of the next event and the simulation proceeds.
+