The ns Manual (formerly ns Notes and Documentation)1 - NM Lab at ...
The ns Manual (formerly ns Notes and Documentation)1 - NM Lab at ... The ns Manual (formerly ns Notes and Documentation)1 - NM Lab at ...
Chapter 3OTcl Linkagens is an object oriented simulator, written in C++, with an OTcl interpreter as a frontend. The simulator supports a classhierarchy in C++ (also called the compiled hierarchy in this document), and a similar class hierarchy within the OTcl interpreter(also called the interpreted hierarchy in this document). The two hierarchies are closely related to each other; from theuser’s perspective, there is a one-to-one correspondence between a class in the interpreted hierarchy and one in the compiledhierarchy. The root of this hierarchy is the class TclObject. Users create new simulator objects through the interpreter; theseobjects are instantiated within the interpreter, and are closely mirrored by a corresponding object in the compiled hierarchy.The interpreted class hierarchy is automatically established through methods defined in the class TclClass. user instantiatedobjects are mirrored through methods defined in the class TclObject. There are other hierarchies in the C++ code and OTclscripts; these other hierarchies are not mirrored in the manner of TclObject.3.1 Concept OverviewWhy two languages? ns uses two languages because simulator has two different kinds of things it needs to do. On one hand,detailed simulations of protocols requires a systems programming language which can efficiently manipulate bytes, packetheaders, and implement algorithms that run over large data sets. For these tasks run-time speed is important and turn-aroundtime (run simulation, find bug, fix bug, recompile, re-run) is less important.On the other hand, a large part of network research involves slightly varying parameters or configurations, or quickly exploringa number of scenarios. In these cases, iteration time (change the model and re-run) is more important. Since configurationruns once (at the beginning of the simulation), run-time of this part of the task is less important.ns meets both of these needs with two languages, C++ and OTcl. C++ is fast to run but slower to change, making it suitablefor detailed protocol implementation. OTcl runs much slower but can be changed very quickly (and interactively), making itideal for simulation configuration. ns (via tclcl) provides glue to make objects and variables appear on both langauges.For more information about the idea of scripting languages and split-language programming, see Ousterhout’s article in IEEEComputer [26]. For more information about split level programming for network simulation, see the ns paper [2].Which language for what? Having two languages raises the question of which language should be used for what purpose.Our basic advice is to use OTcl:• for configuration, setup, and “one-time” stuff19
• if you can do what you want by manipulating existing C++ objectsand use C++:• if you are doing anything that requires processing each packet of a flow• if you have to change the behavior of an existing C++ class in ways that weren’t anticipatedFor example, links are OTcl objects that assemble delay, queueing, and possibly loss modules. If your experiment can bedone with those pieces, great. If instead you want do something fancier (a special queueing dicipline or model of loss), thenyou’ll need a new C++ object.There are certainly grey areas in this spectrum: most routing is done in OTcl (although the core Dijkstra algorithm is in C++).We’ve had HTTP simulations where each flow was started in OTcl and per-packet processing was all in C++. This approacheworked OK until we had 100s of flows starting per second of simulated time. In general, if you’re ever having to invoke Tclmany times per second, you problably should move that code to C++.3.2 Code OverviewIn this document, we use the term “interpreter” to be synonymous with the OTcl interpreter. The code to interface with theinterpreter resides in a separate directory, tclcl. The rest of the simulator code resides in the directory, ns-2. We will usethe notation ~tclcl/〈file〉 to refer to a particular 〈file〉 in the Tcl directory. Similarly, we will use the notation, ~ns/〈file〉 torefer to a particular 〈file〉 in the ns-2 directory.There are a number of classes defined in ~tclcl/. We only focus on the six that are used in ns: The Class Tcl (Section 3.3)contains the methods that C++ code will use to access the interpreter. The class TclObject (Section 3.4) is the base class forall simulator objects that are also mirrored in the compiled hierarchy. The class TclClass (Section 3.5) defines the interpretedclass hierarchy, and the methods to permit the user to instantiate TclObjects. The class TclCommand (Section 3.6) is used todefine simple global interpreter commands. The class EmbeddedTcl (Section 3.7) contains the methods to load higher levelbuiltin commands that make configuring simulations easier. Finally, the class InstVar (Section 3.8) contains methods to accessC++ member variables as OTcl instance variables.The procedures and functions described in this chapter can be found in ~tclcl/Tcl.{cc, h}, ~tclcl/Tcl2.cc, ~tclcl/tcl-object.tcl,and, ~tclcl/tracedvar.{cc, h}. The file ~tclcl/tcl2c++.c is used in building ns, and is mentioned briefly in this chapter.3.3 Class TclThe class Tcl encapsulates the actual instance of the OTcl interpreter, and provides the methods to access and communicatewith that interpreter. The methods described in this section are relevant to the ns programmer who is writing C++ code.The class provides methods for the following operations:• obtain a reference to the Tcl instance;• invoke OTcl procedures through the interpreter;• retrieve, or pass back results to the interpreter;• report error situations and exit in an uniform manner; and20
- Page 6 and 7: 18 Radio Propagation Models 17718.1
- Page 8 and 9: 30 Multicast Routing 25130.1 Multic
- Page 10 and 11: 38.2.5 An example . . . . . . . . .
- Page 12 and 13: X Other 40347 Educational use of NS
- Page 14: # so, we lied. now, we define the t
- Page 17 and 18: Chapter 2Undocumented FacilitiesNs
- Page 19: Part IInterface to the Interpreter1
- Page 23 and 24: • tcl.result(const char* s)Pass t
- Page 25 and 26: By convention in ns, the class Agen
- Page 27 and 28: $object set bwvar 1500kb$object set
- Page 29 and 30: For a C++ variable to be traceable,
- Page 31 and 32: 3.5 Class TclClassThis compiled cla
- Page 33 and 34: class Packet {......static int hdrl
- Page 35 and 36: The actual arguments passed by the
- Page 37 and 38: class TclClass (Section 3.5) define
- Page 39 and 40: Chapter 4The Class SimulatorThe ove
- Page 41 and 42: 4.2.2 the heap schedulerThe heap sc
- Page 43 and 44: 4.4 Commands at a glanceSynopsis:ns
- Page 45 and 46: $ns_ dumpqCommand for dumping event
- Page 47 and 48: NODEPortClassifierAgentAgentAddrCla
- Page 49 and 50: The Node instance variable, entry_,
- Page 51 and 52: The default values for all the abov
- Page 53 and 54: The classify() method is pure virtu
- Page 55 and 56: };The class imposes no direct seman
- Page 57 and 58: flow-specific queuing disciplines a
- Page 59 and 60: 5.5 Routing Module and Classifier O
- Page 61 and 62: Module NameRtModule/BaseRtModule/Mc
- Page 63 and 64: $node neighborsThis returns the lis
- Page 65 and 66: Linkhead_enqT_queue_ deqT_ link_ tt
- Page 67 and 68: 6.2 ConnectorsConnectors, unlink cl
- Page 69 and 70: $ns_ link-lossmodel This function
Chapter 3OTcl Linkage<strong>ns</strong> is an object oriented simul<strong>at</strong>or, written in C++, with an OTcl interpreter as a frontend. <strong>The</strong> simul<strong>at</strong>or supports a classhierarchy in C++ (also called the compiled hierarchy in this document), <strong>and</strong> a similar class hierarchy within the OTcl interpreter(also called the interpreted hierarchy in this document). <strong>The</strong> two hierarchies are closely rel<strong>at</strong>ed to each other; from theuser’s perspective, there is a one-to-one correspondence between a class in the interpreted hierarchy <strong>and</strong> one in the compiledhierarchy. <strong>The</strong> root of this hierarchy is the class TclObject. Users cre<strong>at</strong>e new simul<strong>at</strong>or objects through the interpreter; theseobjects are i<strong>ns</strong>tanti<strong>at</strong>ed within the interpreter, <strong>and</strong> are closely mirrored by a corresponding object in the compiled hierarchy.<strong>The</strong> interpreted class hierarchy is autom<strong>at</strong>ically established through methods defined in the class TclClass. user i<strong>ns</strong>tanti<strong>at</strong>edobjects are mirrored through methods defined in the class TclObject. <strong>The</strong>re are other hierarchies in the C++ code <strong>and</strong> OTclscripts; these other hierarchies are not mirrored in the manner of TclObject.3.1 Concept OverviewWhy two languages? <strong>ns</strong> uses two languages because simul<strong>at</strong>or has two different kinds of things it needs to do. On one h<strong>and</strong>,detailed simul<strong>at</strong>io<strong>ns</strong> of protocols requires a systems programming language which can efficiently manipul<strong>at</strong>e bytes, packetheaders, <strong>and</strong> implement algorithms th<strong>at</strong> run over large d<strong>at</strong>a sets. For these tasks run-time speed is important <strong>and</strong> turn-aroundtime (run simul<strong>at</strong>ion, find bug, fix bug, recompile, re-run) is less important.On the other h<strong>and</strong>, a large part of network research involves slightly varying parameters or configur<strong>at</strong>io<strong>ns</strong>, or quickly exploringa number of scenarios. In these cases, iter<strong>at</strong>ion time (change the model <strong>and</strong> re-run) is more important. Since configur<strong>at</strong>ionru<strong>ns</strong> once (<strong>at</strong> the beginning of the simul<strong>at</strong>ion), run-time of this part of the task is less important.<strong>ns</strong> meets both of these needs with two languages, C++ <strong>and</strong> OTcl. C++ is fast to run but slower to change, making it suitablefor detailed protocol implement<strong>at</strong>ion. OTcl ru<strong>ns</strong> much slower but can be changed very quickly (<strong>and</strong> interactively), making itideal for simul<strong>at</strong>ion configur<strong>at</strong>ion. <strong>ns</strong> (via tclcl) provides glue to make objects <strong>and</strong> variables appear on both langauges.For more inform<strong>at</strong>ion about the idea of scripting languages <strong>and</strong> split-language programming, see Ousterhout’s article in IEEEComputer [26]. For more inform<strong>at</strong>ion about split level programming for network simul<strong>at</strong>ion, see the <strong>ns</strong> paper [2].Which language for wh<strong>at</strong>? Having two languages raises the question of which language should be used for wh<strong>at</strong> purpose.Our basic advice is to use OTcl:• for configur<strong>at</strong>ion, setup, <strong>and</strong> “one-time” stuff19
Change language