commoncpp2.texi

贡献一份commoncpp2,有兴趣的可以研究一下

@node Daemons
@section Daemons
@cindex Daemons

@findex pdetach
@cindex slog
Daemon support consists of two GNU Common C++ features.  The first is
the "pdetach" function.  This function provides a simple and portable
means to fork/detach a process into a daemon.  In addition, the "slog"
object is provided.

@tindex Slog
@cindex slog
@cindex clog
@findex Slog::operator<<
"slog" is an object which behaves very similar to the Standard C++
"clog".  The key difference is that the "slog" object sends it's
output to the system logging daemon (typically syslogd) rather than
through stderr.  "slog" can be streamed with the << operator just like
"clog".  "slog" can also accept arguments to specify logging severity
level, etc.


@c -----------------------------------------------------------------------
@node Persistence
@section Persistence
@cindex Persistence

The GNU Common C++ Persistence library was designed with one thought
foremost - namely that large interlinked structures should be easily
serializable. The current implementation is @emph{not} endian safe,
and so, whilst it should in theory be placed in the "Extras" section,
the codebase itself is considered stable enough to be part of the main
distribution.

@tindex Persistence::BaseObject
@findex IMPLEMENT_PERSISTENCE
@findex DECLARE_PERSISTENCE
The Persistence library classes are designed to provide a quick and
easy way to make your data structures serializable. The only way of
doing this safely is to inherit your classes from the provided class
Persistence::BaseObject. The macros "IMPLEMENT_PERSISTENCE" and
"DECLARE_PERSISTENCE" provide all the function prototypes and
implementation details you may require to get your code off the
ground.


@c -----------------------------------------------------------------------
@node Configuration and Misc.
@section Configuration and Misc.
@cindex Configuration and Misc.

@tindex MemPager
There are a number of odd and specialized utility classes found in
Common C++.  The most common of these is the "MemPager" class.  This
is basically a class to enable page-grouped "cumulative" memory
allocation; all accumulated allocations are dropped during the
destructor.  This class has found it's way in a lot of other utility
classes in GNU Common C++.

@tindex Keydata
The most useful of the misc. classes is the Keydata class.  This class
is used to load and then hold "keyword = value" pairs parsed from a
text based "config" file that has been divided into "[sections]".
Keydata can also load a table of "initialization" values for keyword
pairs that were not found in the external file.

One typically derives an application specific keydata class to load a
specific portion of a known config file and initialize it's values.
One can then declare a global instance of these objects and have
configuration data initialized automatically as the executable is
loaded.

Hence, if I have a "[paths]" section in a "/etc/server.conf" file, I
might define something like:

@example
@cartouche
class KeyPaths : public Keydata
@{
public:
        KeyPaths() : Keydata("/server/paths")
        @{
                static KEYDEF *defvalues = @{
                @{"datafiles", "/var/server"@},
                @{NULL, NULL@}@};

                // @r{override with [paths] from "~/.serverrc" if avail.}

                Load("~server/paths");
                Load(defvalues);
        @}
@};

KeyPaths keypaths;
@end cartouche
@end example


@c -----------------------------------------------------------------------
@node Numbers and Dates
@section Numbers and Dates
@cindex Numbers and Dates

@tindex Number
@tindex ZNumber
@tindex Date
@tindex DateNumber
@emph{TODO.} This section will explain the number manipulation classes
(@code{Number} and @code{ZNumber}, as well as the data related classes
(@code{Date} and @code{DateNumber}).


@c -----------------------------------------------------------------------
@node URL Streams
@section URL Streams
@cindex URL Streams

@tindex URLStream
@cindex URL related functions
@emph{TODO.} This section will explain the URLStream class, as well as
the following URL related functions:

@ftable @code
@item URLStream

@item urlDecode

@item urlEncode

@item b64Decode

@item b64Encode

@end ftable

In the meantime you can have a look at the @file{urlfetch.cpp} demo,
which is a good example of use of URLStream to retrieve documents from
URLs.


@c -----------------------------------------------------------------------
@node XML Streams and RPC
@section XML Streams and RPC
@cindex XML Streams and RPC

@tindex XMLStream
@tindex XMLRPC
@emph{TODO.} This section will explain the XML streams parsing
(@code{XMLStream} class) and XML RPC (@code{XMLRPC} class) facilities
of Common C++. In the meantime, you can have a look at the
@file{xmlfetch.cpp} demo, which defines a basic XML parser for URL
streams.


@c -----------------------------------------------------------------------
@node Exceptions
@section Exceptions
@cindex Exceptions

@tindex Exception
@tindex std::exception
@emph{TODO.} This section will explain the exception model of Common
C++, based on the @code{Exception} class, derived from std::exception.

@tindex Exception
@tindex IOException
@tindex SockException
@tindex DirException
@tindex DSOException
@tindex FIFOException
@tindex PipeException
@tindex FileException
@tindex FTPException
@tindex SerException
@tindex ThrException
@tindex PersistException
Other exception classes that will be commented are:
@code{IOException}, @code{SockException}, @code{DirException},
@code{DSOException}, @code{FIFOException}, @code{PipeException},
@code{FileException}, @code{FTPException}, @code{SerException},
@code{ThrException} and @code{PersistException}. In the meantime you
can have a look at the exception class hierarchy on the reference
manual.


@c -----------------------------------------------------------------------
@node Templates
@section Templates
@cindex Templates

@tindex objCounter
@tindex objList
@tindex objMap
@tindex keyMap]
@tindex objSync
@tindex cstring
@tindex cistring
@tindex Pointer
@tindex Counter
@findex abs
@emph{TODO.} This section will explain the template subsistem of
Common C++.



