libxorp_overview.tex

xorp源码hg

This file provides facility for debug messages generation.
More specifically, it defines the \verb=debug_msg()=, the macro
responsible for generating debug messages.
It takes the same arguments as printf(3). For example:

\begin{verbatim}
debug_msg("The number is %d\n", 5);
\end{verbatim}

For more details see the comments inside that file.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{ether\_compat.h}

This file contains Ethernet-related manipulation compatibility
functions. For example, it includes the appropriate system files,
and declares functions \verb=ether_aton()= and \verb=ether_ntoa()=
(implemented locally in \emph{ether\_compat.c}) if the system is missing
the corresponding \verb=ether_aton(3)= and \verb=ether_ntoa(3)=.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{eventloop.hh}

This file defines \emph{class EventLoop}.
It is used to co-ordinate interactions between a TimerList and a
SelectorList for XORP processes.  All XorpTimer and select operations
should be co-ordinated through this interface.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{exceptions.hh}

This file contains \emph{class XorpException}: a base class for XORP C++
exceptions. It contains also all standard XORP C++ exceptions.
An example of such exception is \emph{class InvalidFamily} which is
thrown if the address family is invalid (for example, by an IPvX
constructor when invoked with an invalid address family).

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{heap.hh}

This file contains \emph{class Heap}.  The Heap class is used by the
TimerList class as it's priority queue for timers. This implementation
supports removal of arbitrary objects from the heap, even if they are
not located at the top.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{ioevents.hh}

This file contains the enumerated \emph{IoEventType} codes: various
event types supported by the I/O callback facade. The event types are
used by clients when registering interest in I/O events.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{ipnet.hh, ipv4net.hh, ipv6net.hh, ipvxnet.hh}

These files contain the declaration of the following classes:
\emph{class IPv4Net, class IPv6Net, class IPvXNet}, which are
classes for basic subnet addresses (for IPv4, IPv6 and dual IPv4/6
address family respectively). IPvXNet can be used to store a subnet
address that has either IPv4 or IPv6 address family.

Most of the implementation is contained in file \emph{ipnet.hh}, which
contains a \emph{template class IPNet}. The IPv4Net, IPv6Net, and
IPvXNet classes are derived from that template.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{ipv4.hh, ipv6.hh, ipvx.hh}

These files contain the declaration for the following classes:
\emph{class IPv4, class IPv6, class IPvX}, which are
classes for basic IP addresses (for IPv4, IPv6 and dual IPv4/6
address family respectively). IPvX can be used to store an
address that has either IPv4 or IPv6 address family.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{mac.hh}

This file declares the following classes: \emph{class Mac, class
EtherMac}. The first class is a generic container for any type of MAC.
The second class is a container for Ethernet MAC address.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{nexthop.hh}

This file declares a number of classes that can be used to contain
routing next-hop information. For example, \emph{class NextHop}
is the generic class for holding information about routing
next hops.  NextHops can be of many types, including immediate
neighbors, remote routers (with IBGP), discard interfaces,
encapsulation endpoints, etc.  NextHop itself doesn't really do
anything useful, except to provide a generic handle for the
specialized subclasses. The specialized subclasses are:

\begin{itemize}

  \item IPPeerNextHop is for next hops that are local peers.

  \item IPEncapsNextHop is for ``next hops'' that are non-local, and require
  encapsulation to reach. An example is the PIM Register Encapsulation.

  \item IPExternalNextHop An IP nexthop that is not an intermediate
  neighbor.

  \item DiscardNextHop is a discard interface.

\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{popen.hh}

This file contains the interface for the local implementation
of \emph{popen(2)} and \emph{pclose(2)}.
The corresponding local names are \emph{popen2()} and \emph{pclose2()}
respectively. Unlike the system's \emph{popen(2)}, the local
\emph{popen2()} implementation allows the user to specify the streams
where the \emph{stdout} and \emph{stderr} of the command will be
redirected to.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{profile.hh}

This file implements the mechanism for event profiling.
The developer can add profiling entries at various places of the program.
Each profiling entry has a name and it can be enabled or disabled.
In addition, a number of strings can be added to each profiling entry,
and those strings can be read at some later stage.

% TODO: add an example of using the profiling mechanism.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{random.hh}

This file declares the API for the local implementation of random(3).
Currently it is used if the underlying system doesn't have random(3).

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{range.hh}

This file implements the following classes:
\emph{class U32Range, class IPv4Range, class IPv4Range}.

Those classes implement linear ranges X..Y (\eg for integers or
addresses). A linear range is defined by its low and high inclusive
boundaries. It is the user's responisibility to ensure that the
condition (low $\leq$ high) always holds.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{ref\_ptr.hh}

This file declares \emph{template class ref\_ptr}: reference counted
pointer class.

The ref\_ptr class is a strong reference class.  It maintains a count of
how many references to an object exist and releases the memory associated
with the object when the reference count reaches zero.  The reference
pointer can be dereferenced like an ordinary pointer to call methods
on the reference counted object.

