libxorp_overview.tex

xorp源码hg

%
% $XORP: xorp/docs/libxorp/libxorp_overview.tex,v 1.28 2007/03/15 00:43:13 pavlin Exp $
%

\documentclass[11pt]{article}

%\usepackage[dvips]{changebar}

\usepackage{subfigure}
\usepackage{fullpage}
\usepackage{setspace}
\usepackage{times}
\usepackage{latexsym}
\usepackage{epsfig}
\usepackage{graphicx}
\usepackage{xspace}
\usepackage{color}
\usepackage{amsmath}
\usepackage{rotating}
\usepackage{moreverb}
\usepackage{listings}
\usepackage{alltt}
\usepackage{stmaryrd}
%\usepackage[dvipdf]{graphics}
%\usepackage[dvips]{graphicx}
%\usepackage{xorp}

\definecolor{gray}{rgb}{0.5,0.5,0.5}
\newcommand{\etc}{\emph{etc.}\xspace}
\newcommand{\ie}{\emph{i.e.,}\xspace}
\newcommand{\eg}{\emph{e.g.,}\xspace}
%\newcommand{\comment}[1]{{\color{gray}[\textsf{#1}]}}
%\newcommand{\comment}[1]{}

% Changebar stuff
% \newenvironment{colorcode}{\color{blue}}{}
% \renewcommand{\cbstart}{\begin{colorcode}}
% \renewcommand{\cbend}{\end{colorcode}}

% \pagestyle{empty}

\begin{document}

\title{XORP Libxorp Library Overview \\
\vspace{1ex}
Version 1.4}
\author{ XORP Project					\\
	 International Computer Science Institute	\\
	 Berkeley, CA 94704, USA			\\
         {\it http://www.xorp.org/}			\\
	 {\it [e-mail]}
}
\date{March 20, 2007}

\maketitle


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Introduction}

The \emph{libxorp} library contains a set of classes for basic
XORP functionality such as IP addresses and subnets, timers, event
loops, etc. It is used by virtually every other XORP component, and
its main purpose is to simplify the implementation of those components.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Overview}

Currently, the libxorp library contains the following classes and
components (in alphabetical order):

\begin{itemize}

  \item \emph{asnum.hh: class AsNum}: A class for storing an AS number
  used by protocols such as BGP.

  \item \emph{asyncio.hh: class AsyncFileReader, class AsyncFileWriter}:
  Asynchronous file transfer classes.

  \item \emph{buffer.hh: class Buffer}:  A class for storing buffered
  data.

  \item \emph{buffered\_asyncio.hh: class BufferedAsyncReader}:
  Buffered asynchronous file reader class.

  \item \emph{c\_format.hh: c\_format()}: A macro that creates a C++
  string from a C-style printf(3)-formatted string.

  \item \emph{callback.hh, callback\_debug.hh, callback\_nodebug.hh,
  safe\_callback\_obj.hh}:
  Callback mechanism.

  \item \emph{clock.hh: class SystemClock}: A class for providing the
  interface to obtain the system clock.

  \item \emph{config\_param.hh: template class ConfigParam}: A class for
  storing a configuration parameter.

  \item \emph{debug.h}: Provides facility for generating debug messages.

  \item \emph{ether\_compat.h}: Ethernet manipulation compatibility
  functions.

  \item \emph{eventloop.hh: class EventLoop}: Event loop class for
  coordinated operations between timers and I/O operations on file
  descriptors.

  \item \emph{exceptions.hh}: Standard XORP C++ exceptions.

  \item \emph{heap.hh: class Heap}: Provides Heap data structure.

  \item \emph{ioevents.hh}: Enumeration of various event types supported
  by the I/O callback facade.

  \item \emph{ipnet.hh, ipv4net.hh, ipv6net.hh, ipvxnet.hh: class
  IPv4Net, class IPv6Net, class IPvXNet}: Implementation of classes for
  basic subnet addresses (for IPv4, IPv6 and dual IPv4/6 address family
  respectively).

  \item \emph{ipv4.hh, ipv6.hh, ipvx.hh: class
  IPv4, class IPv6, class IPvX}: Implementation of classes for
  basic IP addresses (for IPv4, IPv6 and dual IPv4/6 address family
  respectively).

  \item \emph{mac.hh: class Mac, class EtherMac}: Containers for
  MAC types.

  \item \emph{nexthop.hh}: Classes that contain routing next-hop
  information.

  \item \emph{popen.hh}: The interface for the local implementation
  of \emph{popen(2)} and \emph{pclose(2)}.

  \item \emph{profile.hh}: Implementation of a mechanism for event
  profiling.

  \item \emph{random.h}: Local implementation of random(3).

  \item \emph{range.hh: class U32Range, class IPv4Range, class
  IPv4Range}: A set of classes that implement linear ranges (\eg
  integers or addresses).

  \item \emph{ref\_ptr.hh: template class ref\_ptr}: Reference counted
  pointer class.

  \item \emph{ref\_trie.hh}: Implementation of a trie to support route
  lookups.  Based on trie.hh, but with reference-counted storage
  supporting delayed deletion.

  \item \emph{round\_robin.hh}: Round-robin queue implementation.

  \item \emph{run\_command.hh: class RunCommand}: A class for running an
  external command.

  \item \emph{safe\_callback\_obj.hh: class CallbackSafeObject}:
  Implementation of a base class for objects that are callback safe.

  \item \emph{selector.hh}: I/O multiplexing interface.

  \item \emph{service.hh}: Provides base for asynchronous service classes.

  \item \emph{status\_codes.h}: Process states status codes used by
  processes when reporting their operational status to the router
  manager.

  \item \emph{task.hh: class XorpTask}: Priority-based task implementation.

  \item \emph{time\_slice.hh: class TimeSlice}: A class for computing
  whether some processing is taking too long.

  \item \emph{timer.hh: class XorpTimer}: XORP timer facility.

  \item \emph{timespent.hh: class TimeSpent}: A class used for debugging
  purpose to find code that has taken too long to execute.

  \item \emph{timeval.hh: class TimeVal}: A class for storing time values
  (similar to \emph{struct timeval}).

  \item \emph{tlv.hh: class Tlv}: Facility for reading and writing TLV
  (Type-Lenght-Value) records.

  \item \emph{token.hh}: Token related definitions.

  \item \emph{transactions.hh}: Facility for transaction operations.

  \item \emph{trie.hh}: Implementation of a trie to support route
  lookups.

  \item \emph{utility.h}: Contains various mini-utilities
  (mostly compiler-related helpers).

  \item \emph{utils.hh}: Contains various utilities (\eg to delete a
  list or array of pointers and the objects pointed to).

  \item \emph{vif.hh: class Vif, class VifAddr}: Virtual interface and
  virtual interface address classes.

  \item \emph{win\_dispatcher.hh, win\_io.hh}: Windows-specific header
  files.

  \item \emph{xlog.h}: Provides facility for log messages generation.

  \item \emph{xorp.h}: The XORP main include file that should be included
  by all XORP C and C++ files.

  \item \emph{xorpfd.hh: class XorpFd}: Implementation of a wrapper
  class used to encapsulate a file descriptor.

\end{itemize}

Each of the components is described in
Section~\ref{sec:components_description}.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Components Description}
\label{sec:components_description}

This section contains a brief description of each of the components of
the \emph{libxorp} library. This description is for informative
purpose only. The source code for each component is the ultimate source
for programming reference, and implementation details.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{asnum.hh}

This file contains \emph{class AsNum}: a class for storing an AS number
used by protocols such as BGP.
This class can be used to store an AS number that can be either
16 or 32 bits.  Originally, the AS numbers were defined as 16-bit
unsigned numbers.  Later the ``extended'' AS numbers were introduced,
which are unsigned 32-bit numbers.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{asyncio.hh}
\label{asyncio.hh}

This file contains
asynchronous file transfer classes.  These utilize XORP EventLoop
and its SelectorList to read or write files asynchronously.  The
user creates an AsyncFile\{Reader,Writer\} and adds a buffer for
reading or writing with add\_buffer().  A callback provided with
each buffer is called every time I/O happens on the buffer.
Reading or writing only begins when start() is called, and normally
continues until there are no buffers left.

From the developer's point of view, the following classes are of
interest: \emph{class AsyncFileReader, class AsyncFileWriter}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{buffer.hh}

This file contains \emph{class Buffer}: a class for conveniently storing
and accessing buffered data.
Currently it has limited applicability.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{buffered\_asyncio.hh}

This file contains \emph{class BufferedAsyncReader}: a class for
buffered asynchronous file reading. Unlike the \emph{class AsyncFileReader}
(see Section~\ref{asyncio.hh}) which delivers data whenever it is available,
the \emph{class BufferedAsyncReader} buffers the data and delivers it
whenever its size has reached a predefined threshold.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{c\_format.hh}

This file contains \emph{c\_format()}: a macro that creates a C++ string
from a C-style printf(3)-formatted string.
It takes the same arguments as printf(3), but \%n is illegal and
will cause abort to be called.

In practice, \emph{c\_format()} is a nasty macro, but by doing this we can
check the compile time arguments are sane and the run time arguments.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{callback.hh, callback\_debug.hh, callback\_nodebug.hh,
 safe\_callback\_obj.hh}

These files contain an implementation of a callback mechanism.
XORP is an asynchronous programming environment and as a result there
are many places where callbacks are useful.  Callbacks are typically
invoked to signify the completion or advancement of an asynchronous
operation.

XORP provides a generic and flexible callback interface that utilizes
overloaded templatized functions for generating callbacks in
conjunction with many small templatized classes. Whilst this makes the
syntax a little unpleasant, it provides a great deal of flexibility.

XorpCallback objects are objects created by the callback()
function which returns a reference pointer to a newly created
callback object.  The callback is invoked by calling the dispatch()
method on that object.

There are two versions of the callback mechanism: debug and non-debug
version. The debug version includes additional information with
each callback (\eg file name and line number where the callback was invoked),
records callback tracing events, etc, but creates additional overhead
to the system. Non-debug callbacks are used by default; the debug
callbacks can be enabled by defining \emph{DEBUG\_CALLBACK}
before including \emph{callback.hh}, or by running
\emph{./configure --enable-callback-debug} before compiling XORP.

For more details on the callback mechanism, and for usage examples, see
the beginning of \emph{callback\_debug.hh} or \emph{callback\_nodebug.hh}.
Note that these files are auto-generated by \emph{callback-gen.py}
(a Python script), therefore they should never be edited.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{clock.hh}

This file contains the implementation of \emph{class SystemClock}
that provides the interface for obtaining the system clock.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{config\_param.hh}

This file contains the implementation of \emph{template class
ConfigParam}: a class for storing a configuration parameter.

This class can be used to store the value of a configuration parameter.
Such parameter has a current and a default value.
The \emph{ConfigParam} class has the facility to add a callback that is
invoked whenever the value of the configuration parameter is changed.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{debug.h}