agents.tex

柯老师网站上找到的

\%
% personal commentary:
%        handlers and how they are used are confusing
%        Connector::send is needed, but so is just send()... confusing
%        default handler in Connector::recv is confusing
%        this is a DRAFT DRAFT DRAFT
%        - KFALL
%
\chapter{Agents}
\label{sec:agents}

Agents represent endpoints where network-layer
packets are constructed or consumed, and are used in the implementation
of protocols at various layers.
%Generally, a user wishing to create a new
%source or sink for network-layer packets
%will create a class derived from {\tt Agent}.
The \clsref{Agent}{../ns-2/agent.h} has an implementation partly in
OTcl and partly in C++.
The C++ implementation is contained in \nsf{agent.cc} and
\nsf{agent.h}, and the OTcl support is in
\nsf{tcl/lib/ns-agent.tcl}.

\section{Agent state}
\label{sec:agentstate}

The C++ \clsref{Agent}{../ns-2/agent.h} includes enough internal state
to assign various fields to a simulated packet before
it is sent.
This state includes the following:

\begin{tabularx}{\linewidth}{rX}
\code{addr\_} & node address of myself (source address in packets) \\
\code{dst\_} & where I am sending packets to \\
\code{size\_} & packet size in bytes (placed into the common packet header) \\
\code{type\_} & type of packet (in the common header, see packet.h) \\
\code{fid\_} & the IP flow identifier (formerly {\em class} in ns-1) \\
\code{prio\_} & the IP priority field \\
\code{flags\_} & packet flags (similar to ns-1) \\
\code{defttl\_} & default IP ttl value \\
\end{tabularx}

These variables may be modified by any class derived from \code{Agent},
although not all of them may be needed by any particular agent.

\section{Agent methods}
\label{sec:agentmethods}

The \clsref{Agent}{../ns-2/agent.h} supports packet generation and reception.
The following member functions are implemented by the C++ Agent class, and are
generally {\em not} over-ridden by derived classes:

\begin{tabularx}{\linewidth}{rX}
\fcn[]{Packet* allocpkt} & allocate new packet and assign its fields \\
\fcn[int]{Packet* allocpkt} & allocate new packet with a data payload of n bytes and assign its fields \\
\end{tabularx}

The following member functions are also defined by the class Agent,
but {\em are} intended to be over-ridden by classes deriving from Agent:

\begin{tabularx}{\linewidth}{rX}
  \fcn[timeout number]{void timeout} & subclass-specific time out method \\
  \fcn[Packet*, Handler*]{void recv} & receiving agent main receive path \\
\end{tabularx}

The \fcn[]{allocpkt} method is used by derived classes
to create packets to send.
The function fills in the following fields
\href{in the common packet header}{Section}{chap:pformat}:
{\tt uid, ptype, size}, and the following fields in the IP header:
{\tt src, dst, flowid, prio, ttl}.
It also zero-fills in the following fields of the Flags header:
{\tt ecn, pri, usr1, usr2}.
Any packet header information not included in these lists must
be must be handled in the classes derived from \code{Agent}.

The \fcn[]{recv} method is the main entry point for an
Agent which receives packets, and
is invoked by upstream nodes when sending a packet.
In most cases, Agents make no use of the second argument (the handler
defined by upstream nodes).

\section{Protocol Agents}
\label{sec:protoagents}

There are several agents supported in the simulator.
These are their names in OTcl:

\begin{longtable}{rl}
  TCP & a ``Tahoe'' TCP sender (cwnd = 1 on any loss)   \\
  TCP/Reno & a ``Reno'' TCP sender  (with fast recovery)        \\
  TCP/NewReno & a modified Reno TCP sender (changes fast recovery)      \\
  TCP/Sack1 & a SACK TCP sender \\
  TCP/Fack & a ``forward'' SACK sender TCP      \\
  TCP/FullTcp & a more full-functioned TCP with 2-way traffic   \\
  TCP/Vegas & a ``Vegas'' TCP sender    \\
  TCP/Vegas/RBP & a Vegas TCP with ``rate based pacing''        \\
  TCP/Vegas/RBP & a Reno TCP with ``rate based pacing'' \\
  TCP/Asym & an experimental Tahoe TCP for asymmetric links     \\
  TCP/Reno/Asym & an experimental Reno TCP for asymmetric links \\
  TCP/Newreno/Asym & an experimental NewReno TCP for asymmetric links   \\
  TCPSink & a Reno or Tahoe TCP receiver (not used for FullTcp) \\
  TCPSink/DelAck & a TCP delayed-ACK receiver   \\
  TCPSink/Asym & an experimental  TCP sink for asymmetric links \\
  TCPSink/Sack1 & a SACK TCP receiver   \\
  TCPSink/Sack1/DelAck & a delayed-ACK SACK TCP receiver        \\
        \\
  UDP & a basic UDP agent\\
	\\
  RTP & an RTP sender and receiver  \\
  RTCP & an RTCP sender and receiver    \\
        \\
  LossMonitor & a packet sink which checks for losses   \\
        \\
  IVS/Source & an IVS source    \\
  IVS/Receiver & an IVS receiver        \\
        \\
  CtrMcast/Encap & a ``centralised multicast'' encapsulator     \\
  CtrMcast/Decap & a ``centralised multicast'' de-encapsulator  \\
  Message & a protocol to carry textual messages        \\
  Message/Prune & processes multicast routing prune messages    \\
        \\
  SRM & an SRM agent with non-adaptive timers   \\
  SRM/Adaptive & an SRM agent with adaptive timers      \\
        \\
  Tap & interfaces the simulator to a live network      \\
        \\
  Null & a degenerate agent which discards packets      \\
        \\
  rtProto/DV & distance-vector routing protocol agent   \\
