Callbacks
*********

Some new users to ns-3 are unfamiliar with an extensively used programming idiom used throughout the code:  the ``ns-3 callback''.  This chapter provides some motivation on the callback, guidance on how to use it, and details on its implementation.

Motivation
==========

Consider that you have two simulation models A and B, and you wish to have them pass information between them during the simulation.  One way that you can do that is that you can make A and B each explicitly knowledgeable about the other, so that they can invoke methods on each other.

class A {
public:
  void ReceiveInput ( // parameters );
  ...
}

(in another source file:)

class B {
public:
  void DoSomething (void);
  ...

private:
  A* a_instance; // pointer to an A
}

void
B::DoSomething()
{
  // Tell a_instance that something happened
  a_instance->ReceiveInput ( // parameters);
  ...
}

This certainly works, but it has the drawback that it introduces a dependency on A and B to know about the other at compile time (this makes it harder to have independent compilation units in the simulator) and is not generalized; if in a later usage scenario, B needs to talk to a completely different C object, the source code for B needs to be changed to add a ``c_instance'' and so forth.  It is easy to see that this is a brute force mechanism of communication that can lead to programming cruft in the models.

This is not to say that objects should not know about one another if there is a hard dependency between them, but that often the model can be made more flexible if its interactions are less constrained at compile time.

This is not an abstract problem for network simulation research, but rather it has been a source of problems in previous simulators, when researchers want to extend or modify the system to do different things (as they are apt to do in research).  Consider, for example, a user who wants to add an IPsec security protocol sublayer between TCP and IP:
------------                   -----------
|   TCP    |                   |  TCP    |
------------                   -----------
     |           becomes ->        |
-----------                    -----------
|   IP    |                    | IPsec   |
-----------                    -----------
                                   |
                               -----------
                               |   IP    |
                               -----------
If the simulator has made assumptions, and hard coded into the code, that IP always talks to a transport protocol above, the user may be forced to hack the system to get the desired interconnections,  This is clearly not an optimal way to design a generic simulator.

Background
==========

Readers familiar with programming callbacks may skip this tutorial section.

The basic mechanism that allows one to address the problem above is known as a callback.  The ultimate goal is to allow one piece of code to call a function (or method in C++) without any specific inter-module dependency.

This ultimately means you need some kind of indirection -- you treat the address of the called function as a variable.  This variable is called a pointer-to-function variable.  The relationship between function and pointer-to-function pointer is really no different that that of object and pointer-to-object.

In C the canonical example of a pointer-to-function is a pointer-to-function-returning-integer (PFI).  For a PFI taking one int parameter, this could be declared like,

  int (*pfi)(int arg) = 0;

What you get from this is a variable named simply ``pfi'' that is initialized to the value 0.  If you want to initialize this pointer to something meaningful, you have to have a function with a matching signature.  In this case,

  int MyFunction (int arg) {}

If you have this target, you can initialize the variable to point to your function like,

  pfi = MyFunction;

You can then call MyFunction indirectly using the more suggestive form of the call,

  int result = (*pfi) (1234);

This is suggestive since it looks like you are dereferencing the function pointer just like you would dereference any pointer.  Typically, however, people take advantage of the fact that the compiler knows what is going on and will just use a shorter form,

  int result = pfi (1234);

Notice that the function pointer obeys value semantics, so you can pass it around like any other value.  Typically, when you use an asynchronous interface you will pass some entity like this to a function which will perform an action and ``call back'' to let you know it completed.  It calls back by following the indirection and executing the provided function.

In C++ you have the added complexity of objects.  The analogy with the PFI above means you have a pointer to a member function returning an int (PMI) instead of the pointer to function returning an int (PFI).

The declaration of the variable providing the indirection looks only slightly different,

  int (MyClass::*pmi) (int arg) = 0;

This declares a variable named ``pmi'' just as the previous example declared a variable named ``pfi.''  Since the will be to call a method of an instance of a particular class, one must declare that method in a class.

  class MyClass {
  public:
    int MyMethod (int arg);
  };

Given this class declaration, one would then initialize that variable like this,

  pmi = &MyClass::MyMethod;

This assigns the address of the code implementing the method to the variable, completing the indirection.  In order to call a method, the code needs a ``this'' pointer.  This, in turn, means there must be an object of MyClass to refer to. A simplistic example of this is just calling a method indirectly (think virtual function).

  int (MyClass::*pmi) (int arg) = 0;  // Declare a PMI
  pmi = &MyClass::MyMethod;           // Point at the implementation code

  MyClass myClass;                    // Need an instance of the class
  (myClass.*pmi) (1234);              // Call the method with an object ptr

Just like in the C example, you can use this in an asynchronous call to another module which will ``call back'' using a method and an object pointer.  The straightforward extension one might consider is to pass a pointer to the object and the PMI variable.  The module would just do,

  (*objectPtr.*pmi) (1234);

to execute the callback on the desired object.

One might ask at this time, ``what's the point''?  The called module will have to understand the concrete type of the calling object in order to properly make the callback.  Why not just accept this, pass the correctly typed object pointer and do object->Method(1234) in the code instead of the callback?  This is precisely the problem described above.  What is needed is a way to decouple the calling function from the called class completely.  This requirement led to the development of the Functor.

A functor is the outgrowth of something invented in the 1960s called a closure. It is basically just a packaged-up function call, possibly with some state.

A functor has two parts, a specific part and a generic part, related through inheritance.  The calling code (the code that executes the callback) will execute a generic overloaded operator () of a generic functor to cause the callback to be called.  The called code (the code that wants to be called back) will have to provide a specialized implementation of the operator () that performs the class-specific work that caused the close-coupling problem above.

With the specific functor and its overloaded operator () created, the called code then gives the specialized code to the module that will execute the callback (the calling code).

The calling code will take a generic functor as a parameter, so an implicit cast is done in the function call to convert the specific functor to a generic functor. This means that the calling module just needs to understand the generic functor type.  It is decoupled from the calling code completely.

The information one needs to make a specific functor is the object pointer and the pointer-to-method address.

The essence of what needs to happen is that the system declares a generic part of the functor,

  template <typename T>
  class Functor
  {
  public:
      virtual void operator() (T arg) = 0;
   };

The caller defines a specific part of the functor that really is just there to implement the specific operator() method,

  template <typname T, typename ARG>
  class SpecificFunctor : public Functor
   {
   public:
      SpecificFunctor(T* p, int (T::*_pmi)(ARG arg))
      {
        m_p = p;
        m_pmi = pmi;
      }

      virtual int operator() (ARG arg)
      {
        (*m_p.*m_pmi)(arg);
      }
  private:
      void (T::*m_pmi)(ARG arg);
      T* m_p;
   };

N.B. The previous code is not real ns-3 code.  It is simplistic example code used only to illustrate the concepts involved and to help you understand the system more.  Do not expect to find this code anywhere in the ns-3 tree

Notice that there are two variables defined in the class above.  The m_p variable is the object pointer and m_pmi is the variable containing the address of the function to execute.

Notice that when operator() is called, it in turn calls the method provided with the object pointer using the C++ PMI syntax.

To use this, one could then declare some model code that takes a generic functor as a parameter

  void LibraryFunction (Functor functor);

The code that will talk to the model would build a specific functor and pass it to LibraryFunction,

  MyClass myClass;
  SpecificFunctor<MyClass, int> functor (&myclass, MyClass::MyMethod);

When LibraryFunction is done, it executes the callback using the operator() on the generic functor it was passed, and in this particular case, provides the integer argument:

  void
  LibraryFunction (Functor functor)
  {
    // Ececute the library function
    functor(1234);
  }

Notice that LibraryFunction is completely decoupled from the specific type of the client.  The connection is made through the Functor polymorphism.

The Callback API in ns-3 implements object-oriented callbacks using the functor mechanism.  This callback API, being based on C++ templates, is type-safe; that is, it performs static type checks to enforce proper signature compatibility between callers and callees.  It is therefore more type-safe to use than traditional function pointers, but the syntax may look imposing at first.  This section is designed to walk you through the Callback system so that you can be comfortable using it in ns-3.

Using the Callback API
======================

The Callback API is fairly minimal, providing only two services:

  * callback type declaration: a way to declare a type of callback with a given signature, and,

  * callback instantiation: a way to instantiate a template-generated forwarding callback which can forward any calls to another C++ class member method or C++ function.

This is best observed via walking through an example, based on samples/main-callback.cc.

Using the Callback API with static functions
--------------------------------------------

Consider a function:

  static double
  CbOne (double a, double b)
  {
    std::cout << "invoke cbOne a=" << a << ", b=" << b << std::endl;
    return a;
  }

Consider also the following main program snippet:

  int main (int argc, char *argv[])
  {
    // return type: double
    // first arg type: double
    // second arg type: double
    Callback<double, double, double> one;
  }

This is an example of a C-style callback -- one which does not include or need a this pointer.  The function template Callback is esentially the declaration of the variable containing the pointer-to-function.  In the example above, we explicitly showed a pointer to a function that returned an integer and took a single integer as a parameter,  The Callback template function is a generic version of that -- it is used to declare the type of a callback.

Note1: Readers unfamiliar with C++ templates may consult this reference.

The Callback template requires one mandatory argument (the return type of the function to be assigned to this callback) and up to five optional arguments, which each specify the type of the arguments (if your particular callback function has more than five arguments, then this can be handled by extending the callback implementation).

So in the above example, we have a declared a callback named "one" that will eventually hold a function pointer.  The signature of the function that it will hold must return double and must support two double arguments.  If one tries to pass a function whose signature does not match the declared callback, the compilation will fail.

Now, we need to tie together this callback instance and the actual target function (CbOne).  Notice above that CbOne has the same function signature types as the callback-- this is important.  We can pass in any such properly-typed function to this callback.  Let's look at this more closely:

static double CbOne (double a, double b) {}
          ^           ^          ^
          |        ---|    ------|
          |        |       |
Callback<double, double, double> one;

You can only bind a function to a callback if they have the matching signature. The first template argument is the return type, and the additional template arguments are the types of the arguments of the function signature.

Now, let's bind our callback "one" to the function that matches its signature:

  // build callback instance which points to cbOne function
  one = MakeCallback (&CbOne);

This call to MakeCallback is, in essence, creating one of the specialized functors mentioned above.  The variable declared using the Callback template function is going to be playing the part of the generic functor.  The assignment one = MakeCallback (&CbOne) is the cast that converts the specialized functor known to the callee to a generic functor known to the caller.

Then, later in the program, if the callback is needed, it can be used as follows:
  NS_ASSERT (!one.IsNull ());

  // invoke cbOne function through callback instance
  double retOne;
  retOne = one (10.0, 20.0);

The check for IsNull() ensures that the callback is not null -- that there is a function to call behind this callback.  Then, one() executes the generic operator() which is really overloaded with a specific implementation of operator() and returns the same result as if CbOne() had been called directly.

Using the Callback API with member functions
--------------------------------------------

Generally, you will not be calling static functions but instead public member functions of an object.  In this case, an extra argument is needed to the MakeCallback function, to tell the system on which object the function should be invoked.  Consider this example, also from main-callback.cc:

  class MyCb {
  public:
    int CbTwo (double a) {
        std::cout << "invoke cbTwo a=" << a << std::endl;
        return -5;
    }
  };

  int main ()
  {
    ...
    // return type: int
    // first arg type: double
    Callback<int, double> two;
    MyCb cb;
    // build callback instance which points to MyCb::cbTwo
    two = MakeCallback (&MyCb::CbTwo, &cb);
    ...
  }

Here, we pass an additional object pointer to the MakeCallback<> function. Recall from the background section above that Operator() will use the pointer to member syntax when it executes on an object:

      virtual int operator() (ARG arg)
      {
        (*m_p.*m_pmi)(arg);
      }

And so we needed to provide the two variables (m_p and m_pmi) when we made the specific functor.  The line,

    two = MakeCallback (&MyCb::CbTwo, &cb);

does precisely that.  In this case,

When two () is invoked,

  int result = two (1.0);

I will result in a call the CbTwo member function (method) on the object pointed to by &cb.

Building Null Callbacks
-----------------------

It is possible for callbacks to be null; hence it may be wise to check before using them.  There is a special construct for a null callback, which is preferable to simply passing "0" as an argument; it is the MakeNullCallback<> construct:

  two = MakeNullCallback<int, double> ();
  NS_ASSERT (two.IsNull ());

Invoking a null callback is just like invoking a null function pointer: it will crash at runtime.

Bound Callbacks
===============

A very useful extension to the functor concept is that of a Bound Callback. Previously it was mentioned that closures were originally function calls packaged up for later execution.  Notice that in all of the Callback descriptions above, there is no way to package up any parameters for use later -- when the Callback is called via operator().  All of the parameters are provided by the calling function.

What if it is desired to allow the client function (the one that provides the callback) to provide some of the parameters?  Alexandrescu calls the process of allowing a client to specify one of the parameters binding.  One of the parameters of operator() has been bound (fixed) by the client.

Some of our pcap tracing code provides a nice example of this.  There is a function that needs to be called whenever a packet is received.  This function calls an object that actually writes the packet to disk in the pcap file format.  The signature of one of these functions will be,

  static void SniffEvent (Ptr<PcapWriter> writer, Ptr<const Packet> packet);

The static keyword means this is a static function which does not need a this pointer, so it will be using C-style callbacks.  We don't want the calling code to have to know about anything but the Packet.  What we want there is just a call that looks like,

  m_promiscSnifferTrace (m_currentPkt);

What we want to do is to bind the Ptr<PcapWriter> writer to the specific callback implementation when it is created and arrange for the operator() of the Callback to provide that parameter for free.

We provide the MakeBoundCallback template function for that purpose.  It takes the same parameters as the MakeCallback template function but also takes the parameters to be bound.  In the case of the example above,

    MakeBoundCallback (&CsmaHelper::SniffEvent, pcap));

will create a specific callback implementation that knows to add in the extra bound arguments.  Conceptually, it extends the specific functor described above with one or more bound arguments

