commoncpp2.texi

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

\input texinfo    @c -*-texinfo-*-
@c %** start of header
@setfilename commoncpp2.info
@settitle GNU Common C++ 2
@afourpaper
@setchapternewpage odd
@documentlanguage en
@documentencoding ISO-8859-1
@c %** end of header

@set EDITION 1.0pre0
@set VERSION 1.0
@set UPDATED September 2002

@dircategory Development
@direntry
* GNU Common C++ 2: (commoncpp2).     GNU Common C++ 2 Framework Documentation.
@end direntry

@c -----------------------------------------------------------------------

@c %** start of summary description and copyright
@ifnottex
GNU Common C++ 2 is the second major release of a C++ framework
offering portable support for threading, sockets, file access,
daemons, persistence, serial I/O, XML parsing, and system services,
initially started by David Sugar and Daniel Silverstone.

Copyright @copyright{} 1999, 2000, 2001, 2002 Open Source Telecom Corporation.
@include fdlnotice.texi
@end ifnottex
@c %** end of summary description and copyright

@c -----------------------------------------------------------------------

@c %** start of title and copyright page
@shorttitlepage @titlefont{GNU Common C++ 2}
@titlepage
@sp 10
@title GNU Common C++ 2
@subtitle 
@subtitle @value{EDITION}th Edition, covering GNU Common C++ version @value{VERSION}
@subtitle @value{UPDATED}
@author David Sugar wrote this document.
@author Federico Montesino Pouzols updated and formatted it in @TeX{}Info

@page
@vskip 0pt plus 1filll
@center{Copyright @copyright{} 1999, 2000, 2001, 2002 Open Source Telecom Corporation}
@include fdlnotice.texi
@page
@end titlepage
@c %** end of title and copyright page

@c -----------------------------------------------------------------------

@c %** start of top node and master menu
@ifnottex
@node Top
@top
This document describes GNU Common C++ 2, the second major release of
a C++ framework offering portable support for threading, sockets, file
access, daemons, persistence, serial I/O, XML parsing, and system
services, initially started by David Sugar and Daniel Silverstone.

This is the edition @value{EDITION} of this manual and documents
GNU Common C++ 2 version @value{VERSION}.
@end ifnottex

@contents

@menu
* Introduction::                  What GNU Common C++ and this manual are.
* Distribution::                  How to get GNU Common C++.
* Framework Description::         GNU Common C++ classes.
* Extras::                        GNU Common C++ extras.
* Serverlets::                    GNU Common C++ serverlets.
* Compiler Options::              Compiler options to use with GNU Common C++.
* Automake Services::             GNU Common C++ automake services.
* Configuring Sources::           Configuring GNU Common C++ sources.
* Developer Documentation::       Information of interest for CC++ developers.
* Licenses::                      Library and documentation licenses.
* Class and Data Type Index::     Index of Common C++ classes and data types.
* Method and Function Index::     Index of Common C++ methods and functions.
* Concept Index::                 Index of concepts.
@end menu
@c %** end of top node and master menu

@c -----------------------------------------------------------------------

@c %** start of body
@node Introduction
@comment  node-name,  next,  previous,  up
@chapter Introduction
@cindex Introduction

@quotation
@strong{PLEASE NOTE;} This is a preliminary version of this
document. Some information may not be complete or even somewhat
obsolete; bug reports, suggestions and contributions are welcome.
@end quotation

@cindex reference manual
In writing this document I hope to better explain what the GNU Common
C++ library is about and how it may be used in developing your own C++
applications.  This document is intended as an overview and unifying
document to support the already detailed class-by-class function
descriptions found and browsable in the "doc" subdirectory of the
Common C++ distribution.

GNU Common C++ offers a set of "portable" classes that can be used to 
build highly portable applications in C++.  In particular, Common C++ 
offers classes that abstract threading, sockets, synchronization, serial 
I/O, "config" file parsing, class object persistence, shared object module
loading, daemon management, and optimized "block" and memory mapped file
I/O under a set of consistent classes that your application can then
be built from.  The goal is to write your application to use the portable
abstract services and classes of the GNU Common C++ libraries rather than
having to access low level system services directly.

There is a large diversity of views in how one should code a C++
framework.  Since a large number of older C++ compilers remain in
everyday use, I choose to use what I felt was an appropriate set of
C++ language features and practices to provide the greatest compiler
compatibility and to generate the most optimized code for GNU Common
C++.  To further reduce the overhead of writing GNU Common C++
applications, I have split the primary library image itself into
several different shared libraries.  This allowed me to collect the
more obscure and less likely to be used features into separate
libraries which need never be loaded.

