Manual: Applications and transport agent API

From nsnam
Revision as of 23:29, 23 July 2008 by Lachlan (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Previous Chapter "PLM" | Index | Next Chapter "Web cache as an application"

Applications sit on top of transport agents in ns. There are two basic types of applications: traffic generators and simulated applications. Figure 39.1 illustrates two examples of how applications are composed and attached to transport agents. Transport agents are described in Part V (Transport).

This chapter first describes the base class Application. Next, the transport API, through which applications request services from underlying transport agents, is described. Finally, the current implementations of traffic generators and sources are explained.

The class Application

Application is a C++ class defined as follows:

class Application : public TclObject {
public:
  Application();
  virtual void send(int nbytes);
  virtual void recv(int nbytes);
  virtual void resume();
protected:
  int command(int argc, const char*const* argv);
  virtual void start();
  virtual void stop();
  Agent *agent_;
  int enableRecv_; // call OTcl recv or not
  int enableResume_; // call OTcl resume or not
};

Although objects of class Application are not meant to be instantiated, we do not make it an abstract base class so that it is visible from OTcl level. The class provides basic prototypes for application behavior (send(), recv(), resume(), start(), stop()), a pointer to the transport agent to which it is connected, and flags that indicate whether a OTcl-level upcall should be made for recv() and resume() events.

The transport agent API

In real-world systems, applications typically access network services through an applications programming interface (API). The most popular of these APIs is known as “sockets.” In ns, we mimic the behavior of the sockets API through a set of well-defined API functions. These functions are then mapped to the appropriate internal agent functions (e.g., a call to send(numBytes) causes TCP to increment its “send buffer” by a corresponding number of bytes).

This section describes how agents and applications are hooked together and communicate with one another via the API.

Attaching transport agents to nodes

This step is typically done at OTcl level. Agent management was also briefly discussed in the chapter on Nodes and Packet Forwarding.

set src [new Agent/TCP/FullTcp]
set sink [new Agent/TCP/FullTcp]
$ns_ attach-agent $node_(s1) $src
$ns_ attach-agent $node_(k1) $sink
$ns_ connect $src $sink

The above code illustrates that in ns, agents are first attached to a node via attach-agent. Next, the connect instproc sets each agent’s destination target to the other. Note that, in ns, connect() has different semantics than in regular sockets. In ns, connect() simply establishes the destination address for an agent, but does not set up the connection. As a result, the overlying application does not need to know its peer’s address. For TCPs that exchange SYN segments, the first call to send() will trigger the SYN exchange.

To detach an agent from a node, the instproc detach-agent can be used; this resets the target for the agent to a null agent.

Attaching applications to agents

After applications are instantiated, they must be connected to a transport agent. The attach-agent method can be used to attach an application to an agent, as follows:

set ftp1 [new Application/FTP]
$ftp1 attach-agent $src

The following shortcut accomplishes the same result:

set ftp1 [$src attach-app FTP]

The attach-agent method, which is also used by attach-app, is implemented in C++. It sets the agent_ pointer in class Application to point to the transport agent, and then it calls attachApp() in agent.cc to set the app_ pointer to point back to the application. By maintaining this binding only in C++, OTcl-level instvars pointers are avoided and consistency between OTcl and C++ is guaranteed. The OTcl-level command [$ftp1 agent] can be used by applications to obtain the handler for the transport agent.

Using transport agents via system calls

Once transport agents have been configured and applications attached, applications can use transport services via the following system calls. These calls can be invoked at either OTcl or C++ level, thereby allowing applications to be coded in either C++ or OTcl. These functions have been implemented as virtual functions in the base class Agent, and can be redefined as needed by derived Agents.

  • send(int nbytes)—Send nbytes of data to peer. For TCP agents, if nbytes == -1, this corresponds to an "infinite" send; i.e., the TCP agent will act as if its send buffer is continually replenished by the application.
  • sendmsg(int nbytes, const char* flags = 0)—Identical to send(int nbytes), except that it passes an additional string flags. Currently one flag value, "MSG_EOF," is defined; MSG_EOF specifies that this is the last batch of data that the application will submit, and serves as an implied close (so that TCP can send FIN with data).
  • close()—Requests the agent to close the connection (only applicable for TCP).
  • listen()—Requests the agent to listen for new connections (only applicable for Full TCP).
  • set_pkttype(int pkttype)—This function sets the type_ variable in the agent to pkttype. Packet types are defined in packet.h. This function is used to override the transport layer packet type for tracing purposes.

Note that certain calls are not applicable for certain agents; e.g., a call to close() a UDP connection results in a no-op. Additional calls can be implemented in specialized agents, provided that they are made public member functions.

Agent upcalls to applications

Since presently in ns there is no actual data being passed between applications, agents can instead announce to applications the occurrence of certain events at the transport layer through “upcalls.” For example, applications can be notified of the arrival of a number of bytes of data; this information may aid the application in modelling real-world application behavior more closely. Two basic “upcalls” have been implemented in base class Application and in the transport agents:

  • recv(int nbytes)—Announces that nbytes of data have been received by the agent. For UDP agents, this signifies the arrival of a single packet. For TCP agents, this signifies the “delivery” of an amount of in-sequence data, which may be larger than that contained in a single packet (due to the possibility of network reordering).
  • resume()—This indicates to the application that the transport agent has sent out all of the data submitted to it up to that point in time. For TCP, it does not indicate whether the data has been ACKed yet, only that it has been sent out for the first time.

The default behavior is as follows: Depending on whether the application has been implemented in C++ or OTcl, these C++ functions call a similarly named (recv, resume) function in the application, if such methods have been defined.

Although strictly not a callback to applications, certain Agents have implemented a callback from C++ to OTcl-level that has been used by applications such as HTTP simulators. This callback method, done{}, is used in TCP agents. In TCP, done{} is called when a TCP sender has received ACKs for all of its data and is now closed; it therefore can be used to simulate a blocked TCP connection. The done{} method was primarily used before this API was completed, but may still be useful for applications that do not want to use resume().

To use done{} for FullTcp, for example, you can try:

set myagent [new Agent/TCP/FullTcp]
$myagent proc done
... code you want ...

If you want all the FullTCP’s to have the same code you could also do:

Agent/TCP/FullTcp instproc done
... code you want ...

By default, done{} does nothing.

An example

Here is an example of how the API is used to implement a simple application (FTP) on top of a FullTCP connection.

set src [new Agent/TCP/FullTcp]
set sink [new Agent/TCP/FullTcp]
$ns_ attach-agent $node_(s1) $src
$ns_ attach-agent $node_(k1) $sink
$ns_ connect $src $sink
# set up TCP-level connections
$sink listen;
$src set window_ 100
set ftp1 [new Application/FTP]
$ftp1 attach-agent $src
$ns_ at 0.0 "$ftp1 start"

In the configuration script, the first five lines of code allocates two new FullTcp agents, attaches them to the correct nodes, and "connects" them together (assigns the correct destination addresses to each agent). The next two lines configure the TCP agents further, placing one of them in LISTEN mode. Next, ftp1 is defined as a new FTP Application, and the attach-agent method is called in C++ (app.cc).

The ftp1 application is started at time 0:

Application/FTP instproc start {} {
  [$self agent] send -1; # Send indefinitely
}

Alternatively, the FTP application could have been implemented in C++ as follows:

void FTP::start()
{
  agent_->send(-1); // Send indefinitely
}

Since the FTP application does not make use of callbacks, these functions are null in C++ and no OTcl callbacks are made.

The class TrafficGenerator

TrafficGenerator is an abstract C++ class defined as follows:

class TrafficGenerator : public Application {
public:
  TrafficGenerator();
  virtual double next_interval(int &) = 0;
  virtual void init() {}
  virtual double interval() { return 0; }
  virtual int on() { return 0; }
  virtual void timeout();
  virtual void recv() {}
  virtual void resume() {}
protected:
  virtual void start();
  virtual void stop();
  double nextPkttime_;
  int size_;
  int running_;
  TrafficTimer timer_;
};

The pure virtual function next_interval() returns the time until the next packet is created and also sets the size in bytes of the next packet. The function start() calls init(void) and starts the timer. The function timeout() sends a packet and reschedules the next timeout. The function stop() cancels any pending transmissions. Callbacks are typically not used for traffic generators, so these functions (recv, resume) are null.

Currently, there are four C++ classes derived from the class TrafficGenerator:

  1. EXPOO_Traffic—generates traffic according to an Exponential On/Off distribution. Packets are sent at a fixed rate during on periods, and no packets are sent during off periods. Both on and off periods are taken from an exponential distribution. Packets are constant size.
  2. POO_Traffic—generates traffic according to a Pareto On/Off distribution. This is identical to the Exponential On/Off distribution, except the on and off periods are taken from a pareto distribution. These sources can be used to generate aggregate traffic that exhibits long range dependency.
  3. CBR_Traffic—generates traffic according to a deterministic rate. Packets are constant size. Optionally, some randomizing dither can be enabled on the interpacket departure intervals.
  4. TrafficTrace—generates traffic according to a trace file. Each record in the trace file consists of 2 32-bit fields in network (big-endian) byte order. The first contains the time in microseconds until the next packet is generated. The second contains the length in bytes of the next packet.

These classes can be created from OTcl. The OTcl classes names and associated parameters are given below:

Exponential On/Off An Exponential On/Off object is embodied in the OTcl class Application/Traffic/Exponential. The member variables that parameterize this object are:

packetSize_ the constant size of the packets generated
burst_time_ the average “on” time for the generator
idle_time_ the average “off” time for the generator
rate_ the sending rate during “on” times

Hence a new Exponential On/Off traffic generator can be created and parameterized as follows:

set e [new Application/Traffic/Exponential]
$e set packetSize_ 210
$e set burst_time_ 500ms
$e set idle_time_ 500ms
$e set rate_ 100k

NOTE: The ExponentialOn/Off generator can be configured to behave as a Poisson process by setting the variable burst_time_ to 0 and the variable rate_ to a very large value. The C++ code guarantees that even if the burst time is zero, at least one packet is sent. Additionally, the next interarrival time is the sum of the assumed packet transmission time (governed by the variable rate_) and the random variate corresponding to idle_time_. Therefore, to make the first term in the sum very small, make the burst rate very large so that the transmission time is negligible compared to the typical idle times.


Pareto On/Off A Pareto On/Off object is embodied in the OTcl class Application/Traffic/Pareto. The member variables that parameterize this object are:

packetSize_ the constant size of the packets generated
burst_time_ the average "on" time for the generator
idle_time_ the average "off" time for the generator
rate_ the sending rate during "on" times
shape_ the "shape" parameter used by the pareto distribution

A new Pareto On/Off traffic generator can be created as follows:

set p [new Application/Traffic/Pareto]
$p set packetSize_ 210
$p set burst_time_ 500ms
$p set idle_time_ 500ms
$p set rate_ 200k
$p set shape_ 1.5


CBR A CBR object is embodied in the OTcl class Application/Traffic/CBR. The member variables that parameterize this object are:

rate_ the sending rate
interval_ (Optional) interval between packets
packetSize_ the constant size of the packets generated
random_ flag indicating whether or not to introduce random “noise” in the scheduled departure times (default is off)
maxpkts_ the maximum number of packets to send (default is (228)

Hence a new CBR traffic generator can be created and parameterized as follows:

set e [new Application/Traffic/CBR]
$e set packetSize_ 48
$e set rate_ 64Kb
$e set random_ 1

The setting of a CBR object’s rate_ and interval_ are mutually exclusive (the interval between packets is maintained as an interval variable in C++, and some example ns scripts specify an interval rather than a rate). In a simulation, either a rate or an interval (but not both) should be specified for a CBR object.


Traffic Trace A Traffic Trace object is instantiated by the OTcl class Application/Traffic/Trace. The associated class Tracefile is used to enable multiple Traffic/Trace objects to be associated with a single trace file. The Traffic/Trace class uses the method attach-tracefile to associate a Traffic/Trace object with a particular Tracefile object. The method filename of the Tracefile class associates a trace file with the Tracefile object. The following example shows how to create two Application/Traffic/Trace objects, each associated with the same trace file (called "example-trace" in this example). To avoid synchronization of the traffic generated, random starting places within the trace file are chosen for each Traffic/Trace object.

set tfile [new Tracefile]
$tfile filename example-trace
set t1 [new Application/Traffic/Trace]
$t1 attach-tracefile $tfile
set t2 [new Application/Traffic/Trace]
$t2 attach-tracefile $tfile

An example

The following code illustrates the basic steps to configure an Exponential traffic source over a UDP agent, for traffic flowing from node s1 to node k1:

set src [new Agent/UDP]
set sink [new Agent/UDP]
$ns_ attach-agent $node_(s1) $src
$ns_ attach-agent $node_(k1) $sink
$ns_ connect $src $sink
set e [new Application/Traffic/Exponential]
$e attach-agent $src
$e set packetSize_ 210
$e set burst_time_ 500ms
$e set idle_time_ 500ms
$e set rate_ 100k
$ns_ at 0.0 "$e start"

Simulated applications: Telnet and FTP

There are currently two “simulate application” classes derived from Application: Application/FTP and Application/Telnet. These classes work by advancing the count of packets available to be sent by a TCP transport agent. The actual transmission of available packets is still controlled by TCP’s flow and congestion control algorithm.

Application/FTP Application/FTP, implemented in OTcl, simulates bulk data transfer. The following are methods of the Application/FTP class:

attach-agent attaches an Application/FTP object to an agent.
start start the Application/FTP by calling the TCP agent’s send(-1) function, which causes TCP to behave as if the application were continuously sending new data.
stop stop sending.
produce n set the counter of packets to be sent to n.
producemore n increase the counter of packets to be sent by n.
send n similar to producemore, but sends n bytes instead of packets.


Application/Telnet Application/Telnet objects generate packets in one of two ways. If the member variable interval_ is non-zero, then inter-packet times are chosen from an exponential distribution with average equal to interval_. If interval_ is zero, then inter-arrival times are chosen according to the tcplib distribution (see tcplib-telnet.cc). The start method starts the packet generation process.

Applications objects

An application object may be of two types, a traffic generator or a simulated application. Traffic generator objects generate traffic and can be of four types, namely, exponential, pareto, CBR and traffic trace.

Application/Traffic/Exponential objects Exponential traffic objects generate On/Off traffic. During "on" periods, packets are generated at a constant burst rate. During "off" periods, no traffic is generated. Burst times and idle times are taken from exponential distributions. Configuration parameters are:

PacketSize_ constant size of packets generated.
burst_time_ average on time for generator.
idle_time_ average off time for generator.
rate_ sending rate during on time.


Application/Traffic/Pareto Application/Traffic/Pareto objects generate On/Off traffic with burst times and idle times taken from pareto distributions. Configuration parameters are:

PacketSize_ constant size of packets generated.
burst_time_ average on time for generator.
idle_time_ average off time for generator.
rate_ sending rate during on time.
shape_ the shape parameter used by pareto distribution.


Application/Traffic/CBR CBR objects generate packets at a constant bit rate. $cbr start

Causes the source to start generating packets.

$cbr stop

Causes the source to stop generating packets.

Configuration parameters are:

PacketSize_ constant size of packets generated.
rate_ sending rate.
interval_ (optional) interval between packets.
random_ whether or not to introduce random noise in the scheduled departure times. defualt is off.
maxpkts_ maximum number of packets to send.

Application/Traffic/Trace Application/Traffic/Trace objects are used to generate traffic froma trace file.

$trace attach-tracefile tfile

Attach the Tracefile object tfile to this trace. The Tracefile object specifies the trace file from which the traffic data is to be read. Multiple Application/Traffic/Trace objects can be attached to the same Tracefile object. A random starting place within the Tracefile is chosen for each Application/Traffic/Trace object.

There are no configuration parameters for this object.

A simulated application object can be of two types, Telnet and FTP.


Application/Telnet TELNET objects produce individual packets with inter-arrival times as follows. If interval_ is non-zero, then inter-arrival times are chosen from an exponential distribution with average interval_. If interval_ is zero, then inter-arrival times are chosen using the "tcplib" telnet distribution.

$telnet start

Causes the Application/Telnet object to start producing packets.

$telnet stop

Causes the Application/Telnet object to stop producing packets.

$telnet attach <agent>

Attaches a Telnet object to agent.

Configuration Parameters are:

interval_ The average inter-arrival time in seconds for packets generated by the Telnet object.


Application FTP FTP objects produce bulk data for a TCP object to send.

$ftp start

Causes the source to produce maxpkts_ packets.

$ftp produce <n>

Causes the FTP object to produce n packets instantaneously.

$ftp stop

Causes the attached TCP object to stop sending data.

$ftp attach agent

Attaches a Application/FTP object to agent.

$ftp producemore <count>

Causes the Application/FTP object to produce count more packets.

Configuration Parameters are:

maxpkts The maximum number of packets generated by the source.

TRACEFILE OBJECTS Tracefile objects are used to specify the trace file that is to be used for generating traffic (see Application/Traffic/Trace objects described earlier in this section). $tracefile is an instance of the Tracefile Object.

$tracefile filename <trace-input>

Set the filename from which the traffic trace data is to be read to trace-input.

There are no configuration parameters for this object. A trace file consists of any number of fixed length records. Each record consists of 2 32 bit fields. The first indicates the interval until the next packet is generated in microseconds. The second indicates the length of the next packet in bytes.

Commands at a glance

Following are some transport agent and application related commands commonly used in simulation scripts:

set tcp1 [new Agent/TCP]
$ns_ attach-agent $node_(src) $tcp1
set sink1 [new Agent/TCPSink]
$ns_ attach-agent $node_(snk) $sink1
$ns_ connect $tcp1 $sink1

This creates a source tcp agent and a destination sink agent. Both the transport agents are attached to their resoective nodes.

Finally an end-to-end connection is setup between the src and sink.

set ftp1 [new Application/FTP]
$ftp1 attach-agent $agent

or set ftp1 [$agent attach-app FTP] Both the above commands achieve the same. An application (ftp in this example) is created and attached to the source agent. An application can be of two types, a traffic generator or a simulated application. Types of Traffic generators currently present are: Application/Traffic/Exponential, Application/Traffic/Pareto, Application/Traffic/CBR, and Application/Traffic/Trace. See the above section on [#The class TrafficGenerator|the class TrafficGenerator]] for details. Types of simulated applications currently implemented are: Application/FTP and Application/Telnet. See the above section on Telnet and FTP for details.

Previous Chapter "PLM" | Index | Next Chapter "Web cache as an application"