[Ns-developers] Proposed Simulator Changes

[Mathieu Lacage]

On Mon, 2008-10-13 at 11:45 -0700, craigdo at ee.washington.edu wrote:
> [ ... ]
> 
> > > > 1) I see that ::RunOneEvent is not implemented in 
> > > > RealtimeSimulatorImpl.
> > > > Is it not possible to implement it by a single call to 
> > > > ProcessOneEvent ?
> > > 
> > > It can be made to run, but what do you expect it to do?  It 
> > certainly
> > > isn't
> > 
> > I expect it to do what it does already, that is, synchronize on the
> > wall-clock and execute one event. 
> 
> Well, now it (being ns-3-dev) doesn't do anything.  This is what needs to be
> clarified.
> 
> The wall clock is free-running and completely asynchronous with respect to
> the simulation time.  In order to "synchronize on the wall-clock" you need
> to establish a relationship between the wall-clock and the simulator clock.
> There are a number of things you can do; and the semantics result in very
> different behavior and use cases are limited one way or another.
> 
> 1) When you call RunOneEvent, you can set the origin of the normalized real
> time to the time of _last_ event executed (m_currentTs); and then wait for
> the time of the _next_ event in the queue.  In this case, you will consume
> the real time that would have been executed between the events had the main
> event loop been executed.  This removes processing times from something like
> the visualizer from the equation, but limits the system to a 1:1
> relationship between sim clock and real clock.
> 
> 2) When you call RunOneEvent, you can synchronize real time with the _next_
> event executed (m_currentTs), and wait for the time of the _next_ event in
> the queue.  This effectively turns off real-time mode and executes the next

yes.

> event immediately.  You might as well not even introduce real-time into the
> equation.  This would mean RunOneEvent for real-time is basically the
> RunOneEvent from the non-real-time case.  This allows something like a
> visualizer to completely control the timing (in conjunction with
> Simulator::next()) in a simulation but really isn't real-time at all.

I don't really understand the end of the above paragraph but the
beginning of 2) describes what I was expecting RunOne to do.

> 3) Provide some additional method to establish the origin of real-time with
> respect to simulation time (like Run() does).  When you then subsequently
> call RunOneEvent, it will wait for the time of the _next_ event in the
> queue.  In this case, you do a real-time simulation but are calling into the
> processing loop from the outside; but the "responsibility" for the
> real-time-ness is shared between caller and callee.
> 
> You privately sent me a patch that just called ProcessOneEvent from
> RunOneEvent.  This patch provided no synchronization between real-time clock
> and simulation clock -- it apparently relied on the fact that the real-time
> clock was running asynchronously and had a huge value most of the time.
> This had the effect of making every event "late"; and then caused those
> events to be executed immediately.  I think you accidentally implemented

I think that my code is sleeping quite a bit on the synchronizer when
calling this RunOneEvent. I will double-check this later today.

> case two.
>
> If you want to add the functionality, you really need to tell me which one
> of these cases, or an entirely different one I haven't mentioned, you want
> to support, since the user-visible behavior (and responsibilities) may be
> quite different.
> 
> I think the most flexible thing to do is case two (just make it
> non-real-time), but this really doesn't have anything to do with
> "synchroniz[ing] on the wall-clock."  What you would gain by making this
> feature possible in the real-time simulator would be the multithreaded
> behavior and the ability to schedule events from emu or tap devices.  It
> would mean that ScheduleRealNow would just effectively be treated as
> ScheduleFromAnotherThread.
>
> 
> > This has allowed me to run gustavo's
> > visualizer successfully, which, as far as I am concerned, is 
> > good-enough
> > for now. We can revisit that implementation later if someone complains
> > about it.
> > 
> > > > If you feel that the 'Real' keyword is not
> > > > sufficiently-explicit, 'Realtime' or 'WallClock' seem fine:
> > > > 
> > > > class Simulator 
> > > > {
> > > > static void ScheduleXXX (Time delay, ...);
> > > > static void ScheduleXXXNow (...);
> > > > static Time XXXNow (void);
> > > > };
> > > > 
> > > > where XXX is one of Real, Realtime, RealTime, WallClock.
> > > 
> > > I could be convinced that moving these methods back into Simulator
> > > would be
> > > okay if we plastered enough warning signs all over them.  If you
> > > actually
> > 
> > Feel free to do so, ?but, please, make sure that no method 
> > documentation
> > is longer than 3 paragraphs.
> 
> Is this some kind of new and undiscussed documentation requirement that you
> have unilaterally decided on?  I always thought that documentation should be
> sufficient to document the behavior of the function.

This kind of irony is not very productive: you know very well that I
don't want insufficient documentation and I am fairly certain that you
know why I added that comment because I already mentioned the below to
you while casually chatting. When I read, 'plastering enough warning
signs' from craig, I know that it means 2-page comments inserted in the
documentation and I believe that this makes the documentation useless:
no one reads a 2-page documentation for a function. 

So, I am not asking you to make the documentation be insufficient: I am
asking you to make your sufficient documentation fit a 3-paragraph limit
and I would like to add another constraint: no paragraph should be
longer than 5 lines. I think that it will improve the usefulness of the
resulting documentation and I specifically added this comment for you
because you are the only person to generate such prolific documentation.

If you consider this to be an unfair unilateral decision, I would be
happy to submit that specific request for larger discussion among ns3
maintainers and defer the decision to a consensus but I believe that the
above request is pretty reasonable for the code I maintain and falls
within the bounds of maintainer authority.

regards,
Mathieu