Finally, in designing GNU Common C++, I assume that class extension
(inheritance) is the primary vehicle for application development. The 
GNU Common C++ framework, while offering many classes that are usable
directly, is designed for one to create applications by extending Common
C++ "base" classes into an application specific versions of said classes
as needed. 


@c -----------------------------------------------------------------------
@node Distribution
@chapter Distribution
@cindex distribution

@cindex free software
@cindex GNU GPL
@cindex linking exception
@cindex GNU FDL
@cindex philosophy
This manual is licensed under the terms of the @acronym{GNU} Free
Documentation License, @xref{GNU Free Documentation License}.

@acronym{GNU} Common C++ is free software (see
@url{http://www.gnu.org/philosophy/philosophy.html}). There are
several ways to get @acronym{GNU} Common C++, refer to
@url{http://www.gnu.org} and
@url{http://www.gnu.org/software/commoncpp/}.

The @acronym{GNU} Common C++ framework is licensed under the terms of
the @acronym{GNU} General Public License, @xref{GNU General Public
License}, plus a linking exception, @xref{GNU Common C++ Linking
Exception}, that grants additional privileges. These privileges are
similar to the terms Guile is licensed under and constitute privileges
similar to the LGPL. David Sugar explains why these licensing terms
were chosen for Common C++ as follows:

The one problem I recall immediately with the LGPL as it applies to
C++ class frameworks is the way it defines and refers to ``linking''
vs ``derived works''.  In concept, a C++ header with inline members or
template is not ``linked'' in the same sense as one might presume the
meaning in traditional C library, and what does one make of a class
who's base class is defined in a header in a LGPL protected library?
Is creating a derived C++ class purely a linking operation or creating
a derived/composite work?

At the time it seemed simpler to take the language of the GPL and
provide an appropriate privileges to allow Common C++ to be used in
ways that achieve the same goals of the LGPL, but without using the
same choice of language for this that is found in the LGPL.  We
actually looked at the Guile license, which also faced many of these
questions, and choose to use their methodology for creating a special
privilege in this regard.  Of course, this was a number of years ago,
and the language of the LGPL (and GPL) has evolved over time to better
address the needs of object oriented frameworks.  If the language of
the current LGPL were close enough to resolving these goals, I think
we would likely switch to it, as that would resolve some confusion
over the exact license status.  I have found it simpler to explain it
as a LGPL-like license since we were trying for much the same effect
within the context of a C++ framework, and most people basically
understand what the LGPL is.


@c -----------------------------------------------------------------------
@node Framework Description
@chapter Framework Description
@cindex Framework Description

This chapter provides a description of the GNU Common C++ framework
main components.

@menu
* Overall Concepts::             Global GNU Common C++ Practices.
* Threading Concepts::           GNU Common C++ Threading Concepts.
* Synchronization::              GNU Common C++ Synchronization.
* Sockets::                      GNU Common C++ Sockets.
* Serial I/O::                   GNU Common C++ Serial I/O.
* Block I/O::                    GNU Common C++ Block I/O.
* Daemons::                      GNU Common C++ Daemon Support.
* Persistence::                  GNU Common C++ Persistence.
* Configuration and Misc.::      GNU Common C++ Configuration and Other Things.
* Numbers and Dates::            GNU Common C++ Numbers and Dates Manipulation.
* URL Streams::                  GNU Common C++ HTTP Support.
* XML Streams and RPC::          GNU Common C++ XML Streams and RPC.
* Exceptions::                   GNU Common C++ Exception Model.
* Templates::                    GNU Common C++ Template Subsystem
@end menu

@c -----------------------------------------------------------------------
@node Overall Concepts
@section Overall Concepts 
@cindex Overall Concepts

@cindex ost
@cindex ost namespace
@cindex namespace
Unless explicitly stated, all GNU Common C++ symbols are under the
@code{ost} namespace@footnote{Provided the C++ compiler used to
compile GNU Common C++ suupports namespaces, which is checked at
configuration time.}. Thus, when we refer to the Thread class, we
actually refer to ost::Thread.

The GNU Common C++ framework actually consists of two libraries:
@file{ccgnu2} and @file{ccext2}@footnote{@xref{Compiler Options}, for
how to specify compiling and linking options for these libraries. On
Win32 systems, these libraries are compiled as @file{ccgnu2.dll} and
@file{ccext2.dll}}. The first includes core functionality that other
things commonly depend on, such as threading and synchronization. That
way, if you are building a tight application with a small footprint,
you can have it used the ccgnu2 shared image alone. On the contrary,
things that require or induce new library link requirements are
included in @file{ccext2}.  Hence, for example, if you do not wish to
use XML parsing in your application, why create an unused library
dependency for libxml2?  The idea being that one can, if one needs to,
use only ``core'' features found in ccgnu2 and then create very
compact executables with very few additional library dependencies.


@c -----------------------------------------------------------------------
@node Threading Concepts
@section Threading Concepts 
@cindex Threading Concepts

@cindex threading
@cindex APE
@cindex Java threading
Threading was the first part of GNU Common C++ I wrote, back when it
was still the APE library.  My goal for GNU Common C++ threading has
been to make threading as natural and easy to use in C++ application
development as threading is in Java.  With this said, one does not
need to use threading at all to take advantage of GNU Common C++.
However, all GNU Common C++ classes are designed at least to be
thread-aware/thread-safe as appropriate and necessary.

@cindex pthread
@cindex ost_pthread.m4
@cindex autoconf
GNU Common C++ threading is currently built either from the Posix
"pthread" library or using the win32 SDK.  In that the Posix "pthread"
draft has gone through many revisions, and many system implementations
are only marginally compliant, and even then usually in different
ways, I wrote a large series of autoconf macros found in
ost_pthread.m4 which handle the task of identifying which pthread
features and capabilities your target platform supports.  In the
process I learned much about what autoconf can and cannot do for
you.

@cindex GNU pth
@cindex pth
Currently the GNU Portable Thread library (GNU pth) is not directly
supported in GNU Common C++.  While GNU "Pth" doesn't offer direct
native threading support or benefit from SMP hardware, many of the
design advantages of threading can be gained from it's use, and the
Pth pthread "emulation" library should be usable with GNU Common C++.
In the future, GNU Common C++ will directly support Pth, as well as
OS/2 and BeOS native threading API's.

@cindex threading model
GNU Common C++ itself defines a fairly "neutral" threading model that
is not tied to any specific API such as pthread, win32, etc.  This
neutral thread model is contained in a series of classes which handle
threading and synchronization and which may be used together to build
reliable threaded applications.

@tindex Thread
@findex Thread::run
@cindex execution context
@cindex termination
@cindex thread termination
GNU Common C++ defines application specific threads as objects which
are derived from the GNU Common C++ "Thread" base class.  At minimum
the "run" method must be implemented, and this method essentially is
the "thread", for it is executed within the execution context of the
thread, and when the run method terminates the thread is assumed to
have terminated.

@cindex priority
@cindex thread priority
GNU Common C++ allows one to specify the running priority of a newly 
created thread relative to the "parent" thread which is the thread that is
executing when the constructor is called.  Since most newer C++
implementations do not allow one to call virtual constructors or virtual
methods from constructors, the thread must be "started" after the
constructor returns.  This is done either by defining a "starting"
semaphore object that one or more newly created thread objects can wait
upon, or by invoking an explicit "Start" member function.

@cindex suspended
@cindex resumed
@cindex SIGUSR1
@cindex SIGSTOP
@cindex SIGCONT
@cindex solaris threads
@cindex linux threads
Threads can be "suspended" and "resumed".  As this behavior is not
defined in the Posix "pthread" specification, it is often emulated
through signals.  Typically SIGUSR1 will be used for this purpose in
GNU Common C++ applications, depending in the target platform.  On
Linux, since threads are indeed processes, SIGSTOP and SIGCONT can be
used.  On solaris, the Solaris thread library supports suspend and
resume directly.

@cindex cancelable threads
Threads can be canceled.  Not all platforms support the concept of
externally cancelable threads.  On those platforms and API
implementations that do not, threads are typically canceled through
the action of a signal handler.

@findex Thread::setCancellation
@findex Thread::exit
@findex Thread::run
@cindex cancellation
@cindex cancellation point
As noted earlier, threads are considered running until the "run"
method returns, or until a cancellation request is made.  GNU Common
C++ threads can control how they respond to cancellation, using
setCancellation().  Cancellation requests can be ignored, set to occur
only when a cancellation "point" has been reached in the code, or
occur immediately.  Threads can also exit by returning from run() or
by invoking the exit() method.

@findex Thread::terminate
@cindex thread initialization
@cindex thread destruction
Generally it is a good practice to initialize any resources the thread