TCL/OTCL

Adding a new class to NS

The need for a new (program object) class
- There will come a time when making small changes to the existing code in NS is no longer adequate to implement the changes that you want to make to a protocol.
- When that time comes, you will need to write a completely new class.
Relationship between NS and OTcl
- You need to realise that the program line to create a new agent uses a built-in class definition in the OTCL programming language.
- Example:
  Agent/TCP/Reno (BTW, slashes "/" are considered as ordinary characters in OTcl) is the name of an existing class in the OTcl language interpreter
  (Now the ordinary OTcl language interpreter does not have this class, the people who made NS expanded OTcl to include this class)
- So, the NS simulator is actually an extended TCL language interpreter:
- You can add new commands into the NS "language"
- The type of the new commands that can add can be:
  - new nodes (i.e., nodes that have a new routing method)
  - new links (i.e., queues that have a new queueing method)
  - new agents (i.e., agents that have a new transport layer protocol)
  - ..

How to add a new class to NS

Method outline:

Write the class that you want to add in C++
This class must contain the method int command(int argc, char **argv)
(OTcl will invoke the method command when an object command is used in an OTcl program)
Write a special purpose static who only purpose is to execute code that make OTcl associate an identifier (make sure you pick a unique identifier) with the new C++ class.

Step 1 in adding a new class to NS: writing a new "MyAgent" class

Suppose we want to add a new Agent class to NS
By "a new Agent" class, I mean a class that inherits from the NS Agent class
(Afterall, C++ is an Object Oriented programming language and you can save a lot of programming work by inheriting from the proper class that is already defined in NS)
However, the new MyAgent class is not going to be a super-duper TCP protocol (Agents in NS are transport layer entities).
Nope, in fact, the MyAgent class is kinda dumb and has only 2 methods that print some internal variables.
The point of the exercise is keep things simple to show you what you need to do to add a new Agent class.
(A new super-duper TCP protocol agent will make things so messy that you may not understand how things work between C++ and OTcl).

Here is a simple C++ class "MyAgent" that inherits from the NS class "Agent":

// *********************** // Include files... // *********************** #include <stdio.h> #include <string.h> #include "agent.h" // The MyAgent class is a subclass of Agent // So we need to include the definition of "Agent"
// *********************** // Class header // *********************** class MyAgent : public Agent // Inherits from the NS Agent class { public: MyAgent(); // Constructor - used to bind C++ and Tcl variable names protected: int command(int argc, const char*const* argv); // This C++ method gets called when OTcl // executes a command associated with a MyAgent object // The structure of this method is usually a huge switch statement... private: int my_var1; // Variable 1 double my_var2; // Variable 2 void MyPrivFunc(void); void showvars(void); // These functions are called from within "command()" // to do the actual work };
// *********************** // Class Body // *********************** /* ----------------------------------------------------------- Constructor: this method is used to bind variable names in the C++ class to OTcl ----------------------------------------------------------- */ MyAgent::MyAgent() : Agent(PT_UDP) { bind("my_var1_otcl", &my_var1); // Bind C++ var my_var1 to OTcl name my_var1_otcl bind("my_var2_otcl", &my_var2); // Bind C++ var my_var2 to OTcl name my_var2_otcl } /* --------------------------------------------------------------------------- command: MAIN entry point from a OTcl method call using an MyAgent object. When TCL executes a command: MyAgent-type-Object x y z Then, this "command" method is invoked with "x" "y" "z" as argv[] parameters to this "command" method !!! --------------------------------------------------------------------------- */ int MyAgent::command(int argc, const char* const* argv) { /* ----------------------------------------------------------- In this example, we tries to detect 2 possible commands for argv[1]: ----------------------------------------------------------- */ if (strcmp(argv[1], "call-my-priv-func") == 0) { MyPrivFunc(); // invoke the corresponding implementation return(TCL_OK); } else if (strcmp(argv[1], "showvars") == 0) { showvars(); // invoke the corresponding implementation return(TCL_OK); } /* ----------------------------------------------------------- If we arrived here, the command issued was not one of those implemented by MyAgent. But since MyAgent is an Agent, it inherits ALL agent commands. So let Agent handle it... ----------------------------------------------------------- */ return(Agent::command(argc, argv)); } /* -------------------------------------------------------------- MyPrivFunc(): shows how to invoke TCL commands within C++ This function is "dispatched" through the "command()" method The statements of this method looks "strange" because it is not C++ code but shows how to use Tcl inside C++... -------------------------------------------------------------- */ void MyAgent::MyPrivFunc(void) { Tcl& tcl = Tcl::instance(); // Create a Tcl interpreter tcl.eval("puts \"Message From MyPrivFunc\""); tcl.evalf("puts \" my_var1 = %d\"", my_var1); tcl.evalf("puts \" my_var2 = %f\"", my_var2); } /* -------------------------------------------------------------- showvars(): shows an ordinary C++ function This function is "dispatched" through the "command()" method This function contain "ordinary" C++ statements... --------------------------------------------------------------- */ void MyAgent::showvars(void) { printf("** my_var1 = %d\n", my_var1); printf("** my_var2 = %lf\n", my_var2); }

TclClass: the magic to associate a C++ class to an OTcl command

The OTcl interpreter is written in C++
There is a special class named TclClass defined in the OTcl interpreter
The TclClass class constructor takes a class name (string) as an argument and has the side effect of registering that new name as a newly supported class type in OTcl.
To use the TclClass class, we inherit from this class and create our own constructor that invoke the constructor in the parent (TclClass) class

Example:

NOTE:

