1.1 --- a/doc/manual/manual.texi	Sat Sep 20 15:45:31 2008 -0700
     1.2 +++ b/doc/manual/manual.texi	Sun Sep 21 13:10:08 2008 -0700
     1.3 @@ -81,6 +81,7 @@
     1.4  * Random variables::
     1.5  * Callbacks::
     1.6  * Attributes::
     1.7 +* RealTime::
     1.8  * Packets::
     1.9  * Sockets APIs::
    1.10  * Node and Internet Stack::
    1.11 @@ -92,6 +93,7 @@
    1.12  @include random.texi
    1.13  @include callbacks.texi
    1.14  @include attributes.texi
    1.15 +@include realtime.texi
    1.16  @include packets.texi
    1.17  @include sockets.texi
    1.18  @include node.texi

     2.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.2 +++ b/doc/manual/realtime.texi	Sun Sep 21 13:10:08 2008 -0700
     2.3 @@ -0,0 +1,100 @@
     2.4 +@node RealTime
     2.5 +@chapter Real-Time Scheduler
     2.6 +@anchor{chap:RealTime}
     2.7 +
     2.8 +ns-3 has been designed for integration into testbed and virtual machine
     2.9 +environments.  To integrate with real network stacks and emit/consume
    2.10 +packets, a real-time scheduler is needed to try to lock the simulation
    2.11 +clock with the hardware clock.  We describe here a component of this:
    2.12 +the RealTime scheduler. 
    2.13 +
    2.14 +The purpose of the realtime scheduler is to cause the progression of 
    2.15 +the simulation clock to occur synchronously with respect to some 
    2.16 +external time base. Without the presence of an external time base 
    2.17 +(wall clock), simulation time jumps instantly from one simulated time to 
    2.18 +the next.
    2.19 +
    2.20 +@section Behavior
    2.21 +
    2.22 +When using a non-realtime scheduler (the default in ns-3), the simulator
    2.23 +advances the simulation time to the next scheduled event.  During event
    2.24 +execution, simulation time is frozen.  With the realtime scheduler, the 
    2.25 +behavior is similar from the perspective of simulation models (i.e.,
    2.26 +simulation time is frozen during event execution), but between events,
    2.27 +the simulator will attempt to keep the simulation clock aligned with
    2.28 +the machine clock.
    2.29 +
    2.30 +When an event is finished executing, and the scheduler moves to the next
    2.31 +event, the scheduler compares the next event execution time with the
    2.32 +machine clock.  If the next event is scheduled for a future time,
    2.33 +the simulator sleeps until that realtime is reached and then executes
    2.34 +the next event.
    2.35 +
    2.36 +It may happen that, due to the processing inherent in the execution
    2.37 +of simulation events, that the simulator cannot keep up with realtime.
    2.38 +In such a case, it is up to the user configuration what to do.  There
    2.39 +are two ns-3 attributes that govern the behavior.  The first is
    2.40 +@code{ns3::RealTimeSimulatorImpl::SynchronizationMode}.  The two
    2.41 +entries possible for this attribute are @code{BestEffort} (the default)
    2.42 +or @code{HardLimit}.  In "BestEffort" mode, the simulator will just
    2.43 +try to catch up to realtime by executing events until it reaches
    2.44 +a point where the next event is in the (realtime) future, or else
    2.45 +the simulation ends.  In BestEffort mode, then, it is possible for
    2.46 +the simulation to consume more time than the wall clock time.  The
    2.47 +other option "HardLimit" will cause the simulation to abort if the tolerance
    2.48 +threshold is exceeded.  This attribute is
    2.49 +@code{ns3::RealTimeSimulatorImpl::HardLimit} and the default is 0.1 seconds.   
    2.50 +
    2.51 +A different mode of operation is one in which simulated time is @strong{not}
    2.52 +frozen during an event execution.  This mode of realtime simulation was
    2.53 +implemented but removed from the ns-3 tree because of questions of whether
    2.54 +it would be useful.  If users are interested in a realtime simulator
    2.55 +for which simulation time does not freeze during event execution (i.e.,
    2.56 +every call to @code{Simulator::Now()} returns the current wall clock time,
    2.57 +not the time at which the event started executing), please contact the
    2.58 +ns-developers mailing list.
    2.59 +
    2.60 +@section Usage
    2.61 +
    2.62 +The usage of the realtime simulator is straightforward, from a scripting
    2.63 +perspective.  Users just need to set the attribute 
    2.64 +@code{SimulatorImplementationType} to the Realtime simulator, such as follows:
    2.65 +@verbatim
    2.66 +  GlobalValue::Bind ("SimulatorImplementationType",
    2.67 +    StringValue ("ns3::RealtimeSimulatorImpl"));
    2.68 +@end verbatim
    2.69 +
    2.70 +There is a script in @code{examples/realtime-udp-echo.cc} that has an
    2.71 +example of how to configure the realtime behavior.  Try:
    2.72 +@verbatim
    2.73 +./waf --run realtime-udp-echo
    2.74 +@end verbatim
    2.75 +
    2.76 +Whether the simulator will work in a best effort or hard limit policy
    2.77 +fashion is governed by the attributes explained in the previous section.
    2.78 +
    2.79 +@section Implementation
    2.80 +
    2.81 +The implementation is contained in the following files:
    2.82 +@itemize @bullet
    2.83 +@item @code{src/simulator/realtime-simulator-impl.{cc,h}}
    2.84 +@item @code{src/simulator/wall-clock-synchronizer.{cc,h}}
    2.85 +@end itemize
    2.86 +
    2.87 +In order to create a realtime scheduler, to a first approximation you 
    2.88 +just want to cause simulation time jumps to consume real time. We propose 
    2.89 +doing this using a combination of sleep- and busy- waits. Sleep-waits cause 
    2.90 +the calling process (thread) to yield the processor for some amount of time. 
    2.91 +Even though this specified amount of time can be passed to nanosecond 
    2.92 +resolution, it is actually converted to an OS-specific granularity. 
    2.93 +In Linux, the granularity is called a Jiffy. Typically this resolution is 
    2.94 +insufficient for our needs (on the order of a ten milliseconds), so we 
    2.95 +round down and sleep for some smaller number of Jiffies. The process is 
    2.96 +then awakened after the specified number of Jiffies has passed. At this 
    2.97 +time, we have some residual time to wait. This time is generally smaller 
    2.98 +than the minimum sleep time, so we busy-wait for the remainder of the time. 
    2.99 +This means that the thread just sits in a for loop consuming cycles until 
   2.100 +the desired time arrives. After the combination of sleep- and busy-waits, 
   2.101 +the elapsed realtime (wall) clock should agree with the simulation time 
   2.102 +of the next event and the simulation proceeds. 
   2.103 +