libxorp_overview.tex

xorp源码hg

'|' 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{win\_dispatcher.hh, win\_io.hh}

Those are Windows-specific header files which are used internally by
libxorp and shouldn't be used by the rest of the system.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\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_MIN=
  and \verb=XLOG_LEVEL_MAX= excluded):

\begin{verbatim}
typedef enum {
    XLOG_LEVEL_MIN = 0,         /* 0 */
    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).

\end{itemize}

Below is an example of using the XLOG facility:

\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}


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.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{xorpfd.hh}

This file contains the implementation of \emph{class XorpFd} used to
encapsulate a file descriptor.

It exists because of fundamental differences between UNIX and Windows
in terms of how the two families of operating systems deal with file
descriptors; in most flavours of UNIX, all file descriptors are
created equal, and may be represented using an 'int' type which is
usually 32 bits wide. In Windows, sockets are of type SOCKET, which
is a typedef alias of u\_int; whereas all other system objects are
of type HANDLE, which in turn is a typedef alias of 'void *'.


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

\begin{itemize}

  \item December 11, 2002: Initial version 0.1 completed.

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

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

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

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

  \item July 8, 2004: Updated to match XORP release 1.0.

  \item April 13, 2005: Updated to match XORP release 1.1:
  added information for \emph{buffered\_asyncio.hh}, \emph{clock.hh},
  \emph{popen.hh}, \emph{profile.hh} and \emph{run\_command.hh}.

  \item March 8, 2006: Updated to match XORP release 1.2:
  added information for \emph{range.hh}, \emph{tlv.hh} and
  \emph{xorpfd.hh}.

  \item August 2, 2006: Updated the version to 1.3, and the date.

  \item March 20, 2007: Updated to match XORP release 1.4:
  added information for \emph{ioevents.hh}, \emph{random.h},
  \emph{round\_robin.hh}, \emph{task.hh}, \emph{win\_dispatcher.hh}
  and \emph{win\_io.hh}.

\end{itemize}

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

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