We used a static class (that's the common practice in NS)
Static classes in C++ are classes that do not contain instance members (other than those inherited from the class Object) and do not have a callable constructor.

The class name (in the example: Agent/MyAgentOtcl ) is hierarchical .
So we can explicitly define class hierarchies in OTcl using a pathname syntax.
Example:
The TclClass class contains a (virtual) method called create(int argc, char **argv).
(Note: in C++, only virtual methods in a class can be overriden by a method in the subclass)
When the OTcl interpreter executes the (OTcl) command:
the OTcl interpreter will invoke the method create(int argc, char **argv) in the TclClass class (because we used the string "Agent/MyAgentClass" as argument in TclClass("Agent/MyAgentOtcl") )
The inherited version of the create(int argc, char **argv) method will not create the right object - we need to override it with one that create an object that we want (i.e., MyAgentClass)
Now, when the create(int argc, char **argv) is run and at the end, it must return a pointer to the newly created object.
OTcl can now use this pointer to invoke the command() method (the main entry point for all OTcl objects).
Hene, to complete the C++/OTcl linkage, we must implement the create(int argc, char **argv) ourselves by writing code to create a new MyAgent object instance and return a pointer to the newly created MyAgent object.

Example:

static class MyAgentClass : public TclClass { public: /* ----------------------------------------------------------- Constructor Invokes the constructor of the parent class (TclClass) The method TclClass registers the name "Agent/MyAgentOtcl" as a newly supported OTcl class ----------------------------------------------------------- */ MyAgentClass() : TclClass("Agent/MyAgentOtcl") {} /* ----------------------------------------------------------- Overridden create(argc, argv): This method is invoked by OTcl interpreter when [new Agent/MyAgentOtcl] is executed We must override the inheritted method and create our MyAgent object !!! ----------------------------------------------------------- */ TclObject* create(int argc, const char*const* argv) { return(new MyAgent()); } }

Step 2 in adding a new class to NS: associate C++ "MyAgent" class with OTcl identifier "Agent/MyAgentOtcl"

We just learned the mechanics to associate the C++ class MyAgent with the OTcl identifier Agent/MyAgentOtcl
We have written the create() method for OTcl to execute.
Although we have written the constructor MyAgentClass() that executes the registering command: TclClass("Agent/MyAgentOtcl") , the statement has NOT yet been executed !!!

What we still need to do is:

Make C++ execute the code :

MyAgentClass() : TclClass("Agent/MyAgentOtcl") { }

ONCE

To make the OTcl interpreter execute the constructor MyAgentClass(), we need to define a variable of the type MyAgentClass.

This can be done as follows:

static class MyAgentClass : public TclClass { public: /* ----------------------------------------------------------- Constructor Invokes the constructor of the parent class (TclClass) The method TclClass registers the name "Agent/MyAgentOtcl" as a newly supported OTcl class ----------------------------------------------------------- */ MyAgentClass() : TclClass("Agent/MyAgentOtcl") {} /* ----------------------------------------------------------- create(argc, argv): Method is invoked by OTcl interpreter when [new Agent/MyAgentOtcl] is executed We must take care of creating the actual MyAgent object ourselves ----------------------------------------------------------- */ TclObject* create(int argc, const char*const* argv) { return(new MyAgent()); } } MyAgentClass dummy; // Dummy variable definition // This variable is not used anywhere // The purpose is to force OTcl interpreter to // execute the constructor in MyAgentClass ONCE

In C++, you can define a variable immediately following a class definition

That's why, you often see the following construct:

static class MyAgentClass : public TclClass { public: /* ----------------------------------------------------------- Constructor Invokes the constructor of the parent class (TclClass) The method TclClass registers the name "Agent/MyAgentOtcl" as a newly supported OTcl class ----------------------------------------------------------- */ MyAgentClass() : TclClass("Agent/MyAgentOtcl") {} /* ----------------------------------------------------------- create(argc, argv): Method is invoked by OTcl interpreter when [new Agent/MyAgentOtcl] is executed We must take care of creating the actual MyAgent object ourselves ----------------------------------------------------------- */ TclObject* create(int argc, const char*const* argv) { return(new MyAgent()); } } MyAgentClass dummy;

How to use the new "MyAgent" class in OTcl
- You can use the new MyAgent class through the OTcl identifier Agent/MyAgentOtcl
- To create a MyAgent object, use:
  The OTcl command "[new Agent/MyAgentOtcl]" triggers OTcl to invoke the "create(0, null)" (because there is no further arguments in [new Agent/MyAgentOtcl]) in the "MyAgentClass".
  This in turn, invokes "new MyAgent()" and returns an MyAgent object and asigned to the OTcl variable x.
- To set an "instance variable in the MyAgent, just use the set command in OTcl.
  Examples:
- The following example shows how to invoke a method in the MyAgent object x:
- This is what happens behind the scenes:
  When OTcl executes:
  The OTcl interpreter will execute the method:
  Look at the implementation of the command() function ( click here ) and you will see that:
  - $x call-my-priv-func will execute the function MyPrivFunc(void)
  - $x showvars will execute the function showvars(void)

Adding the "MyAgent" class to NS (OTcl)
- It best to store the source file for "MyAgent" in a separate directory.
  I stored it in:
  - 01-MyAgent/MyAgent.cc: click here
- Add the following line in NS's Makefile to tell the make utility to include the MyAgent.cc file in the compilation:
  You can see the modified Makefile: click here
- Finally, we need to initialize the instance variables (you only need to initialized the bound instance variables) by adding the following lines in ns-default.tcl :
- Example Program: (Demo above code)
  - The MyAgent prog file (contains "MyAgent" and the linkage class): click here
  - The modified Makefile: click here
  - The modified ns-default.tcl: click here
  - A OTcl script to test the new MyAgent class: click here