At the time of writing the only supported memory management is
through the new and delete operators.  At a future date, this class
should support the STL allocator classes or an equivalent to
provide greater flexibility.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{ref\_trie.hh}

This file implements a trie to support route lookups.  The
implementation is template-based, and is based on the code in
trie.hh. From deleloper's point of view, templates RefTrie, RefTrieNode,
RefTriePreOrderIterator, and RefTriePostOrderIterator are the most important.
Those templates should be invoked
with two classes, the basetype ``A'' for the search Key (which is a
subnet, \verb=IPNet<A>=), and the Payload.

RefTrie differs from Trie (and its associated classes) in that the
RefTrieNode includes a reference count of how many RefTrieIterators
are pointing at it.  If a RefTrieNode is deleted, but has a non-zero
reference count, deletion will be delayed until the reference count
becomes zero.  In this way, additions and deletions to the RefTrie
cannot cause a RefTriePreOrderIterator or RefTriePostOrderIterator
to reference invalid memory, although a deletion and subsequent addition can
cause the payload data referenced by an iterator to change.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{round\_robin.hh}

This file implements round-robin queue which is used by the
priority-based task implementation (see Section~\ref{sec:task_hh}).
It is used internally by libxorp and shouldn't be used by the rest of
the system.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{run\_command.hh}

This file implements \emph{class RunCommand} which provides the
mechanism for running an external command. In addition to the command
name and its arguments, the developer can specify three callbacks:

\begin{itemize}

  \item \emph{stdout\_cb}: the callback to call when there is data on
  the standard output.

  \item \emph{stderr\_cb}: the callback to call when there is data on
  the standard error.

  \item \emph{done\_cb}: the callback to call when the command is completed.

\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{safe\_callback\_obj.hh}

This file declares class \emph{CallbackSafeObject}.
Objects that wish to be callback safe should be derived from this
class. When a CallbackSafeObject is destructed it informs all the callbacks
that refer to it that this is the case and invalidates (sets to null)
the object they point to.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{selector.hh}

This file contains the I/O multiplexing interface. The particular class
of interest is \emph{class SelectorList}.

A SelectorList provides an entity where callbacks for pending I/O
operations on file descriptors may be registered.  The callbacks
are invoked when one of the select methods is called and I/O
is pending on the particular descriptors.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{service.hh}

This file declares \emph{class ServiceBase}.  A service is a class that
can be started and stopped and would typically involve some asynchronous
processing to transition between states.  The base class provides a
state model and methods for transitioning between states.  Mandatory
transition methods, like start and stop, are abstract in the base
class.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{status\_codes.h}

This file contains the enumerated \emph{ProcessStatus} codes
that a XORP process should report to the XORP router manager
(\emph{rtrmgr})~\cite{xorp:rtrmgr}.
The file itself contains a detailed explanation of the process states
(valid transaction between states, triggering events, actions, etc).

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{task.hh}
\label{sec:task_hh}

This file declares and implements class \emph{class XorpTask}.
Class \emph{XorpTask} is used for priority-based tasks.
Each task can have a priority between \emph{PRIORITY\_HIGHEST} and
\emph{PRIORITY\_LOWEST}. A number of suggested priorities and weights
are declared inside that class:

\begin{verbatim}
class XorpTask {
public:
    ...

    //
    // Task/Timer priorities. Those are suggested values.
    //
    static const int PRIORITY_HIGHEST		= 0;
    static const int PRIORITY_XRL_KEEPALIVE	= 1;
    static const int PRIORITY_HIGH		= 2;
    static const int PRIORITY_DEFAULT		= 4;
    static const int PRIORITY_BACKGROUND	= 7;
    static const int PRIORITY_LOWEST		= 9;
    static const int PRIORITY_INFINITY		= 255;

    //
    // Task/Timer weights. Those are suggested values.
    //
    static const int WEIGHT_DEFAULT		= 1;

    ...
};

\end{verbatim}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{time\_slice.hh}

This file declares \emph{class TimeSlice}.
This class can be used to compute whether some processing is taking
too long time to complete. It is up to the program that uses
TimeSlice to check whether the processing is taking too long,
and suspend processing of that task if necessary.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{timer.hh}

This file declares the XORP timer facility. The only class of interest
from a developer's point of view is \emph{class XorpTimer}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{timespent.hh}

This files declares and implements \emph{class TimeSpent}.
This class used for debugging purpose to find code that has taken too long to
execute.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{timeval.hh}

This file contains implementation of \emph{class TimeVal} for
storing time values (similar to \emph{struct timeval}).
\emph{TimeVal} implements the appropriate constructors and numerous
helper methods (\eg Less-Than and Addition operators, etc).

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{tlv.hh}

This file contains the implementation of \emph{class Tlv} for reading
and writing TLV (Type-Lenght-Value) records from/to a file. The records
are stored in network byte order format.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{token.hh}

This file contains various token-related definitions. Token is a
sequence of symbols separated from other tokens by some pre-defined
symbols. In this implementation, the separators are the is\_space(3) and