Emeric Vigier | 2f62582 | 2012-08-06 11:09:52 -0400 | [diff] [blame] | 1 | \input texinfo @c -*-texinfo-*- |
| 2 | @c %** start of header |
| 3 | @setfilename commoncpp2.info |
| 4 | @settitle GNU Common C++ 2 |
| 5 | @afourpaper |
| 6 | @setchapternewpage odd |
| 7 | @documentlanguage en |
| 8 | @documentencoding ISO-8859-1 |
| 9 | @c %** end of header |
| 10 | |
| 11 | @set EDITION 1.0pre0 |
| 12 | @set VERSION 1.0 |
| 13 | @set UPDATED September 2002 |
| 14 | |
| 15 | @dircategory Development |
| 16 | @direntry |
| 17 | * GNU Common C++ 2: (commoncpp2). GNU Common C++ 2 Framework Documentation. |
| 18 | @end direntry |
| 19 | |
| 20 | @c ----------------------------------------------------------------------- |
| 21 | |
| 22 | @c %** start of summary description and copyright |
| 23 | @ifnottex |
| 24 | GNU Common C++ 2 is the second major release of a C++ framework |
| 25 | offering portable support for threading, sockets, file access, |
| 26 | daemons, persistence, serial I/O, XML parsing, and system services, |
| 27 | initially started by David Sugar and Daniel Silverstone. |
| 28 | |
| 29 | Copyright @copyright{} 1999, 2000, 2001, 2002 Open Source Telecom Corporation. |
| 30 | @include fdlnotice.texi |
| 31 | @end ifnottex |
| 32 | @c %** end of summary description and copyright |
| 33 | |
| 34 | @c ----------------------------------------------------------------------- |
| 35 | |
| 36 | @c %** start of title and copyright page |
| 37 | @shorttitlepage @titlefont{GNU Common C++ 2} |
| 38 | @titlepage |
| 39 | @sp 10 |
| 40 | @title GNU Common C++ 2 |
| 41 | @subtitle |
| 42 | @subtitle @value{EDITION}th Edition, covering GNU Common C++ version @value{VERSION} |
| 43 | @subtitle @value{UPDATED} |
| 44 | @author David Sugar wrote this document. |
| 45 | @author Federico Montesino Pouzols updated and formatted it in @TeX{}Info |
| 46 | |
| 47 | @page |
| 48 | @vskip 0pt plus 1filll |
| 49 | @center{Copyright @copyright{} 1999, 2000, 2001, 2002 Open Source Telecom Corporation} |
| 50 | @include fdlnotice.texi |
| 51 | @page |
| 52 | @end titlepage |
| 53 | @c %** end of title and copyright page |
| 54 | |
| 55 | @c ----------------------------------------------------------------------- |
| 56 | |
| 57 | @c %** start of top node and master menu |
| 58 | @ifnottex |
| 59 | @node Top |
| 60 | @top |
| 61 | This document describes GNU Common C++ 2, the second major release of |
| 62 | a C++ framework offering portable support for threading, sockets, file |
| 63 | access, daemons, persistence, serial I/O, XML parsing, and system |
| 64 | services, initially started by David Sugar and Daniel Silverstone. |
| 65 | |
| 66 | This is the edition @value{EDITION} of this manual and documents |
| 67 | GNU Common C++ 2 version @value{VERSION}. |
| 68 | @end ifnottex |
| 69 | |
| 70 | @contents |
| 71 | |
| 72 | @menu |
| 73 | * Introduction:: What GNU Common C++ and this manual are. |
| 74 | * Distribution:: How to get GNU Common C++. |
| 75 | * Framework Description:: GNU Common C++ classes. |
| 76 | * Extras:: GNU Common C++ extras. |
| 77 | * Serverlets:: GNU Common C++ serverlets. |
| 78 | * Compiler Options:: Compiler options to use with GNU Common C++. |
| 79 | * Automake Services:: GNU Common C++ automake services. |
| 80 | * Configuring Sources:: Configuring GNU Common C++ sources. |
| 81 | * Developer Documentation:: Information of interest for CC++ developers. |
| 82 | * Licenses:: Library and documentation licenses. |
| 83 | * Class and Data Type Index:: Index of Common C++ classes and data types. |
| 84 | * Method and Function Index:: Index of Common C++ methods and functions. |
| 85 | * Concept Index:: Index of concepts. |
| 86 | @end menu |
| 87 | @c %** end of top node and master menu |
| 88 | |
| 89 | @c ----------------------------------------------------------------------- |
| 90 | |
| 91 | @c %** start of body |
| 92 | @node Introduction |
| 93 | @comment node-name, next, previous, up |
| 94 | @chapter Introduction |
| 95 | @cindex Introduction |
| 96 | |
| 97 | @quotation |
| 98 | @strong{PLEASE NOTE;} This is a preliminary version of this |
| 99 | document. Some information may not be complete or even somewhat |
| 100 | obsolete; bug reports, suggestions and contributions are welcome. |
| 101 | @end quotation |
| 102 | |
| 103 | @cindex reference manual |
| 104 | In writing this document I hope to better explain what the GNU Common |
| 105 | C++ library is about and how it may be used in developing your own C++ |
| 106 | applications. This document is intended as an overview and unifying |
| 107 | document to support the already detailed class-by-class function |
| 108 | descriptions found and browsable in the "doc" subdirectory of the |
| 109 | Common C++ distribution. |
| 110 | |
| 111 | GNU Common C++ offers a set of "portable" classes that can be used to |
| 112 | build highly portable applications in C++. In particular, Common C++ |
| 113 | offers classes that abstract threading, sockets, synchronization, serial |
| 114 | I/O, "config" file parsing, class object persistence, shared object module |
| 115 | loading, daemon management, and optimized "block" and memory mapped file |
| 116 | I/O under a set of consistent classes that your application can then |
| 117 | be built from. The goal is to write your application to use the portable |
| 118 | abstract services and classes of the GNU Common C++ libraries rather than |
| 119 | having to access low level system services directly. |
| 120 | |
| 121 | There is a large diversity of views in how one should code a C++ |
| 122 | framework. Since a large number of older C++ compilers remain in |
| 123 | everyday use, I choose to use what I felt was an appropriate set of |
| 124 | C++ language features and practices to provide the greatest compiler |
| 125 | compatibility and to generate the most optimized code for GNU Common |
| 126 | C++. To further reduce the overhead of writing GNU Common C++ |
| 127 | applications, I have split the primary library image itself into |
| 128 | several different shared libraries. This allowed me to collect the |
| 129 | more obscure and less likely to be used features into separate |
| 130 | libraries which need never be loaded. |
| 131 | |
| 132 | Finally, in designing GNU Common C++, I assume that class extension |
| 133 | (inheritance) is the primary vehicle for application development. The |
| 134 | GNU Common C++ framework, while offering many classes that are usable |
| 135 | directly, is designed for one to create applications by extending Common |
| 136 | C++ "base" classes into an application specific versions of said classes |
| 137 | as needed. |
| 138 | |
| 139 | |
| 140 | @c ----------------------------------------------------------------------- |
| 141 | @node Distribution |
| 142 | @chapter Distribution |
| 143 | @cindex distribution |
| 144 | |
| 145 | @cindex free software |
| 146 | @cindex GNU GPL |
| 147 | @cindex linking exception |
| 148 | @cindex GNU FDL |
| 149 | @cindex philosophy |
| 150 | This manual is licensed under the terms of the @acronym{GNU} Free |
| 151 | Documentation License, @xref{GNU Free Documentation License}. |
| 152 | |
| 153 | @acronym{GNU} Common C++ is free software (see |
| 154 | @url{http://www.gnu.org/philosophy/philosophy.html}). There are |
| 155 | several ways to get @acronym{GNU} Common C++, refer to |
| 156 | @url{http://www.gnu.org} and |
| 157 | @url{http://www.gnu.org/software/commoncpp/}. |
| 158 | |
| 159 | The @acronym{GNU} Common C++ framework is licensed under the terms of |
| 160 | the @acronym{GNU} General Public License, @xref{GNU General Public |
| 161 | License}, plus a linking exception, @xref{GNU Common C++ Linking |
| 162 | Exception}, that grants additional privileges. These privileges are |
| 163 | similar to the terms Guile is licensed under and constitute privileges |
| 164 | similar to the LGPL. David Sugar explains why these licensing terms |
| 165 | were chosen for Common C++ as follows: |
| 166 | |
| 167 | The one problem I recall immediately with the LGPL as it applies to |
| 168 | C++ class frameworks is the way it defines and refers to ``linking'' |
| 169 | vs ``derived works''. In concept, a C++ header with inline members or |
| 170 | template is not ``linked'' in the same sense as one might presume the |
| 171 | meaning in traditional C library, and what does one make of a class |
| 172 | who's base class is defined in a header in a LGPL protected library? |
| 173 | Is creating a derived C++ class purely a linking operation or creating |
| 174 | a derived/composite work? |
| 175 | |
| 176 | At the time it seemed simpler to take the language of the GPL and |
| 177 | provide an appropriate privileges to allow Common C++ to be used in |
| 178 | ways that achieve the same goals of the LGPL, but without using the |
| 179 | same choice of language for this that is found in the LGPL. We |
| 180 | actually looked at the Guile license, which also faced many of these |
| 181 | questions, and choose to use their methodology for creating a special |
| 182 | privilege in this regard. Of course, this was a number of years ago, |
| 183 | and the language of the LGPL (and GPL) has evolved over time to better |
| 184 | address the needs of object oriented frameworks. If the language of |
| 185 | the current LGPL were close enough to resolving these goals, I think |
| 186 | we would likely switch to it, as that would resolve some confusion |
| 187 | over the exact license status. I have found it simpler to explain it |
| 188 | as a LGPL-like license since we were trying for much the same effect |
| 189 | within the context of a C++ framework, and most people basically |
| 190 | understand what the LGPL is. |
| 191 | |
| 192 | |
| 193 | @c ----------------------------------------------------------------------- |
| 194 | @node Framework Description |
| 195 | @chapter Framework Description |
| 196 | @cindex Framework Description |
| 197 | |
| 198 | This chapter provides a description of the GNU Common C++ framework |
| 199 | main components. |
| 200 | |
| 201 | @menu |
| 202 | * Overall Concepts:: Global GNU Common C++ Practices. |
| 203 | * Threading Concepts:: GNU Common C++ Threading Concepts. |
| 204 | * Synchronization:: GNU Common C++ Synchronization. |
| 205 | * Sockets:: GNU Common C++ Sockets. |
| 206 | * Serial I/O:: GNU Common C++ Serial I/O. |
| 207 | * Block I/O:: GNU Common C++ Block I/O. |
| 208 | * Daemons:: GNU Common C++ Daemon Support. |
| 209 | * Persistence:: GNU Common C++ Persistence. |
| 210 | * Configuration and Misc.:: GNU Common C++ Configuration and Other Things. |
| 211 | * Numbers and Dates:: GNU Common C++ Numbers and Dates Manipulation. |
| 212 | * URL Streams:: GNU Common C++ HTTP Support. |
| 213 | * XML Streams and RPC:: GNU Common C++ XML Streams and RPC. |
| 214 | * Exceptions:: GNU Common C++ Exception Model. |
| 215 | * Templates:: GNU Common C++ Template Subsystem |
| 216 | @end menu |
| 217 | |
| 218 | @c ----------------------------------------------------------------------- |
| 219 | @node Overall Concepts |
| 220 | @section Overall Concepts |
| 221 | @cindex Overall Concepts |
| 222 | |
| 223 | @cindex ost |
| 224 | @cindex ost namespace |
| 225 | @cindex namespace |
| 226 | Unless explicitly stated, all GNU Common C++ symbols are under the |
| 227 | @code{ost} namespace@footnote{Provided the C++ compiler used to |
| 228 | compile GNU Common C++ suupports namespaces, which is checked at |
| 229 | configuration time.}. Thus, when we refer to the Thread class, we |
| 230 | actually refer to ost::Thread. |
| 231 | |
| 232 | The GNU Common C++ framework actually consists of two libraries: |
| 233 | @file{ccgnu2} and @file{ccext2}@footnote{@xref{Compiler Options}, for |
| 234 | how to specify compiling and linking options for these libraries. On |
| 235 | Win32 systems, these libraries are compiled as @file{ccgnu2.dll} and |
| 236 | @file{ccext2.dll}}. The first includes core functionality that other |
| 237 | things commonly depend on, such as threading and synchronization. That |
| 238 | way, if you are building a tight application with a small footprint, |
| 239 | you can have it used the ccgnu2 shared image alone. On the contrary, |
| 240 | things that require or induce new library link requirements are |
| 241 | included in @file{ccext2}. Hence, for example, if you do not wish to |
| 242 | use XML parsing in your application, why create an unused library |
| 243 | dependency for libxml2? The idea being that one can, if one needs to, |
| 244 | use only ``core'' features found in ccgnu2 and then create very |
| 245 | compact executables with very few additional library dependencies. |
| 246 | |
| 247 | |
| 248 | @c ----------------------------------------------------------------------- |
| 249 | @node Threading Concepts |
| 250 | @section Threading Concepts |
| 251 | @cindex Threading Concepts |
| 252 | |
| 253 | @cindex threading |
| 254 | @cindex APE |
| 255 | @cindex Java threading |
| 256 | Threading was the first part of GNU Common C++ I wrote, back when it |
| 257 | was still the APE library. My goal for GNU Common C++ threading has |
| 258 | been to make threading as natural and easy to use in C++ application |
| 259 | development as threading is in Java. With this said, one does not |
| 260 | need to use threading at all to take advantage of GNU Common C++. |
| 261 | However, all GNU Common C++ classes are designed at least to be |
| 262 | thread-aware/thread-safe as appropriate and necessary. |
| 263 | |
| 264 | @cindex pthread |
| 265 | @cindex ost_pthread.m4 |
| 266 | @cindex autoconf |
| 267 | GNU Common C++ threading is currently built either from the Posix |
| 268 | "pthread" library or using the win32 SDK. In that the Posix "pthread" |
| 269 | draft has gone through many revisions, and many system implementations |
| 270 | are only marginally compliant, and even then usually in different |
| 271 | ways, I wrote a large series of autoconf macros found in |
| 272 | ost_pthread.m4 which handle the task of identifying which pthread |
| 273 | features and capabilities your target platform supports. In the |
| 274 | process I learned much about what autoconf can and cannot do for |
| 275 | you. |
| 276 | |
| 277 | @cindex GNU pth |
| 278 | @cindex pth |
| 279 | Currently the GNU Portable Thread library (GNU pth) is not directly |
| 280 | supported in GNU Common C++. While GNU "Pth" doesn't offer direct |
| 281 | native threading support or benefit from SMP hardware, many of the |
| 282 | design advantages of threading can be gained from it's use, and the |
| 283 | Pth pthread "emulation" library should be usable with GNU Common C++. |
| 284 | In the future, GNU Common C++ will directly support Pth, as well as |
| 285 | OS/2 and BeOS native threading API's. |
| 286 | |
| 287 | @cindex threading model |
| 288 | GNU Common C++ itself defines a fairly "neutral" threading model that |
| 289 | is not tied to any specific API such as pthread, win32, etc. This |
| 290 | neutral thread model is contained in a series of classes which handle |
| 291 | threading and synchronization and which may be used together to build |
| 292 | reliable threaded applications. |
| 293 | |
| 294 | @tindex Thread |
| 295 | @findex Thread::run |
| 296 | @cindex execution context |
| 297 | @cindex termination |
| 298 | @cindex thread termination |
| 299 | GNU Common C++ defines application specific threads as objects which |
| 300 | are derived from the GNU Common C++ "Thread" base class. At minimum |
| 301 | the "run" method must be implemented, and this method essentially is |
| 302 | the "thread", for it is executed within the execution context of the |
| 303 | thread, and when the run method terminates the thread is assumed to |
| 304 | have terminated. |
| 305 | |
| 306 | @cindex priority |
| 307 | @cindex thread priority |
| 308 | GNU Common C++ allows one to specify the running priority of a newly |
| 309 | created thread relative to the "parent" thread which is the thread that is |
| 310 | executing when the constructor is called. Since most newer C++ |
| 311 | implementations do not allow one to call virtual constructors or virtual |
| 312 | methods from constructors, the thread must be "started" after the |
| 313 | constructor returns. This is done either by defining a "starting" |
| 314 | semaphore object that one or more newly created thread objects can wait |
| 315 | upon, or by invoking an explicit "Start" member function. |
| 316 | |
| 317 | @cindex suspended |
| 318 | @cindex resumed |
| 319 | @cindex SIGUSR1 |
| 320 | @cindex SIGSTOP |
| 321 | @cindex SIGCONT |
| 322 | @cindex solaris threads |
| 323 | @cindex linux threads |
| 324 | Threads can be "suspended" and "resumed". As this behavior is not |
| 325 | defined in the Posix "pthread" specification, it is often emulated |
| 326 | through signals. Typically SIGUSR1 will be used for this purpose in |
| 327 | GNU Common C++ applications, depending in the target platform. On |
| 328 | Linux, since threads are indeed processes, SIGSTOP and SIGCONT can be |
| 329 | used. On solaris, the Solaris thread library supports suspend and |
| 330 | resume directly. |
| 331 | |
| 332 | @cindex cancelable threads |
| 333 | Threads can be canceled. Not all platforms support the concept of |
| 334 | externally cancelable threads. On those platforms and API |
| 335 | implementations that do not, threads are typically canceled through |
| 336 | the action of a signal handler. |
| 337 | |
| 338 | @findex Thread::setCancellation |
| 339 | @findex Thread::exit |
| 340 | @findex Thread::run |
| 341 | @cindex cancellation |
| 342 | @cindex cancellation point |
| 343 | As noted earlier, threads are considered running until the "run" |
| 344 | method returns, or until a cancellation request is made. GNU Common |
| 345 | C++ threads can control how they respond to cancellation, using |
| 346 | setCancellation(). Cancellation requests can be ignored, set to occur |
| 347 | only when a cancellation "point" has been reached in the code, or |
| 348 | occur immediately. Threads can also exit by returning from run() or |
| 349 | by invoking the exit() method. |
| 350 | |
| 351 | @findex Thread::terminate |
| 352 | @cindex thread initialization |
| 353 | @cindex thread destruction |
| 354 | Generally it is a good practice to initialize any resources the thread |
| 355 | may require within the constructor of your derived thread class, and |
| 356 | to purge or restore any allocated resources in the destructor. In |
| 357 | most cases, the destructor will be executed after the thread has |
| 358 | terminated, and hence will execute within the context of the thread |
| 359 | that requested a join rather than in the context of the thread that is |
| 360 | being terminated. Most destructors in derived thread classes should |
| 361 | first call terminate() to make sure the thread has stopped running |
| 362 | before releasing resources. |
| 363 | |
| 364 | @cindex thread join |
| 365 | A GNU Common C++ thread is normally canceled by deleting the thread |
| 366 | object. The process of deletion invokes the thread's destructor, and |
| 367 | the destructor will then perform a "join" against the thread using the |
| 368 | terminate() function. This behavior is not always desirable since the |
| 369 | thread may block itself from cancellation and block the current |
| 370 | "delete" operation from completing. One can alternately invoke |
| 371 | terminate() directly before deleting a thread object. |
| 372 | |
| 373 | @findex Thread::final |
| 374 | @findex operator new |
| 375 | @cindex detached thread |
| 376 | When a given GNU Common C++ thread exits on it's own through it's |
| 377 | run() method, a "final" method will be called. This Final method will |
| 378 | be called while the thread is "detached". If a thread object is |
| 379 | constructed through a "new" operator, it's final method can be used to |
| 380 | "self delete" when done, and allows an independent thread to construct |
| 381 | and remove itself autonomously. |
| 382 | |
| 383 | @findex getThread |
| 384 | @cindex pthread_self |
| 385 | A special global function, getThread(), is provided to identify the |
| 386 | thread object that represents the current execution context you are |
| 387 | running under. This is sometimes needed to deliver signals to the |
| 388 | correct thread. Since all thread manipulation should be done through |
| 389 | the GNU Common C++ (base) thread class itself, this provides the same |
| 390 | functionality as things like "pthread_self" for GNU Common C++. |
| 391 | |
| 392 | GNU Common C++ threads are often aggregated into other classes to |
| 393 | provide services that are "managed" from or operate within the context |
| 394 | of a thread, even within the GNU Common C++ framework itself. A good |
| 395 | example of this is the TCPSession class, which essentially is a |
| 396 | combination of a TCP client connection and a separate thread the user |
| 397 | can define by deriving a class with a Run() method to handle the |
| 398 | connected service. This aggregation logically connects the successful |
| 399 | allocation of a given resource with the construction of a thread to |
| 400 | manage and perform operations for said resource. |
| 401 | |
| 402 | Threads are also used in "service pools". In GNU Common C++, a |
| 403 | service pool is one or more threads that are used to manage a set of |
| 404 | resources. While GNU Common C++ does not provide a direct "pool" |
| 405 | class, it does provide a model for their implementation, usually by |
| 406 | constructing an array of thread "service" objects, each of which can |
| 407 | then be assigned the next new instance of a given resource in turn or |
| 408 | algorithmically. |
| 409 | |
| 410 | @findex Thread::signal |
| 411 | @findex Thread::onDisconnect |
| 412 | @findex Thread::onHangup |
| 413 | @cindex SIGPIPE |
| 414 | @cindex SIGHUP |
| 415 | Threads have signal handlers associated with them. Several signal |
| 416 | types are "predefined" and have special meaning. All signal handlers |
| 417 | are defined as virtual member functions of the Thread class which are |
| 418 | called when a specific signal is received for a given thread. The |
| 419 | "SIGPIPE" event is defined as a "onDisconnect" event since it's normally |
| 420 | associated with a socket disconnecting or broken fifo. The onHangup() |
| 421 | method is associated with the SIGHUP signal. All other signals are |
| 422 | handled through the more generic signal(). |
| 423 | |
| 424 | Incidently, unlike Posix, the win32 API has no concept of signals, and |
| 425 | certainly no means to define or deliver signals on a per-thread basis. |
| 426 | For this reason, no signal handling is supported or emulated in the |
| 427 | win32 implementation of GNU Common C++ at this time. |
| 428 | |
| 429 | @tindex TCPStream |
| 430 | @tindex TCPSession |
| 431 | In addition to TCPStream, there is a TCPSession class which combines a |
| 432 | thread with a TCPStream object. The assumption made by TCPSession is |
| 433 | that one will service each TCP connection with a separate thread, and |
| 434 | this makes sense for systems where extended connections may be |
| 435 | maintained and complex protocols are being used over TCP. |
| 436 | |
| 437 | |
| 438 | @c ----------------------------------------------------------------------- |
| 439 | @node Synchronization |
| 440 | @section Synchronization |
| 441 | @cindex Synchronization |
| 442 | |
| 443 | Synchronization objects are needed when a single object can be |
| 444 | potentially manipulated by more than one thread (execution) context |
| 445 | concurrently. GNU Common C++ provides a number of specialized classes |
| 446 | and objects that can be used to synchronize threads. |
| 447 | |
| 448 | @tindex Mutex |
| 449 | One of the most basic GNU Common C++ synchronization object is the |
| 450 | Mutex class. A Mutex only allows one thread to continue execution at |
| 451 | a given time over a specific section of code. Mutex's have a enter |
| 452 | and leave method; only one thread can continue from the Enter until |
| 453 | the Leave is called. The next thread waiting can then get through. |
| 454 | Mutex's are also known as "CRITICAL SECTIONS" in win32-speak. |
| 455 | |
| 456 | The GNU Common C++ mutex is presumed to support recursive locking. |
| 457 | This was deemed essential because a mutex might be used to block |
| 458 | individual file requests in say, a database, but the same mutex might |
| 459 | be needed to block a whole series of database updates that compose a |
| 460 | "transaction" for one thread to complete together without having to |
| 461 | write alternate non-locking member functions to invoke for each part |
| 462 | of a transaction. |
| 463 | |
| 464 | Strangely enough, the original pthread draft standard does not |
| 465 | directly support recursive mutexes. In fact this is the most common |
| 466 | "NP" extension for most pthread implementations. GNU Common C++ |
| 467 | emulates recursive mutex behavior when the target platform does not |
| 468 | directly support it. |
| 469 | |
| 470 | @tindex ThreadLock |
| 471 | In addition to the Mutex, GNU Common C++ supports a rwlock class |
| 472 | (ThreadLock). This implements the X/Open recommended "rwlock". On |
| 473 | systems which do not support rwlock's, the behavior is emulated with a |
| 474 | Mutex; however, the advantage of a rwlock over a mutex is then |
| 475 | entirely lost. There has been some suggested clever hacks for |
| 476 | "emulating" the behavior of a rwlock with a pair of mutexes and a |
| 477 | semaphore, and one of these will be adapted for GNU Common C++ in the |
| 478 | future for platforms that do not support rwlock's directly. |
| 479 | |
| 480 | @tindex Semaphore |
| 481 | GNU Common C++ also supports "semaphores". Semaphores are typically |
| 482 | used as a counter for protecting or limiting concurrent access to a |
| 483 | given resource, such as to permitting at most "x" number of threads to |
| 484 | use resource "y", for example. Semaphore's are also convenient to use |
| 485 | as synchronization objects to rondevous and signal activity and/or |
| 486 | post pending service requests between one thread thread and another. |
| 487 | |
| 488 | @tindex Event |
| 489 | In addition to Semaphore objects, GNU Common C++ supports "Event" |
| 490 | objects. Event objects are triggered "events" which are used to |
| 491 | notify one thread of some event it is waiting for from another thread. |
| 492 | These event objects use a trigger/reset mechanism and are related to |
| 493 | low level conditional variables. |
| 494 | |
| 495 | @tindex ThreadKey |
| 496 | @tindex AtomicCounter |
| 497 | @cindex reference counting |
| 498 | A special class, the ThreadKey, is used to hold state information that |
| 499 | must be unique for each thread of context. Finally, GNU Common C++ |
| 500 | supports a thread-safe "AtomicCounter" class. This can often be used |
| 501 | for reference counting without having to protect the counter with a |
| 502 | separate Mutex counter. This lends to lighter-weight code. |
| 503 | |
| 504 | |
| 505 | @c ----------------------------------------------------------------------- |
| 506 | @node Sockets |
| 507 | @section Sockets |
| 508 | @cindex Sockets |
| 509 | |
| 510 | @cindex Java sockets |
| 511 | GNU Common C++ provides a set of classes that wrap and define the |
| 512 | operation of network "sockets". Much like with Java, there are also a |
| 513 | related set of classes that are used to define and manipulate objects |
| 514 | which act as "hostname" and "network addresses" for socket |
| 515 | connections. |
| 516 | |
| 517 | @tindex InetAddress |
| 518 | @tindex InetHostAddress |
| 519 | @tindex InetMaskAddress |
| 520 | @tindex BroadcastAddress |
| 521 | The network name and address objects are all derived from a common |
| 522 | InetAddress base class. Specific classes, such as InetHostAddress, |
| 523 | InetMaskAddress, etc, are defined from InetAddress entirely so that |
| 524 | the manner a network address is being used can easily be documented |
| 525 | and understood from the code and to avoid common errors and accidental |
| 526 | misuse of the wrong address object. For example, a "connection" to |
| 527 | something that is declared as a "InetHostAddress" can be kept |
| 528 | type-safe from a "connection" accidently being made to something that |
| 529 | was declared a "BroadcastAddress". |
| 530 | |
| 531 | @tindex Socket |
| 532 | @cindex QoS |
| 533 | @cindex sockopt |
| 534 | @cindex Dont-Route |
| 535 | @cindex Keep-Alive |
| 536 | The socket is itself defined in a single base class named, quite |
| 537 | unremarkably, "Socket". This base class is not directly used, but is |
| 538 | provided to offer properties common to other GNU Common C++ socket |
| 539 | classes, including the socket exception model and the ability to set |
| 540 | socket properties such as QoS, "sockopts" properties like Dont-Route |
| 541 | and Keep-Alive, etc. |
| 542 | |
| 543 | @tindex TCPStream |
| 544 | @findex TCPStream::operator<< |
| 545 | @findex TCPStream::operator>> |
| 546 | The first usable socket class is the TCPStream. Since a TCP |
| 547 | connection is always a "streamed" virtual circuit with flow control, |
| 548 | the standard stream operators ("<<" and ">>") may be used with |
| 549 | TCPStream directly. TCPStream itself can be formed either by |
| 550 | connecting to a bound network address of a TCP server, or can be |
| 551 | created when "accepting" a network connection from a TCP server. |
| 552 | |
| 553 | @cindex TCPSocket |
| 554 | An implicit and unique TCPSocket object exists in GNU Common C++ to |
| 555 | represent a bound TCP socket acting as a "server" for receiving |
| 556 | connection requests. This class is not part of TCPStream because such |
| 557 | objects normally perform no physical I/O (read or write operations) |
| 558 | other than to specify a listen backlog queue and perform "accept" |
| 559 | operations for pending connections. The GNU Common C++ TCPSocket |
| 560 | offers a Peek method to examine where the next pending connection is |
| 561 | coming from, and a Reject method to flush the next request from the |
| 562 | queue without having to create a session. |
| 563 | |
| 564 | @findex TCPSocket::onAccept |
| 565 | The TCPSocket also supports a "onAccept" method which can be called |
| 566 | when a TCPStream related object is created from a TCPSocket. By |
| 567 | creating a TCPStream from a TCPSocket, an accept operation |
| 568 | automatically occurs, and the TCPSocket can then still reject the |
| 569 | client connection through the return status of it's OnAccept method. |
| 570 | |
| 571 | @tindex UDPSocket |
| 572 | In addition to connected TCP sessions, GNU Common C++ supports UDP |
| 573 | sockets and these also cover a range of functionality. Like a |
| 574 | TCPSocket, A UDPSocket can be created bound to a specific network |
| 575 | interface and/or port address, although this is not required. UDP |
| 576 | sockets also are usually either connected or otherwise "associated" |
| 577 | with a specific "peer" UDP socket. Since UDP sockets operate through |
| 578 | discreet packets, there are no streaming operators used with UDP |
| 579 | sockets. |
| 580 | |
| 581 | @tindex UDPBroadcast |
| 582 | In addition to the UDP "socket" class, there is a "UDPBroadcast" |
| 583 | class. The UDPBroadcast is a socket that is set to send messages to a |
| 584 | subnet as a whole rather than to an individual peer socket that it may |
| 585 | be associated with. |
| 586 | |
| 587 | @tindex UDPDuplex |
| 588 | UDP sockets are often used for building "realtime" media streaming |
| 589 | protocols and full duplex messaging services. When used in this |
| 590 | manner, typically a pair of UDP sockets are used together; one socket |
| 591 | is used to send and the other to receive data with an associated pair |
| 592 | of UDP sockets on a "peer" host. This concept is represented through |
| 593 | the GNU Common C++ UDPDuplex object, which is a pair of sockets that |
| 594 | communicate with another UDPDuplex pair. |
| 595 | |
| 596 | @tindex SocketPort |
| 597 | @tindex SocketService |
| 598 | Finally, a special set of classes, "SocketPort" and "SocketService", |
| 599 | exist for building realtime streaming media servers on top of UDP and |
| 600 | TCP protocols. The "SocketPort" is used to hold a connected or |
| 601 | associated TCP or UDP socket which is being "streamed" and which |
| 602 | offers callback methods that are invoked from a "SocketService" |
| 603 | thread. SocketService's can be pooled into logical thread pools that |
| 604 | can service a group of SocketPorts. A millisecond accurate "timer" is |
| 605 | associated with each SocketPort and can be used to time synchronize |
| 606 | SocketPort I/O operations. |
| 607 | |
| 608 | |
| 609 | @c ----------------------------------------------------------------------- |
| 610 | @node Serial I/O |
| 611 | @section Serial I/O |
| 612 | @cindex Serial I/O |
| 613 | |
| 614 | GNU Common C++ serial I/O classes are used to manage serial devices |
| 615 | and implement serial device protocols. From the point of view of GNU |
| 616 | Common C++, serial devices are supported by the underlying Posix |
| 617 | specified "termios" call interface. |
| 618 | |
| 619 | The serial I/O base class is used to hold a descriptor to a serial |
| 620 | device and to provide an exception handling interface for all serial |
| 621 | I/O classes. The base class is also used to specify serial I/O |
| 622 | properties such as communication speed, flow control, data size, and |
| 623 | parity. The "Serial" base class is not itself directly used in |
| 624 | application development, however. |
| 625 | |
| 626 | GNU Common C++ Serial I/O is itself divided into two conceptual modes; |
| 627 | frame oriented and line oriented I/O. Both frame and line oriented |
| 628 | I/O makes use of the ability of the underlying tty driver to buffer |
| 629 | data and return "ready" status from when select either a specified |
| 630 | number of bytes or newline record has been reached by manipulating |
| 631 | termios c_cc fields appropriately. This provides some advantage in |
| 632 | that a given thread servicing a serial port can block and wait rather |
| 633 | than have to continually poll or read each and every byte as soon as |
| 634 | it appears at the serial port. |
| 635 | |
| 636 | @tindex TTYStream |
| 637 | @findex TTYStream::operator<< |
| 638 | @findex TTYStream::operator>> |
| 639 | @tindex ttystream |
| 640 | The first application relevant serial I/O class is the TTYStream |
| 641 | class. TTYStream offers a linearly buffered "streaming" I/O session |
| 642 | with the serial device. Furthermore, traditional C++ "stream" |
| 643 | operators (<< and >>) may be used with the serial device. A more |
| 644 | "true" to ANSI C++ library format "ttystream" is also available, and |
| 645 | this supports an "open" method in which one can pass initial serial |
| 646 | device parameters immediately following the device name in a single |
| 647 | string, as in "/dev/tty3a:9600,7,e,1", as an example. |
| 648 | |
| 649 | @tindex TTYSession |
| 650 | The TTYSession aggragates a TTYStream and a GNU Common C++ Thread |
| 651 | which is assumed to be the execution context that will be used to |
| 652 | perform actual I/O operations. This class is very anagolous to |
| 653 | TCPSession. |
| 654 | |
| 655 | @tindex TTYPort |
| 656 | @tindex TTYService |
| 657 | The TTYPort and TTYService classes are used to form thread-pool |
| 658 | serviced serial I/O protocol sets. These can be used when one has a |
| 659 | large number of serial devices to manage, and a single (or limited |
| 660 | number of) thread(s) can then be used to service the tty port objects |
| 661 | present. Each tty port supports a timer control and several virtual |
| 662 | methods that the service thread can call when events occur. This |
| 663 | model provides for "callback" event management, whereby the service |
| 664 | thread performs a "callback" into the port object when events occur. |
| 665 | Specific events supported include the expiration of a TTYPort timer, |
| 666 | pending input data waiting to be read, and "sighup" connection breaks. |
| 667 | |
| 668 | |
| 669 | @c ----------------------------------------------------------------------- |
| 670 | @node Block I/O |
| 671 | @section Block I/O |
| 672 | @cindex Block I/O |
| 673 | |
| 674 | @tindex RandomFile |
| 675 | GNU Common C++ block I/O classes are meant to provide more convenient |
| 676 | file control for paged or random access files portably, and to answer |
| 677 | many issues that ANSI C++ leaves untouched in this area. A common |
| 678 | base class, RandomFile, is provided for setting descriptor attributes |
| 679 | and handling exceptions. From this, three kinds of random file access |
| 680 | are supported. |
| 681 | |
| 682 | @tindex ThreadFile |
| 683 | @findex pwread |
| 684 | @findex pwwrite |
| 685 | ThreadFile is meant for use by a threaded database server where |
| 686 | multiple threads may each perform semi-independent operations on a |
| 687 | given database table stored on disk. A special "fcb" structure is |
| 688 | used to hold file "state", and pread/pwrite is used whenever possible |
| 689 | for optimized I/O. On systems that do not offer pwread/pwrite, a |
| 690 | Mutex lock is used to protect concurrent lseek and read/write |
| 691 | operations. ThreadFile managed databases are assumed to be used only |
| 692 | by the local server and through a single file descriptor. |
| 693 | |
| 694 | @tindex SharedFile |
| 695 | SharedFile is used when a database may be shared between multiple |
| 696 | processes. SharedFile automatically applies low level byte-range |
| 697 | "file locks", and provides an interface to fetch and release |
| 698 | byte-range locked portions of a file. |
| 699 | |
| 700 | @tindex MappedFile |
| 701 | @findex MappedFile::sync |
| 702 | The MappedFile class provides a portable interface to memory mapped |
| 703 | file access. One can map and unmap portions of a file on demand, and |
| 704 | update changed memory pages mapped from files immediately through |
| 705 | sync(). |
| 706 | |
| 707 | |
| 708 | @c ----------------------------------------------------------------------- |
| 709 | @node Daemons |
| 710 | @section Daemons |
| 711 | @cindex Daemons |
| 712 | |
| 713 | @findex pdetach |
| 714 | @cindex slog |
| 715 | Daemon support consists of two GNU Common C++ features. The first is |
| 716 | the "pdetach" function. This function provides a simple and portable |
| 717 | means to fork/detach a process into a daemon. In addition, the "slog" |
| 718 | object is provided. |
| 719 | |
| 720 | @tindex Slog |
| 721 | @cindex slog |
| 722 | @cindex clog |
| 723 | @findex Slog::operator<< |
| 724 | "slog" is an object which behaves very similar to the Standard C++ |
| 725 | "clog". The key difference is that the "slog" object sends it's |
| 726 | output to the system logging daemon (typically syslogd) rather than |
| 727 | through stderr. "slog" can be streamed with the << operator just like |
| 728 | "clog". "slog" can also accept arguments to specify logging severity |
| 729 | level, etc. |
| 730 | |
| 731 | |
| 732 | @c ----------------------------------------------------------------------- |
| 733 | @node Persistence |
| 734 | @section Persistence |
| 735 | @cindex Persistence |
| 736 | |
| 737 | The GNU Common C++ Persistence library was designed with one thought |
| 738 | foremost - namely that large interlinked structures should be easily |
| 739 | serializable. The current implementation is @emph{not} endian safe, |
| 740 | and so, whilst it should in theory be placed in the "Extras" section, |
| 741 | the codebase itself is considered stable enough to be part of the main |
| 742 | distribution. |
| 743 | |
| 744 | @tindex Persistence::BaseObject |
| 745 | @findex IMPLEMENT_PERSISTENCE |
| 746 | @findex DECLARE_PERSISTENCE |
| 747 | The Persistence library classes are designed to provide a quick and |
| 748 | easy way to make your data structures serializable. The only way of |
| 749 | doing this safely is to inherit your classes from the provided class |
| 750 | Persistence::BaseObject. The macros "IMPLEMENT_PERSISTENCE" and |
| 751 | "DECLARE_PERSISTENCE" provide all the function prototypes and |
| 752 | implementation details you may require to get your code off the |
| 753 | ground. |
| 754 | |
| 755 | |
| 756 | @c ----------------------------------------------------------------------- |
| 757 | @node Configuration and Misc. |
| 758 | @section Configuration and Misc. |
| 759 | @cindex Configuration and Misc. |
| 760 | |
| 761 | @tindex MemPager |
| 762 | There are a number of odd and specialized utility classes found in |
| 763 | Common C++. The most common of these is the "MemPager" class. This |
| 764 | is basically a class to enable page-grouped "cumulative" memory |
| 765 | allocation; all accumulated allocations are dropped during the |
| 766 | destructor. This class has found it's way in a lot of other utility |
| 767 | classes in GNU Common C++. |
| 768 | |
| 769 | @tindex Keydata |
| 770 | The most useful of the misc. classes is the Keydata class. This class |
| 771 | is used to load and then hold "keyword = value" pairs parsed from a |
| 772 | text based "config" file that has been divided into "[sections]". |
| 773 | Keydata can also load a table of "initialization" values for keyword |
| 774 | pairs that were not found in the external file. |
| 775 | |
| 776 | One typically derives an application specific keydata class to load a |
| 777 | specific portion of a known config file and initialize it's values. |
| 778 | One can then declare a global instance of these objects and have |
| 779 | configuration data initialized automatically as the executable is |
| 780 | loaded. |
| 781 | |
| 782 | Hence, if I have a "[paths]" section in a "/etc/server.conf" file, I |
| 783 | might define something like: |
| 784 | |
| 785 | @example |
| 786 | @cartouche |
| 787 | class KeyPaths : public Keydata |
| 788 | @{ |
| 789 | public: |
| 790 | KeyPaths() : Keydata("/server/paths") |
| 791 | @{ |
| 792 | static KEYDEF *defvalues = @{ |
| 793 | @{"datafiles", "/var/server"@}, |
| 794 | @{NULL, NULL@}@}; |
| 795 | |
| 796 | // @r{override with [paths] from "~/.serverrc" if avail.} |
| 797 | |
| 798 | Load("~server/paths"); |
| 799 | Load(defvalues); |
| 800 | @} |
| 801 | @}; |
| 802 | |
| 803 | KeyPaths keypaths; |
| 804 | @end cartouche |
| 805 | @end example |
| 806 | |
| 807 | |
| 808 | @c ----------------------------------------------------------------------- |
| 809 | @node Numbers and Dates |
| 810 | @section Numbers and Dates |
| 811 | @cindex Numbers and Dates |
| 812 | |
| 813 | @tindex Number |
| 814 | @tindex ZNumber |
| 815 | @tindex Date |
| 816 | @tindex DateNumber |
| 817 | @emph{TODO.} This section will explain the number manipulation classes |
| 818 | (@code{Number} and @code{ZNumber}, as well as the data related classes |
| 819 | (@code{Date} and @code{DateNumber}). |
| 820 | |
| 821 | |
| 822 | @c ----------------------------------------------------------------------- |
| 823 | @node URL Streams |
| 824 | @section URL Streams |
| 825 | @cindex URL Streams |
| 826 | |
| 827 | @tindex URLStream |
| 828 | @cindex URL related functions |
| 829 | @emph{TODO.} This section will explain the URLStream class, as well as |
| 830 | the following URL related functions: |
| 831 | |
| 832 | @ftable @code |
| 833 | @item URLStream |
| 834 | |
| 835 | @item urlDecode |
| 836 | |
| 837 | @item urlEncode |
| 838 | |
| 839 | @item b64Decode |
| 840 | |
| 841 | @item b64Encode |
| 842 | |
| 843 | @end ftable |
| 844 | |
| 845 | In the meantime you can have a look at the @file{urlfetch.cpp} demo, |
| 846 | which is a good example of use of URLStream to retrieve documents from |
| 847 | URLs. |
| 848 | |
| 849 | |
| 850 | @c ----------------------------------------------------------------------- |
| 851 | @node XML Streams and RPC |
| 852 | @section XML Streams and RPC |
| 853 | @cindex XML Streams and RPC |
| 854 | |
| 855 | @tindex XMLStream |
| 856 | @tindex XMLRPC |
| 857 | @emph{TODO.} This section will explain the XML streams parsing |
| 858 | (@code{XMLStream} class) and XML RPC (@code{XMLRPC} class) facilities |
| 859 | of Common C++. In the meantime, you can have a look at the |
| 860 | @file{xmlfetch.cpp} demo, which defines a basic XML parser for URL |
| 861 | streams. |
| 862 | |
| 863 | |
| 864 | @c ----------------------------------------------------------------------- |
| 865 | @node Exceptions |
| 866 | @section Exceptions |
| 867 | @cindex Exceptions |
| 868 | |
| 869 | @tindex Exception |
| 870 | @tindex std::exception |
| 871 | @emph{TODO.} This section will explain the exception model of Common |
| 872 | C++, based on the @code{Exception} class, derived from std::exception. |
| 873 | |
| 874 | @tindex Exception |
| 875 | @tindex IOException |
| 876 | @tindex SockException |
| 877 | @tindex DirException |
| 878 | @tindex DSOException |
| 879 | @tindex FIFOException |
| 880 | @tindex PipeException |
| 881 | @tindex FileException |
| 882 | @tindex FTPException |
| 883 | @tindex SerException |
| 884 | @tindex ThrException |
| 885 | @tindex PersistException |
| 886 | Other exception classes that will be commented are: |
| 887 | @code{IOException}, @code{SockException}, @code{DirException}, |
| 888 | @code{DSOException}, @code{FIFOException}, @code{PipeException}, |
| 889 | @code{FileException}, @code{FTPException}, @code{SerException}, |
| 890 | @code{ThrException} and @code{PersistException}. In the meantime you |
| 891 | can have a look at the exception class hierarchy on the reference |
| 892 | manual. |
| 893 | |
| 894 | |
| 895 | @c ----------------------------------------------------------------------- |
| 896 | @node Templates |
| 897 | @section Templates |
| 898 | @cindex Templates |
| 899 | |
| 900 | @tindex objCounter |
| 901 | @tindex objList |
| 902 | @tindex objMap |
| 903 | @tindex keyMap] |
| 904 | @tindex objSync |
| 905 | @tindex cstring |
| 906 | @tindex cistring |
| 907 | @tindex Pointer |
| 908 | @tindex Counter |
| 909 | @findex abs |
| 910 | @emph{TODO.} This section will explain the template subsistem of |
| 911 | Common C++. |
| 912 | |
| 913 | |
| 914 | |
| 915 | @c ----------------------------------------------------------------------- |
| 916 | @node Extras |
| 917 | @chapter Extras |
| 918 | @cindex Extras |
| 919 | |
| 920 | @emph{TODO: this is rather outdated.} |
| 921 | |
| 922 | At the time of the release of GNU Common C++ 1.0, it was deemed that |
| 923 | several class libraries either were incomplete or still experimental, |
| 924 | and the 1.0 designation seemed very inappropriate for these libraries. |
| 925 | I also wanted to have a mechanism to later add new GNU Common C++ |
| 926 | class libraries without having to disrupt or add experimental code |
| 927 | into the main GNU Common C++ release. |
| 928 | |
| 929 | To resolve this issue, a second package has been created, and is named |
| 930 | GNU "GNU Common C++ Extras". The extras package simply holds class |
| 931 | frameworks that are still not considered "mature" or "recommended". |
| 932 | This package can be downloaded, compiled, and installed, after GNU |
| 933 | Common C++ itself. Many of the class libraries appearing in the |
| 934 | extras package are likely to appear in GNU Common C++ proper at some |
| 935 | future date, and should be considered usable in their current form. |
| 936 | They are made available both to support continued development of GNU |
| 937 | Common C++ proper and because, while not yet mature, they are |
| 938 | considered "useful" in some manner. |
| 939 | |
| 940 | The initial GNU Common C++ "extras" package consisted of two |
| 941 | libraries; Common C++ "scripting" and "math". The scripting library |
| 942 | (-lccscript) is the GNU Bayonne scripting engine which is used as a |
| 943 | near-realtime event driven embedded scripting engine for "callback" |
| 944 | driven state-event server applications. The Bayonne scripting engine |
| 945 | directly uses C++ inheritance to extend the Bayonne dialect for |
| 946 | application specific features and is used as a core technology in the |
| 947 | GNU Bayonne, DBS, and Meridian telephony servers and as part of the a |
| 948 | free home automation project. There has been some discussion about |
| 949 | folding the GNU Bayonne scripting concepts around a more conventional |
| 950 | scripting language, and so this package currently remains in "extras" |
| 951 | rather than part of GNU Common C++ itself. |
| 952 | |
| 953 | The other package found in the initial "extras" distribution is the |
| 954 | Common C++ math libraries. These are still at a VERY early stage of |
| 955 | development, and may well be depreciated if another suitable free C++ |
| 956 | math/numerical analysis package comes along. |
| 957 | |
| 958 | |
| 959 | @c ----------------------------------------------------------------------- |
| 960 | @node Serverlets |
| 961 | @chapter Serverlets |
| 962 | @cindex Serverlets |
| 963 | |
| 964 | Serverlets are a concept popularized with Java and web servers. There |
| 965 | is a broad abstract architectural concept of serverlets or plugins |
| 966 | that one also finds in my GNU Common C++ projects, though they are not |
| 967 | directly defined as part of GNU Common C++ itself. |
| 968 | |
| 969 | A GNU Common C++ "serverlet" comes about in a Common C++ server |
| 970 | project, such as the Bayonne telephony server, where one wishes to |
| 971 | define functionality for alternate hardware or API's in alternated |
| 972 | shared object files that are selected at runtime, or to add "plugins" |
| 973 | to enhance functionality. A serverlet is defined in this sense as a |
| 974 | "DSO" loaded "-module" object file which is linked at runtime against |
| 975 | a server process that exports it's base classes using |
| 976 | "-export-dynamic". The "server" image then acts as a carrier for the |
| 977 | runtime module's base functionality. |
| 978 | |
| 979 | Modules, or "serverlets", defined in this way do not need to be |
| 980 | compiled with position independent code. The module is only used with |
| 981 | a specific server image and so the runtime address is only resolved |
| 982 | once rather than at different load addresses for different arbitrary |
| 983 | processes. |
| 984 | |
| 985 | I recommend that GNU Common C++ based "servers" which publish and |
| 986 | export base classes in this manner for plugins should also have a |
| 987 | server specific "include" file which can be installed in the cc++ |
| 988 | include directory. |
| 989 | |
| 990 | |
| 991 | @c ----------------------------------------------------------------------- |
| 992 | @node Compiler Options |
| 993 | @chapter Compiler Options |
| 994 | @cindex Compiler Options |
| 995 | |
| 996 | @cindex automake |
| 997 | @cindex autoconf |
| 998 | @cindex configuration |
| 999 | @cindex config.h |
| 1000 | @cindex ccgnu2-config |
| 1001 | GNU Common C++ does a few things special with automake and autoconf. |
| 1002 | When the Common C++ library is built, it saves a number of compiler |
| 1003 | options that can be retrieved by an application being configured to |
| 1004 | use GNU Common C++. These options can be retrieved from the standard |
| 1005 | output of the @command{ccgnu2-config} script, which is installed in the |
| 1006 | machine binaries path. |
| 1007 | |
| 1008 | This is done to assure the same compiler options are used to build |
| 1009 | your application that were in effect when GNU Common C++ itself was |
| 1010 | built. Since linkage information is also saved in this manner, this |
| 1011 | means your application's "configure" script does not have to go |
| 1012 | through the entire process of testing for libraries or GNU Common C++ |
| 1013 | related compiler options all over again. Finally, GNU Common C++ |
| 1014 | saves it's own generated @file{config.h} file in |
| 1015 | @file{cc++/config.h}@footnote{On Win32 systems, a specific |
| 1016 | @file{config.h} located under the win32/cc++/ directory is used and |
| 1017 | installed.}. |
| 1018 | |
| 1019 | @command{ccgnu2-config} has the following options (which are shown if |
| 1020 | you type @command{ccgnu2-config --help}): |
| 1021 | |
| 1022 | @example |
| 1023 | Usage: ccgnu2-config [OPTIONS] |
| 1024 | Options: |
| 1025 | [--prefix] |
| 1026 | [--version] |
| 1027 | [--flags] |
| 1028 | [--libs] |
| 1029 | [--gnulibs] |
| 1030 | [--iolibs] |
| 1031 | [--extlibs] |
| 1032 | [--stdlibs] |
| 1033 | [--includes] |
| 1034 | @end example |
| 1035 | |
| 1036 | For a basic usage of Common C++, you just need the options given by |
| 1037 | the following command: @command{ccgnu2-config --flags --stdlibs}, |
| 1038 | whose output should be something like this: |
| 1039 | |
| 1040 | @example |
| 1041 | foo@@bar:~/$ ccgnu2-config --flags --stdlibs |
| 1042 | -I/usr/local/include/cc++2 -I/usr/local/include -D_GNU_SOURCE |
| 1043 | -L/usr/local/lib -lccext2 -lccgnu2 -lxml2 -lz -ldl -pthread |
| 1044 | @end example |
| 1045 | |
| 1046 | Note that this is just an example, the concrete output on your system |
| 1047 | will probably differ. The first output line (corresponding to |
| 1048 | @code{--flags}) tells what directories must be added to the compiler |
| 1049 | include path, as well as global symbol definitions |
| 1050 | (@code{_GNU_SOURCE}) needed to compile with Common C++. The second |
| 1051 | output line (corresponding to @code{--stdlibs}) gives the linker |
| 1052 | options, both additional library path and libraries that must be |
| 1053 | linked. @code{ccgnu2} and @code{ccext2} are the two libraries Common |
| 1054 | C++ currently consists of. The other libraries shown in the example |
| 1055 | are dependencies of Common C++. |
| 1056 | |
| 1057 | The list shown below tells what information is given by each of the |
| 1058 | options that can be specified to @command{ccgnu2-config}. It also |
| 1059 | specifies what would be the output corresponding to the example given |
| 1060 | before. |
| 1061 | |
| 1062 | @table @code |
| 1063 | |
| 1064 | @item --prefix |
| 1065 | Common C++ Installation path prefix. For example, @code{/usr/local}. |
| 1066 | |
| 1067 | @item --version |
| 1068 | Common C++ version. For example, @code{1.0.0}. |
| 1069 | |
| 1070 | @item --flags |
| 1071 | C++ preprocessor flags. For example, @code{-I/usr/local/include/cc++2 |
| 1072 | -I/usr/local/include -D_GNU_SOURCE}. |
| 1073 | |
| 1074 | @item --libs |
| 1075 | C++ linker options for the main Common C++ library |
| 1076 | (@code{ccgnu2}). For example, @code{-L/usr/local/lib -lccgnu2 -ldl |
| 1077 | -pthread}. |
| 1078 | |
| 1079 | @item --gnulibs |
| 1080 | C++ linker options for the main Common C++ library |
| 1081 | (@code{ccgnu2}). For example, @code{-L/usr/local/lib -lccgnu2 -ldl |
| 1082 | -pthread}. |
| 1083 | |
| 1084 | @item --iolibs |
| 1085 | C++ linker options for the input/output Common C++ library |
| 1086 | (@code{ccgnu2}). For example, @code{-L/usr/local/lib -lccgnu2 -ldl |
| 1087 | -pthread}. |
| 1088 | |
| 1089 | @item --extlibs |
| 1090 | C++ linker options for the Common C++ ``extension'' library |
| 1091 | (@code{ccext2}). For exmple, @code{-lccext2 -lxml2 -lz}. |
| 1092 | |
| 1093 | @item --stdlibs |
| 1094 | C++ linker options for the whole Common C++ (@code{ccgnu2} and |
| 1095 | @code{ccext2}). For example, @code{-L/usr/local/lib -lccext2 -lccgnu2 |
| 1096 | -lxml2 -lz -ldl -pthread}. |
| 1097 | |
| 1098 | @item --includes |
| 1099 | Common C++ specific include path. For example, |
| 1100 | @code{/usr/local/include/cc++2}. |
| 1101 | |
| 1102 | @end table |
| 1103 | |
| 1104 | |
| 1105 | @c ----------------------------------------------------------------------- |
| 1106 | @node Automake Services |
| 1107 | @chapter Automake Services |
| 1108 | @cindex Automake Services |
| 1109 | |
| 1110 | @cindex automake services |
| 1111 | @cindex automake macros |
| 1112 | @cindex ost_commoncxx.m4 |
| 1113 | @cindex configure.in |
| 1114 | @cindex configure.ac |
| 1115 | If you are using automake, you can add the @file{ost_check2.m4} macros |
| 1116 | to your projects autoconf "m4" directory and use several CCXX2_ macros |
| 1117 | for your convenience. A "minimal" @file{configure.in} or |
| 1118 | @file{configure.ac} can be constructed as: |
| 1119 | |
| 1120 | @example |
| 1121 | AC_INIT(something...) |
| 1122 | AC_PROG_CXX |
| 1123 | AC_PROG_CXXCPP |
| 1124 | AM_PROG_LIBTOOL |
| 1125 | AM_INIT_AUTOMAKE(....) |
| 1126 | AM_CONFIG_HEADER(my-local-config.h) |
| 1127 | OST_CCXX2_VERSION(1.0.0) |
| 1128 | @end example |
| 1129 | |
| 1130 | Where @samp{1.0.0} means configure will check for GNU Common C++ 2 |
| 1131 | 1.0.0 or later. These are the macros currently provided: |
| 1132 | |
| 1133 | @table @code |
| 1134 | |
| 1135 | @cindex OST_CCXX2_VERSION |
| 1136 | @item OST_CCXX2_VERSION([MINIMUM-VERSION[,ACTION-IF-FOUND[,ACTION-IF-NOT-FOUND]]]) |
| 1137 | Test for usable version of CommonC++. |
| 1138 | |
| 1139 | @cindex OST_CCXX2_XML |
| 1140 | @item OST_CCXX2_XML([ACTION-IF-TRUE[,ACTION-IF-FALSE]]) |
| 1141 | Test whether the CommonC++ library was compiled with XML parsing support. |
| 1142 | |
| 1143 | @cindex OST_CCXX2_HOARD |
| 1144 | @item OST_CCXX2_HOARD |
| 1145 | Will test for and, if found, add the SMP optimized Hoard memory |
| 1146 | allocator to your application link LIBS. |
| 1147 | |
| 1148 | @cindex OST_CCXX2_FOX |
| 1149 | @item OST_CCXX2_FOX |
| 1150 | Test for the FOX toolkit. |
| 1151 | |
| 1152 | @end table |
| 1153 | |
| 1154 | |
| 1155 | @c ----------------------------------------------------------------------- |
| 1156 | @node Configuring Sources |
| 1157 | @chapter Configuring Sources |
| 1158 | @cindex Configuring Sources |
| 1159 | |
| 1160 | When building GNU Common C++ on platforms that support the use of |
| 1161 | configure, the following specific configuration options are provided: |
| 1162 | |
| 1163 | @table @code |
| 1164 | |
| 1165 | @item --with-pthread[=lib] |
| 1166 | using specified pthread library |
| 1167 | |
| 1168 | @item --with-linuxthreads |
| 1169 | use linux kernel mode library |
| 1170 | |
| 1171 | @item --without-xml |
| 1172 | Disable xml support |
| 1173 | |
| 1174 | @item --with-ftp |
| 1175 | Enable ftp support |
| 1176 | |
| 1177 | @item --with-memaudit |
| 1178 | Enable memory auditing |
| 1179 | |
| 1180 | @item --with-stlport[=dir] |
| 1181 | using SGI portable C++ stream library,ie: /usr/local, not all include directory |
| 1182 | |
| 1183 | @item --enable-debug |
| 1184 | compile for debugging |
| 1185 | |
| 1186 | @item --enable-profiling |
| 1187 | compile for profiling |
| 1188 | @end table |
| 1189 | |
| 1190 | |
| 1191 | @c ----------------------------------------------------------------------- |
| 1192 | @node Developer Documentation |
| 1193 | @chapter Developer Documentation |
| 1194 | @cindex Developer Documentation |
| 1195 | |
| 1196 | This chapter contains information of interest for developers of |
| 1197 | components for the GNU Common C++ framework. |
| 1198 | |
| 1199 | @menu |
| 1200 | * Coding Style:: How a CommonC++ 2 source file should be written. |
| 1201 | * Porting:: Common porting related problems and practices. |
| 1202 | @end menu |
| 1203 | |
| 1204 | |
| 1205 | @c ----------------------------------------------------------------------- |
| 1206 | @node Coding Style |
| 1207 | @section Coding Style |
| 1208 | @cindex Coding Style |
| 1209 | |
| 1210 | How a CommonC++ 2 source file should be written. |
| 1211 | |
| 1212 | @menu |
| 1213 | * Naming Convention:: Overall GNU Common C++ naming conventions. |
| 1214 | * Class Encapsulation:: Class interface design guidelines. |
| 1215 | @end menu |
| 1216 | |
| 1217 | |
| 1218 | @c ----------------------------------------------------------------------- |
| 1219 | @node Naming Convention |
| 1220 | @subsection Naming Convention |
| 1221 | @cindex Naming Convention |
| 1222 | |
| 1223 | @itemize |
| 1224 | @item @strong{Classes and structs}. |
| 1225 | Begin with uppercase with word parts capitalized (ThisIsAClass) |
| 1226 | |
| 1227 | @item @strong{Method (function member, also static member)}. |
| 1228 | Begin with lowercase with word parts capitalized (setSomething, send). |
| 1229 | If a member variable is set, a @code{setXxxx} style name should be |
| 1230 | used, and if a member variable is fetched, a @code{getXxxx} style name |
| 1231 | should be used. Sometimes things might both set and perform an |
| 1232 | action, like @code{setError} in place of @code{Error} in the older |
| 1233 | release, in which case, set should still be used as the prefix. |
| 1234 | Function to handle some event (such as data arrival) should begin with |
| 1235 | @code{on} (ex: @code{onInput}) |
| 1236 | |
| 1237 | @item @strong{Data member}. |
| 1238 | Begin with lowercase with word parts capitalized |
| 1239 | (@code{currentThread}) private member can begin with underscore (_). |
| 1240 | |
| 1241 | @item @strong{Global function}. |
| 1242 | Begin with lowercase with word parts capitalized (@code{getThread}). |
| 1243 | |
| 1244 | @item @strong{Enumeration type}. |
| 1245 | Begin with uppercase with word parts capitalized (@code{Error}). |
| 1246 | |
| 1247 | @item @strong{Enumeration item}. |
| 1248 | Begin with lowercase with word parts capitalized (@code{errSuccess}). |
| 1249 | First word should refer to enumeration type (@code{errFailure}, |
| 1250 | cancelImmediate). For error enum we use the prefix @code{err} |
| 1251 | (everyone should understand the meaning). |
| 1252 | |
| 1253 | @item @strong{Member data types}. |
| 1254 | Sometimes a class might use internal member data types or structs. |
| 1255 | These should be written using @code{class} rather than struct wherever |
| 1256 | possible and treated as inner @code{classes}. Hence, they would be |
| 1257 | capitalized in the same conventions of a class. |
| 1258 | |
| 1259 | @end itemize |
| 1260 | |
| 1261 | |
| 1262 | @c ----------------------------------------------------------------------- |
| 1263 | @node Class Encapsulation |
| 1264 | @subsection Class Encapsulation |
| 1265 | @cindex Class Encapsulation |
| 1266 | |
| 1267 | @itemize |
| 1268 | |
| 1269 | @item @strong{Friend functions}. |
| 1270 | To clean up the namespace we are looking to eliminate @emph{friend |
| 1271 | functions} that exist in the default or ost namespace and we are |
| 1272 | suggesting that in many cases static member functions should be used |
| 1273 | in place of friend functions unless the friend function is actually |
| 1274 | used in multiple classes. |
| 1275 | |
| 1276 | A typical example of this is found in things like @code{getXXX}, which |
| 1277 | might be a friend function for finding a specific named instance of |
| 1278 | @code{XXX} thru a self organized link list contained in @code{XXX}. |
| 1279 | Rather, it is suggested for this to use a static member something like |
| 1280 | @code{XXX::find}. |
| 1281 | |
| 1282 | @item @strong{Scope of view and inheritance}. |
| 1283 | In many cases we combine and mix classes directly in GNU Common C++ |
| 1284 | (multiple inheritence). Hence, classes have to be well designed for |
| 1285 | this possibility. Ideally things that should not be exposed to |
| 1286 | derived classes should be made private so that clashes mixing similar |
| 1287 | classes with common named members do not need to occur. |
| 1288 | |
| 1289 | @item @strong{Access to member properties}. |
| 1290 | A well formed GNU Common C++ class need not expose more than is |
| 1291 | nessisary for it's practical and effective use in derived classes or |
| 1292 | thru proper public methods. Ideally set and get members should be |
| 1293 | used to manipulate internal member variables thru public interfaces |
| 1294 | rather than exposing property values directly thru public |
| 1295 | declarations. These set and get methods should use appropriate valid |
| 1296 | range and error checking logic. |
| 1297 | |
| 1298 | Member properties can often be made visible protected to optimize the |
| 1299 | code of derived classes, and care then needs to be taken when creating |
| 1300 | derived classes to make sure they do have reasonable error checking |
| 1301 | when needed. |
| 1302 | |
| 1303 | @item @strong{Constructors and destructors}. |
| 1304 | It is very common in GNU Common C++ for the constructor to create or |
| 1305 | obtain a resource that remains in scope as long as the object does, |
| 1306 | and is then releas\ed in the destructor when the object falls out of |
| 1307 | scope. Things like Mutexes, Threads and Semaphores and such very much |
| 1308 | behave this way. |
| 1309 | |
| 1310 | @end itemize |
| 1311 | |
| 1312 | @c ----------------------------------------------------------------------- |
| 1313 | @node Porting |
| 1314 | @section Porting |
| 1315 | @cindex Porting |
| 1316 | |
| 1317 | Only for no-remake same problem :). |
| 1318 | |
| 1319 | @itemize @bullet |
| 1320 | |
| 1321 | @cindex FreeBSD |
| 1322 | @cindex pthread_join |
| 1323 | @item FreeBSD: assuming having thread A and B. If A call pthread_join |
| 1324 | on B and B call pthread_detach and then exit thread A hang. |
| 1325 | |
| 1326 | @cindex Solaris |
| 1327 | @item Solaris: On multiple inheriting from streambuf and iostream together |
| 1328 | streambuf should inherited first (and initialized too). |
| 1329 | |
| 1330 | @cindex Win32 |
| 1331 | @cindex MSVC |
| 1332 | @cindex DLL |
| 1333 | @item Win32/MSVC6: if you use CC++ DLL library you MUST use C++ DLL library. |
| 1334 | @code{iostream} use a pointer to object. This object pointer can be |
| 1335 | different from library static linked and dinamically linked, so |
| 1336 | iostream see distinct object, causing strange exception and crashes. |
| 1337 | |
| 1338 | @cindex GCC |
| 1339 | @item @acronym{GCC}: including declaration for polimorphic class cause |
| 1340 | link to typeinfo, but typeinfos are defined only in module with |
| 1341 | classes constructors Include only needed header (this problem |
| 1342 | disappear with optimization). |
| 1343 | |
| 1344 | @end itemize |
| 1345 | |
| 1346 | @c %** end of body |
| 1347 | |
| 1348 | |
| 1349 | @c ----------------------------------------------------------------------- |
| 1350 | @node Licenses |
| 1351 | @appendix Licenses |
| 1352 | |
| 1353 | @menu |
| 1354 | * GNU Free Documentation License:: License for this document. |
| 1355 | * GNU General Public License:: License for the library. |
| 1356 | * GNU Common C++ Linking Exception:: Library linking exception. |
| 1357 | @end menu |
| 1358 | |
| 1359 | @include fdl.texi |
| 1360 | |
| 1361 | @include gpl.texi |
| 1362 | |
| 1363 | @c ----------------------------------------------------------------------- |
| 1364 | @node GNU Common C++ Linking Exception |
| 1365 | @appendixsec GNU Common C++ Linking Exception |
| 1366 | @cindex GNU Common C++ Linking Exception |
| 1367 | |
| 1368 | As a special exception to the GNU General Public License, permission |
| 1369 | is granted for additional uses of the text contained in its release of |
| 1370 | Common C++. |
| 1371 | |
| 1372 | The exception is that, if you link the Common C++ library with other |
| 1373 | files to produce an executable, this does not by itself cause the |
| 1374 | resulting executable to be covered by the GNU General Public License. |
| 1375 | Your use of that executable is in no way restricted on account of |
| 1376 | linking the Common C++ library code into it. |
| 1377 | |
| 1378 | This exception does not however invalidate any other reasons why the |
| 1379 | executable file might be covered by the GNU General Public License. |
| 1380 | |
| 1381 | This exception applies only to the code released under the name Common |
| 1382 | C++. If you copy code from other releases into a copy of Common C++, |
| 1383 | as the General Public License permits, the exception does not apply to |
| 1384 | the code that you add in this way. To avoid misleading anyone as to |
| 1385 | the status of such modified files, you must delete this exception |
| 1386 | notice from them. |
| 1387 | |
| 1388 | If you write modifications of your own for Common C++, it is your |
| 1389 | choice whether to permit this exception to apply to your |
| 1390 | modifications. If you do not wish that, delete this exception notice. |
| 1391 | |
| 1392 | |
| 1393 | @c ----------------------------------------------------------------------- |
| 1394 | |
| 1395 | @c %** start of end |
| 1396 | |
| 1397 | @node Class and Data Type Index |
| 1398 | @unnumbered Class and Data Type Index |
| 1399 | |
| 1400 | @printindex tp |
| 1401 | |
| 1402 | @node Method and Function Index |
| 1403 | @unnumbered Method and Function Index |
| 1404 | |
| 1405 | @printindex fn |
| 1406 | |
| 1407 | @node Concept Index |
| 1408 | @unnumbered Concept Index |
| 1409 | |
| 1410 | @printindex cp |
| 1411 | |
| 1412 | @bye |
| 1413 | @c %** end of end |