3.7 Class EmbeddedTcl

ns permits the development of functionality in either compiled code, or through interpreter code, that is evaluated at initialization. For example, the scripts ~tclcl/tcl-object.tcl or the scripts in ~ns/tcl/lib. Such loading and evaluation of scripts is done through objects in the EmbeddedTcl../Tcl/Tcl.h.

The easiest way to extend ns is to add OTcl code to either ~tclcl/tcl-object.tcl or through scripts in the ~ns/tcl/lib directory. Note that, in the latter case, ns sources ~ns/tcl/lib/ns-lib.tcl automatically, and hence the programmer must add a couple of lines to this file so that their script will also get automatically sourced by ns at startup. As an example, the file ~ns/tcl/mcast/srm.tcl defines some of the instance procedures to run SRM. In ~ns/tcl/lib/ns-lib.tcl, we have the lines:

        source tcl/mcast/srm.tcl

to automatically get srm.tcl sourced by ns at startup.

Three points to note with EmbeddedTcl code are that firstly, if the code has an error that is caught during the eval, then ns will not run. Secondly, the user can explicitly override any of the code in the scripts. In particular, they can re-source the entire script after making their own changes. Finally, after adding the scripts to ~ns/tcl/lib/ns-lib.tcl, and every time thereafter that they change their script, the user must recompile ns for their changes to take effect. Of course, in most cases^3.4, the user can source their script to override the embedded code.

The rest of this subsection illustrate how to integrate individual scripts directly into ns. The first step is convert the script into an EmbeddedTcl object. The lines below expand ns-lib.tcl and create the EmbeddedTcl object instance called et_ns_lib:

        tclsh bin/tcl-expand.tcl tcl/lib/ns-lib.tcl | \bs
                               ../Tcl/tcl2c++ et_ns_lib \> gen/ns_tcl.cc

The script, ~ns/bin/tcl-expand.tcl../ns-2/tcl-expand.tcl expands ns-lib.tcl by replacing all source lines with the corresponding source files. The program, ~tclcl/tcl2cc.c../Tcl/tcl2c++.c.html, converts the OTcl code into an equivalent EmbeddedTcl object, et_ns_lib.

During initialization, invoking the method EmbeddedTcl::load explicitly evaluates the array.

--

~tclcl/tcl-object.tcl../Tcl/tcl-object.tcl is evaluated by the method Tcl::init../Tcl/Tcl.ccTcl::init; []Tcl_AppInit../ns-2/tclAppInit.cc::Tcl_AppInit invokes []Tcl::Init. The exact command syntax for the load is:

        et\_tclobject.load();

--

Similarly, ~ns/tcl/lib/ns-lib.tcl../ns-2/tcl/lib/ns-lib.tcl is evaluated directly by Tcl_AppInit in ~ns/ns_tclsh.cc.

        et\_ns\_lib.load();