\end{longtable}

Agents are used in the implementation of protocols at various layers.
Thus, for some transport protocols (e.g.~UDP) the distribution
of packet sizes and/or inter-departure times
may be dictated by some separate
object representing the demands of an application.  To this end, agents
expose an application programming interface (API) to the application.
For agents used in the implementation of lower-layer protocols
(e.g. routing agents), size and departure timing is generally dictated
by the agent's own processing of protocol messages.

\section{OTcl Linkage}
\label{sec:agentotcl}

Agents may be created within OTcl and an agent's internal
state can be modified by use of Tcl's \code{set} function and
any Tcl functions an Agent (or its base classes) implements.
Note that some of an Agent's internal state may exist
only within OTcl, and is thus is not directly accessible from C++.

\subsection{Creating and Manipulating Agents}
\label{sec:agentcreateotcl}

The following example illustrates the creation and modification
of an Agent in OTcl:
\begin{program}
        set newtcp [new Agent/TCP] \; create new object (and C++ shadow object);
        $newtcp set window_ 20 \; sets the tcp agent's window to 20;
        $newtcp target $dest \; target is implemented in Connector class;
        $newtcp set portID_ 1 \; exists only in OTcl, not in C++;
\end{program}

\subsection{Default Values}
\label{sec:agentdefaults}

Default values for member variables, those visible in OTcl only and those
linked between OTcl and C++ with \code{bind} are initialized
in the \nsf{tcl/lib/ns-default.tcl} file.  For example,
\code{Agent} is initialized as follows:
\begin{program}
        Agent set fid_ 0
        Agent set prio_ 0
        Agent set addr_ 0
        Agent set dst_ 0
        Agent set flags_ 0
\end{program}

Generally these initializations are placed in the OTcl namespace
before any objects of these types are created.
Thus, when an \code{Agent} object
is created, the calls to \code{bind}
in the objects' constructors will causes the corresponding member variables
to be set to these specified defaults.

\subsection{OTcl Methods}
\label{sec:agentmethodsotcl}

The instance procedures defined for the OTcl \code{Agent} class are
currently found in \nsf{tcl/lib/ns-agent.tcl}.
They are as follows:
\begin{tabularx}{\linewidth}{rX}
\code{port} & the agent's port identifier \\
\code{dst-port} & the destination's port identifier \\
\code{attach-source \tup{stype}} & create and attach a Source object to an agent \\
\end{tabularx}

\section{Examples: Tcp, TCP Sink Agents}
\label{sec:agentexample}

The \clsref{TCP}{../ns-2/tcp.h} represents a simplified TCP sender.
It sends data to a \code{TCPSink} agent and processes its acknowledgments.
It has a separate object associated with it which represents
an application's demand.
By looking at the \clsref{TCPAgent}{../ns-2/tcp.h} and
 \clsref{TCPSinkAgent}{../ns-2/tcp-sink.h},
we may see how relatively complex agents are constructed.
An example from the Tahoe TCP agent \code{TCPAgent} is also given
to illustrate the use of timers.

\subsection{Creating the Agent}
\label{sec:createtcpsimple}

The following OTcl code fragment creates a \code{TCP} agent
and sets it up:
\begin{program}
        set tcp [new Agent/TCP]         \; create sender agent;
        $tcp set fid_ 2                 \; set IP-layer flow ID;
        set sink [new Agent/TCPSink]    \; create receiver agent;
        $ns attach-agent $n0 $tcp       \; put sender on node $n0;
        $ns attach-agent $n3 $sink      \; put receiver on node $n3;
        $ns connect $tcp $sink          \; establish TCP connection;
        set ftp [new Application/FTP]        \; create an FTP source "application";
        $ftp attach-agent $tcp            \; associate FTP with the TCP sender;
        $ns at 1.2 "$ftp start"  \;arrange for FTP to start at time 1.2 sec;
