[Ns-developers] handling API changes

Tom Henderson tomh at tomh.org
Wed Jul 30 07:23:30 PDT 2008

We've had a lot of traffic recently on dealing with backward
compatibility and API changes.  I'd like to suggest the following
proposal, which is basically along the lines of solving this issue with
documentation (sorry, Gustavo), because of the extra work of maintaining
a backward compatibility layer.

I propose to put a file in the top level directory called "changes.txt".
  This could also be kept as html to add more structure and make it more
browsable (e.g. ns-2 CHANGES.html):

This file would exist in parallel to RELEASE_NOTES and would read as
follows (I've attached a few examples of how this might be populated):

ns-3 is an evolving system and there will be API or behavioral changes
from time to time.   Users who try to use scripts or models across
versions of ns-3 may encounter problems at compile time, run time, or
may see the simulation output change.

We have adopted the development policy that we are going to try to ease
the impact of these changes on users by documenting these changes in a
single place (this file), and not by providing a temporary or permanent
backward-compatibility software layer.

The goal is that users who encounter a problem when trying to use older
code with newer code should be able to consult this file to find
guidance as to how to fix the problem.  For instance, if a method name
or signature has changed, it should be stated what the new replacement
name is.

Note that users who upgrade the simulator across versions, or who work
directly out of the development tree, may find that simulation output
changes even when the compilation doesn't break, such as when a
simulator default value is changed.  Therefore, it is good practice for
_anyone_ using code across multiple ns-3 releases to consult this file,
as well as the RELEASE_NOTES, to understand what has changed over time.

This file is a best-effort approach to solving this issue; we will do
our best but can guarantee that there will be things that fall through
the cracks, unfortunately.  If you, as a user, can suggest improvements
to this file based on your experience, please contribute a patch or drop
us a note on ns-developers mailing list.

| changes from ns-3.1 to ns-3.2 |

new API:

changes to existing API:

+++ 21-07-2008:  class NetDevice has added a pure virtual method that
must be implemented by all subclasses:

virtual void SetPromiscReceiveCallback (PromiscReceiveCallback cb) = 0;

All NetDevices must support this method, and must call this callback
when processing packets in the receive direction (the appropriate place
to call this is device-dependent).  An approach to stub this out
temporarily, if you do not care about immediately enabling this
functionality, would be to add this to your device:

(NetDevice::PromiscReceiveCallback cb)
   NS_ASSERT_MSG (false, "No implementation yet for

To implement this properly, consult the CsmaNetDevice for examples of
when the m_promiscRxCallback is called.

+++ 03-07-2008: change helper API

Rename all instances method names using "SetParameter" to "SetAttribute"

How to fix your code:  Any use of helper API that was using a method
"Set...Parameter()" should be changed to read "Set...Attribute()".  See
this changeset for more details:  3cdd9d60f7c7

changed behavior:

+++ 28-07-2008:  OLSR: HELLO messages hold time changed to 3*hello
interval from hello interval.

More information about the Ns-developers mailing list