27.1.1 OTcl Helper Functions

The following helper functions may be used within simulation scripts to help in attaching trace elements (see ~ns/tcl/lib/ns-lib.tcl); they are instance procedures of the class Simulator:

flush-trace {} flush buffers for all trace objects in simulation

create-trace { type file src dst } create a trace object of type type between the given src and dest nodes. If file is non-null, it is interpreted as a Tcl channel and is attached to the newly-created trace object. The procedure returns the handle to the newly created trace object.

trace-queue { n1 n2 file } arrange for tracing on the link between nodes n1 and n2. This function calls create-trace, so the same rules apply with respect to the file argument.

trace-callback{ ns command } arranges to call command when a line is to be traced. The procedure treats command as a string and evaluates it for every line traced. See ~ns/tcl/ex/callback_demo.tcl for additional details on usage.

monitor-queue { n1 n2 } this function calls the init-monitor function on the link between nodes n1 and n2.

drop-trace { n1 n2 trace } the given trace object is made the drop-target of the queue associated with the link between nodes n1 and n2.

The []create-trace procedure is used to create a new Trace object of the appropriate kind and attach an Tcl I/O channel to it (typically a file handle). The src _ and dst _ fields are are used by the underlying C++ object for producing the trace output file so that trace output can include the node addresses defining the endpoints of the link which is being traced. Note that they are not used for matching. Specifically, these values in no way relate to the packet header src and dst fields, which are also displayed when tracing. See the description of the Trace class below (Section ).

The trace-queue function enables Enque, Deque, and Drop tracing on the link between nodes n1 and n2. The Link trace procedure is described below (Section ).

The monitor-queue function is constructed similarly to trace-queue. By calling the link's init-monitor procedure, it arranges for the creation of objects (SnoopQueue and QueueMonitor objects) which can, in turn, be used to ascertain time-aggregated queue statistics.

The drop-trace function provides a way to specify a Queue's drop target without having a direct handle of the queue.

Tom Henderson 2014-12-17

`flush-trace {}`	flush buffers for all trace objects in simulation
`create-trace { type file src dst }`	create a trace object of type type between the given src and dest nodes. If file is non-null, it is interpreted as a Tcl channel and is attached to the newly-created trace object. The procedure returns the handle to the newly created trace object.
`trace-queue { n1 n2 file }`	arrange for tracing on the link between nodes n1 and n2. This function calls create-trace, so the same rules apply with respect to the file argument.
`trace-callback{ ns command }`	arranges to call `command` when a line is to be traced. The procedure treats `command` as a string and evaluates it for every line traced. See ~ns/tcl/ex/callback_demo.tcl for additional details on usage.
`monitor-queue { n1 n2 }`	this function calls the `init-monitor` function on the link between nodes n1 and n2.
`drop-trace { n1 n2 trace }`	the given trace object is made the drop-target of the queue associated with the link between nodes n1 and n2.