@c -----------------------------------------------------------------------
@node Extras
@chapter Extras
@cindex Extras

@emph{TODO: this is rather outdated.}

At the time of the release of GNU Common C++ 1.0, it was deemed that
several class libraries either were incomplete or still experimental,
and the 1.0 designation seemed very inappropriate for these libraries.
I also wanted to have a mechanism to later add new GNU Common C++
class libraries without having to disrupt or add experimental code
into the main GNU Common C++ release.

To resolve this issue, a second package has been created, and is named
GNU "GNU Common C++ Extras".  The extras package simply holds class
frameworks that are still not considered "mature" or "recommended".
This package can be downloaded, compiled, and installed, after GNU
Common C++ itself.  Many of the class libraries appearing in the
extras package are likely to appear in GNU Common C++ proper at some
future date, and should be considered usable in their current form.
They are made available both to support continued development of GNU
Common C++ proper and because, while not yet mature, they are
considered "useful" in some manner.

The initial GNU Common C++ "extras" package consisted of two
libraries; Common C++ "scripting" and "math".  The scripting library
(-lccscript) is the GNU Bayonne scripting engine which is used as a
near-realtime event driven embedded scripting engine for "callback"
driven state-event server applications.  The Bayonne scripting engine
directly uses C++ inheritance to extend the Bayonne dialect for
application specific features and is used as a core technology in the
GNU Bayonne, DBS, and Meridian telephony servers and as part of the a
free home automation project.  There has been some discussion about
folding the GNU Bayonne scripting concepts around a more conventional
scripting language, and so this package currently remains in "extras"
rather than part of GNU Common C++ itself.

The other package found in the initial "extras" distribution is the
Common C++ math libraries.  These are still at a VERY early stage of
development, and may well be depreciated if another suitable free C++
math/numerical analysis package comes along.


@c -----------------------------------------------------------------------
@node Serverlets
@chapter Serverlets
@cindex Serverlets

Serverlets are a concept popularized with Java and web servers.  There
is a broad abstract architectural concept of serverlets or plugins
that one also finds in my GNU Common C++ projects, though they are not
directly defined as part of GNU Common C++ itself.

A GNU Common C++ "serverlet" comes about in a Common C++ server
project, such as the Bayonne telephony server, where one wishes to
define functionality for alternate hardware or API's in alternated
shared object files that are selected at runtime, or to add "plugins"
to enhance functionality.  A serverlet is defined in this sense as a
"DSO" loaded "-module" object file which is linked at runtime against
a server process that exports it's base classes using
"-export-dynamic".  The "server" image then acts as a carrier for the
runtime module's base functionality.

Modules, or "serverlets", defined in this way do not need to be
compiled with position independent code.  The module is only used with
a specific server image and so the runtime address is only resolved
once rather than at different load addresses for different arbitrary
processes.

I recommend that GNU Common C++ based "servers" which publish and
export base classes in this manner for plugins should also have a
server specific "include" file which can be installed in the cc++
include directory.


@c -----------------------------------------------------------------------
@node Compiler Options
@chapter Compiler Options
@cindex Compiler Options

@cindex automake
@cindex autoconf
@cindex configuration
@cindex config.h
@cindex ccgnu2-config
GNU Common C++ does a few things special with automake and autoconf.
When the Common C++ library is built, it saves a number of compiler
options that can be retrieved by an application being configured to
use GNU Common C++. These options can be retrieved from the standard
output of the @command{ccgnu2-config} script, which is installed in the
machine binaries path.

This is done to assure the same compiler options are used to build
your application that were in effect when GNU Common C++ itself was
built.  Since linkage information is also saved in this manner, this
means your application's "configure" script does not have to go
through the entire process of testing for libraries or GNU Common C++
related compiler options all over again.  Finally, GNU Common C++
saves it's own generated @file{config.h} file in
@file{cc++/config.h}@footnote{On Win32 systems, a specific
@file{config.h} located under the win32/cc++/ directory is used and
installed.}.

@command{ccgnu2-config} has the following options (which are shown if
you type @command{ccgnu2-config --help}):

@example
Usage: ccgnu2-config [OPTIONS]
Options:
        [--prefix]
        [--version]
        [--flags]
        [--libs]
        [--gnulibs]
        [--iolibs]
        [--extlibs]
        [--stdlibs]
        [--includes]
@end example

For a basic usage of Common C++, you just need the options given by
the following command: @command{ccgnu2-config --flags --stdlibs},
whose output should be something like this:

@example
foo@@bar:~/$ ccgnu2-config --flags --stdlibs
-I/usr/local/include/cc++2 -I/usr/local/include -D_GNU_SOURCE
-L/usr/local/lib -lccext2 -lccgnu2 -lxml2 -lz -ldl -pthread
@end example

Note that this is just an example, the concrete output on your system
will probably differ.  The first output line (corresponding to
@code{--flags}) tells what directories must be added to the compiler
include path, as well as global symbol definitions
(@code{_GNU_SOURCE}) needed to compile with Common C++. The second
output line (corresponding to @code{--stdlibs}) gives the linker
options, both additional library path and libraries that must be
linked. @code{ccgnu2} and @code{ccext2} are the two libraries Common
C++ currently consists of. The other libraries shown in the example
are dependencies of Common C++.

The list shown below tells what information is given by each of the
options that can be specified to @command{ccgnu2-config}. It also
specifies what would be the output corresponding to the example given
before.

@table @code