  template <typname T, typename ARG, typename BOUND_ARG>
  class SpecificFunctor : public Functor
   {
   public:
      SpecificFunctor(T* p, int (T::*_pmi)(ARG arg), BOUND_ARG boundArg)
      {
        m_p = p;
        m_pmi = pmi;
        m_boundArg = boundArg;
      }

      virtual int operator() (ARG arg)
      {
        (*m_p.*m_pmi)(m_boundArg, arg);
      }
  private:
      void (T::*m_pmi)(ARG arg);
      T* m_p;
      BOUND_ARG m_boundArg;
   };

You can see that when the specific functor is created, the bound argument is saved in the functor / callback object itself.  When the operator() is invoked with the single parameter, as in

  m_promiscSnifferTrace (m_currentPkt);

the imlpementation of operator() adds the bound parameter into the actual function call:

  (*m_p.*m_pmi)(m_boundArg, arg);

Traced Callbacks
================

Placeholder subsection

Callback locations in ns-3
==========================

Callback locations in ns-3
==========================

Where are callbacks frequently used in ns-3?  Here are some of the more visible ones to typical users:

  * Socket API

  * Layer-2/Layer-3 API

  * Tracing subsystem

  * API between IP and routing subsystems

Implementation details
======================

The code snippets above are simplistic and only designed to illustrate the mechanism itself.  The actual Callback code is quite complicated and very template-intense and a deep understanding of the code is not required.  If interested, expert users may find the following useful:

The code was originally written based on the techniques described in http://www.codeproject.com/cpp/TTLFunction.asp. It was subsequently rewritten to follow the architecture outlined in Modern C++ Design: Generic Programming and Design Patterns Applied-- Alexandrescu, chapter 5, "Generalized Functors".

This code uses:

  * default template parameters to saves users from having to specify empty parameters when the number of parameters is smaller than the maximum supported number

  * the pimpl idiom: the Callback class is passed around by value and delegates the crux of the work to its pimpl pointer.

  * two pimpl implementations which derive from CallbackImpl FunctorCallbackImpl can be used with any functor-type while MemPtrCallbackImpl can be used with pointers to member functions.

  * a reference list implementation to implement the Callback's value semantics.

This code most notably departs from the Alexandrescu implementation in that it does not use type lists to specify and pass around the types of the callback arguments. Of course, it also does not use copy-destruction semantics and relies on a reference list rather than autoPtr to hold the pointer.