\end{program}
The OTcl instruction \code{new Agent/TCP} results in the
creation of a C++ \code{TcpAgent} class object.
It's constructor performs first invokes the constructor of the
\code{Agent} base class and then performs its own bindings.
These two constructors appear as follows:
\begin{program}
{\rm The TcpSimpleAgent constructor (\nsf{tcp.cc}):}

        TcpAgent::TcpAgent() : Agent(PT_TCP), rtt_active_(0), rtt_seq_(-1),
                        rtx_timer_(this), delsnd_timer_(this)
        \{
                bind("window_", &wnd_);
                bind("windowInit_", &wnd_init_);
                bind("windowOption_", &wnd_option_);
                bind("windowConstant_", &wnd_const_);
                \ldots
                bind("off_ip_", &off_ip_);
                bind("off_tcp_", &off_tcp_);
                \ldots
        \}

{\rm The Agent constructor (\nsf{agent.cc}):}

        Agent::Agent(int pkttype) : 
                addr_(-1), dst_(-1), size_(0), type_(pkttype), fid_(-1),
                prio_(-1), flags_(0)
        \{
                memset(pending_, 0, sizeof(pending_)); \* timers */
                // {\cf this is really an IP agent, so set up}
                // {\cf for generating the appropriate IP fields\ldots}
                bind("addr_", (int*)&addr_);
                bind("dst_", (int*)&dst_);
                bind("fid_", (int*)&fid_);
                bind("prio_", (int*)&prio_);
                bind("flags_", (int*)&flags_);
                \ldots
        \}
\end{program}
These code fragments illustrate the common case where an agent's
constructor passes a packet type identifier to the \code{Agent}
constructor.
The values for the various packet types are
\href{used by the packet tracing facility}{Section}{sec:traceptype}
and are defined in \nsf{trace.h}.
The variables which are bound in the \code{TcpAgent} constructor
are ordinary instance/member variables for the class
with the exception of the special integer values \code{off_tcp_}
and \code{off_ip_}.
These are needed in order to access a TCP header and IP header, respectively.
\href{Additional details are in the section on packet headers}{Section}{%
        sec:ppackethdr}.

Note that the \code{TcpAgent} constructor contains initializations for
two timers, \code{rtx_timer_} and \code{delsnd_timer_}.

\code{TimerHandler} 
objects are initialized by providing a pointer (the \code{this} pointer) to
the relevant agent.

\subsection{Starting the Agent}
\label{sec:starttcp}

The \code{TcpAgent} agent is started in the example when its
FTP source receives the \code{start} directive at time 1.2.
The \code{start} operation is an instance procedure defined on the
\href{class Application/FTP}{Section}{sec:simapps}.
It is defined in \nsf{tcl/lib/ns-source.tcl} as follows:
\begin{program}
        Application/FTP instproc start \{\} \{
                [$self agent] send -1
        \}
\end{program}
In this case, \code{agent} refers to our simple TCP agent and
\code{send -1} is analogous to sending an arbitrarily large file.

The call to \code{send} eventually results in the simple TCP sender
generating packets.
The following function \code{output} performs this:
\begin{program}
        void TcpAgent::output(int seqno, int reason)
        \{
                Packet* p = allocpkt();
                hdr_tcp *tcph = (hdr_tcp*)p->access(off_tcp_);
                double now = Scheduler::instance().clock();
                tcph->seqno() = seqno;
                tcph->ts() = now;
                tcph->reason() = reason;
                Connector::send(p, 0);
                \ldots
                if (!(rtx_timer_.status() == TIMER_PENDING))
                        /* {\cf No timer pending.  Schedule one.} */
                        set_rtx_timer();
        \}
\end{program}
Here we see an illustration of the use of the \fcn[]{Agent::allocpkt} method.
This output routine first allocates a new packet
(with its common and IP headers already filled in), but then must fill
in the appropriate TCP-layer header fields.
To find the TCP header in a packet 
(\href{assuming it has been enabled}{Section}{sec:packethdrmgr})
the \code{off_tcp_} must be properly initialized,
as illustrated in the constructor.
The packet \fcn[]{access} method returns a pointer to the TCP header,
its sequence number and time stamp fields are filled in,
and the \fcn[]{send} method of the class Connector is called
to send the packet downstream one hop.
Note that the C++ \code{::} scoping operator is used here to avoid
calling \fcn[]{TcpSimpleAgent::send} (which is also defined).
The check for a pending timer uses the timer method \fcn[]{status} which
is defined in the base class TimerHandler.
It is used here to set a retransmission timer if one is not already set
(a TCP sender only sets one timer per window of packets on each connection).

\subsection{Processing Input at Receiver}
\label{sec:tcpsink}

Many of the TCP agents can be used with the
\clsref{TCPSink}{../ns-2/tcp-sink.h} as the peer.
This class defines the \fcn[]{recv} and \fcn[]{ack} methods as follows:
\begin{program}
        void TcpSink::recv(Packet* pkt, Handler*)
        \{
                hdr_tcp *th = (hdr_tcp*)pkt->access(off_tcp_);
                acker_->update(th->seqno());
                ack(pkt);