[Ns-developers] simulator API roadmap

[Gustavo Carneiro]

On Fri, Apr 2, 2010 at 12:02 PM, Mathieu Lacage <
mathieu.lacage at sophia.inria.fr> wrote:

> Since the simulator API is one of the last pieces of code I still
> maintain, I wanted to update everyone on my plans/roadmap for this
> module so, here it is. Feedback is welcome, as usual.
>
> The main idea behind the following roadmap is that I would like to close
> bug 631 by introducing a thread-safe event scheduling function which
> would also be a way to merge a small part of the multithreaded
> simulation scheduler branch. I know that the API outlined below and
> described in bug 631 is potentially conflictual (based on the last
> comments in that bug report) but we need to make a decision and move on.
>
> [maintainer hat on] My take on this issue is the following:
>
> i. there are very users of RunOneEvent/Next. i.e., there is gustavo.
>
> ii. RunOneEvent/Next do not work with the realtime scheduler and the
> multithreaded scheduler and the mpi scheduler. i.e., they work only with
> our default scheduler. That makes them fairly useless.
>
> iii. there is a way for the users of RunOneEvent/Next to use threads and
> a thread-safe ScheduleWithContext to achieve what they need. It's more
> complicated than using RunOneEvent/Next but it will work and this will
> impact only one person and I promised I would provide patches to migrate
> existing code to the new API as needed.
>
> With the above said, if no new comments are made, I do plan to go
> forward with the following plan for 3.8/3.9.
>
> 1) For ns-3.8, mark Simulator::Next and Simulator::RunOneEvent as
> deprecated. I would like to checkin the trivial patch which does this
> before the 3.8 release: josh, is it ok from the perspective of the
> release schedule if I do this early next week ?
>
> 2) For ns-3.8, change the API of the currently-unused function
> Simulator::ScheduleWithContext. From:
> static void ScheduleWithContext (uint32_t context, Time const &time,
> const Ptr<EventImpl> &event);
> To:
> static void ScheduleWithContext (uint32_t context, Time const &time,
> const EventImpl * event);
>
> Document that the callee (ScheduleWithContext) takes ownership of the
> caller reference count. i.e, the caller must not call Unref after
> calling ScheduleWithContext. The rationale for this change is that the
> plan when ScheduleWithContext was introduced was to make it thread-safe
> but the current API forces the caller to call Unref on the EventImpl
> which forces us to make the EventImpl reference counting operations
> thread-safe which has a performance impact.
>
> As such, in the interest of performance (everyone would have to pay the
> cost of a thread-safe EventImpl although only the python binding
> implementer will call the ScheduleWithContext function above), it's
> better to break our reference counting rules here and use a special
> adhoc policy for the event pointer argument of this function. Because
> this function will be used in only one location (in the wrapper of the
> python bindings), I feel fairly comfortable with this special rule.
>
> Although I have local patches which implement the python binding of this
> function, I have little time in the 3.8 release timeframe to work on
> them and it's getting late for the release cycle so, I would like to
> merge _only_ the API change _now_ and merge early in 3.9 the python
> binding implementation.
>
> 2) Early in 3.9, I would like to:
>
>  - introduce uint32_t Simulator::GetSystemId (uint32_t context) which I
> am using in the multithreaded scheduler and which josh and I discussed
> as something he could use for the mpi scheduler.
>
>  - merge the thread-safe implementation of ScheduleWithContext for all
> simulator implementations
>
>  - merge the python binding implementation of ScheduleWithContext
>
> 3) late in 3.9, I would like to remove Simulator::Next/RunOneEvent.
>
>
Why not make Simulator::RunOneEvent only available in a downcasted class?

I mean, the functionality is there, I don't see what maintenance effort will
be required to just make an existing method public...

I don't really care if PyViz works with real-time scheduler or mpi or
whatever; it's not supposed to work---or even needed to work---with anything
but the simplest scheduler.


> Again, all of the above are things I have patches for already and all of
> them have gone through some fairly serious testing but given our current
> state in the release cycle, it's way too late to merge any real code
> which is why I would like to split this stuff in 2 main parts: first,
> the API changes/deprecations now and, then, in 3.9, the implementations
> and removal of deprecated functions.


>
> Mathieu
>
>


-- 
Gustavo J. A. M. Carneiro
INESC Porto, UTM, WiN, http://win.inescporto.pt/gjc
"The universe is always one step beyond logic." -- Frank Herbert