libxorp_overview.tex

来自「BCAST Implementation for NS2」· TEX 代码 · 共 743 行 · 第 1/2 页

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\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{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 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{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{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{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
'|' characters.
The facilities in that file are to copy tokens, removing them from a
token line, etc.
Currently, this file is used only by the CLI, therefore in the future it
may be moved to the CLI itself.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{transactions.hh}

This file contains facility for transactions.  A transaction consists
of a sequence of transaction operations, each of which is a command.
The TransactionManager class provides a front-end for creating,
dispatching, and destroying transactions.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{trie.hh}

This file implements a trie to support route lookups.
The implementation is template-based. From deleloper's point
of view, templates Trie, TrieNode, TriePreOrderIterator,
and TriePostOrderIterator
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.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{utility.h}

This file contains various mini-utilities.  Those utilities are mostly
compiler-related helpers; \eg compile-time assertion, \emph{UNUSED(var)}
macro to suppress warnings about unused functions arguments, etc.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{utils.hh}

This file contains various helper utilities. Currently, the only two
utilities are template functions to delete a list or array
of pointers and the objects pointed to.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{vif.hh}

This file declares the following classes: \emph{class Vif, class
VifAddr}.

Class Vif holds information about a virtual interface.  A Vif may
represent a physical interface, or may represent more abstract
entities such as the Discard interface, or a VLAN on a physical
interface.
VifAddr holds information about an address of a virtual interface.
A virtual interface may have more than one VifAddr.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{xlog.h}

This file provides facility for log messages generation, similar to
syslog. The log messages may be output to multiple output streams
simultaneously. Below is a description of how to use the log utility.

\begin{itemize}

  \item The xlog utility assumes that \verb=XORP_MODULE_NAME= is defined
   (per module). To do so, you must have in your directory a file like
   ``foo\_module.h'', and inside it should contain something like:

\begin{verbatim}
#define XORP_MODULE_NAME "BGP"
\end{verbatim}

   This file then has to be included by each *.c and *.cc file,
   and MUST be the first of the included local files.

  \item Before using the xlog utility, a program MUST initialize it
   first (think of this as the xlog constructor):

\begin{verbatim}
int xlog_init(const char *process_name, const char *preamble_message);
\end{verbatim}

   Further, if a program tries to use xlog without initializing it
   first, the program will exit.

  \item To add output streams, you MUST use one of the following (or both):

\begin{verbatim}
int xlog_add_output(FILE* fp);
int xlog_add_default_output(void);
\end{verbatim}

  \item To change the verbosity of all xlog messages, use:

\begin{verbatim}
xlog_set_verbose(xlog_verbose_t verbose_level);
\end{verbatim}

   where ``verbose\_level'' is one of the following (\verb=XLOG_VERBOSE_MAX=
   excluded):

\begin{verbatim}
typedef enum {
    XLOG_VERBOSE_LOW = 0,       /* 0 */
    XLOG_VERBOSE_MEDIUM,        /* 1 */
    XLOG_VERBOSE_HIGH,          /* 2 */
    XLOG_VERBOSE_MAX
} xlog_verbose_t;
\end{verbatim}

   Default value is \verb=XLOG_VERBOSE_LOW= (least details).
   Larger value for ``verbose\_level'' adds more details to the
   preamble message (e.g., file name, line number, etc, about the place
   where the log message was initiated).

   Note that the verbosity level of message type \verb=XLOG_LEVEL_FATAL= (see
   below) cannot be changed and is always set to the most verbose level
   (\verb=XLOG_VERBOSE_HIGH=).

  \item To change the verbosity of a particular message type, use:

\begin{verbatim}
void xlog_level_set_verbose(xlog_level_t log_level,
	xlog_verbose_t verbose_level);
\end{verbatim}

where ``log\_level'' is one of the following (\verb=XLOG_LEVEL_MAX=
excluded):

\begin{verbatim}
typedef enum {
    XLOG_LEVEL_FATAL = 0,       /* 0 */
    XLOG_LEVEL_ERROR,           /* 1 */
    XLOG_LEVEL_WARNING,         /* 2 */
    XLOG_LEVEL_INFO,            /* 3 */
    XLOG_LEVEL_TRACE,           /* 4 */
    XLOG_LEVEL_MAX
} xlog_level_t;
\end{verbatim}

   Note that the verbosity level of message type \verb=XLOG_LEVEL_FATAL=
   cannot be changed and is always set to the most verbose level
   (\verb=XLOG_VERBOSE_HIGH=).

  \item To start the xlog utility, you MUST use:

\begin{verbatim}
int xlog_start(void);
\end{verbatim}


  \item To enable or disable a particular message type, use:

\begin{verbatim}
int xlog_enable(xlog_level_t log_level);
int xlog_disable(xlog_level_t log_level);
\end{verbatim}

	By default, all levels are enabled.
	Note that \verb=XLOG_LEVEL_FATAL= cannot be disabled.

  \item To stop the logging, use:

\begin{verbatim}
int xlog_stop(void);
\end{verbatim}

	Later you can restart it again by \verb=xlog_start()=

  \item To gracefully exit the xlog utility, use

\begin{verbatim}
int     xlog_exit(void);
\end{verbatim}

	(think of this as the xlog destructor).
	An example:

\begin{verbatim}
int
main(int argc, char *argv[])
{
    //
    // Initialize and start xlog
    //
    xlog_init(argv[0], NULL);
    xlog_set_verbose(XLOG_VERBOSE_LOW);	// Least verbose messages
    // Increase verbosity of the error messages
    xlog_level_set_verbose(XLOG_LEVEL_ERROR, XLOG_VERBOSE_HIGH);
    xlog_add_default_output();
    xlog_start();

    // Do something

    //
    // Gracefully stop and exit xlog
    //
    xlog_stop();
    xlog_exit();

    exit (0);
}
\end{verbatim}

\end{itemize}


Typically, a developer would use the macros described below
to print a message, add an assert statement, place a marker, etc.
If a macro accepts a message to print, the format of the message is same
as printf(3). The only difference is that the xlog utility automatically
adds \verb='\n'=, (i.e. end-of-line) at the end of each string
specified by \verb=format=:

\begin{itemize}

  \item \verb=XLOG_FATAL(const char *format, ...)=
  \newline
  Write a FATAL message to the xlog output streams and abort the program.

  \item \verb=XLOG_ERROR(const char *format, ...)=
  \newline
  Write an ERROR message to the xlog output streams.

  \item \verb=XLOG_WARNING(const char *format, ...)=
  \newline
  Write a WARNING message to the xlog output streams.

  \item \verb=XLOG_INFO(const char *format, ...)=
  \newline
  Write an INFO message to the xlog output streams.

  \item \verb=XLOG_TRACE(int cond_boolean, const char *format, ...)=
  \newline
  Write a TRACE message to the xlog output stream, but only
  if \verb=cond_boolean= is not 0.

  \item \verb=XLOG_ASSERT(assertion)=
  \newline
  The XORP replacement for assert(3), except that it cannot be
  conditionally disabled and logs error messages through the standard
  xlog mechanism. It calls \verb=XLOG_FATAL()= if the assertion fails.

  \item \verb=XLOG_UNREACHABLE()=
  \newline
   A marker that can be used to indicate code that should never be executed.

  \item \verb=XLOG_UNFINISHED()=
  \newline
  A marker that can be used to indicate code that is not yet implemented
  and hence should not be run.

\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{xorp.h}

This is the XORP main include file that should be included by all XORP
C and C++ files. This file itself includes a number of frequently used system
header files, defines several commonly used values, etc.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%     APPENDIX
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\appendix
\section{Modification History}

\begin{itemize}

  \item December 11, 2002: Version 0.1 completed.

  \item March 10, 2003: Updated to match XORP version 0.2 release code;
  add information about RefTrie; cleanup.

  \item June 9, 2003: Updated to match XORP version 0.3 release code.

  \item August 28, 2003: Updated to match XORP version 0.4 release
  code.

  \item November 6, 2003: Updated to match XORP version 0.5 release code.

\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%     BIBLIOGRAPHY
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\bibliography{../tex/xorp}
\bibliographystyle{plain}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\end{document}