Part I. Core classes

Introduction to core classes

To access the classes and templates described in this part, the application must be linked with the -lcxx option.

Library namespace

All classes and templates in this library are defined in the x namespace. This documentation includes doxygen-generated reference pages for each documented class. Currently, the class documentation does not always explicitly note the x namespace. When reading the separate class documentation pages, mentally prepend the x namespace to all documented classes that do not have one. Example: x::obj, x::ref, and so on.

Patches to the voluminous header files, noting the explicit namespace reference, are welcome. See the existing header files for an example (the namespace is referenced by a macro that's handled by pre-processing, prior to documentation generation).

Using LIBCXX to build C++ applications

This manual is a work in progress. Everything is documented, perhaps not as thorough as it should be, but it's documented. You're reading LIBCXX's manual that's organized as a loosely-structured tutorial. The tutorial contains additional links to doxygen-generated class references, where more information can be found.

LIBCXX uses autotools. If you're not familiar with automake, autoconf, and libtool, follow these links, and start there. After installing the library and the header files add the LIBCXX_INIT macro in order to set up the environment to develop and build applications with LIBCXX:


application_SOURCES=source1.C source2.C

The LIBCXX_INIT configure script macro overrides CC and CXX, and sets them to the compiler that built LIBCXX. The same compiler must be used to build any code that links with it. The macro also adds any additional compiler flags (currently -std=c++0x -fno-omit-frame-pointer). The -export-dynamic compiler flag is also recommended, but is not required.

LIBCXX_INIT defines the LIBCXX_AM automake macro which pulls in Makefile used in Chapter 23, Message dispatching-based thread design pattern and Chapter 18, Parsing command line options.

See examples/managedsingleton subdirectory in LIBCXX's source code tarball. This is an example of building C++ applications with LIBCXX, complete with a basic autotools configuration:

$ aclocal
$ autoreconf -i
[ output not shown]
$ ./configure
[ output not shown]
$ make
make  all-am
make[1]: Entering directory `/home/mrsam/src/ng/examples/managedsingleton'
g++ -DHAVE_CONFIG_H -I.     -g -O2 -fno-omit-frame-pointer -std=c++0x -I/usr/inc
lude/p11-kit-1   -MT managedsingleton.o -MD -MP -MF .deps/managedsingleton.Tpo -
c -o managedsingleton.o managedsingleton.C
mv -f .deps/managedsingleton.Tpo .deps/managedsingleton.Po
/bin/sh ./libtool --tag=CXX   --mode=link g++  -g -O2 -fno-omit-frame-pointer -s
td=c++0x -I/usr/include/p11-kit-1     -o managedsingleton managedsingleton.o -lcxx
libtool: link: g++ -g -O2 -fno-omit-frame-pointer -std=c++0x -I/usr/include/p11-
kit-1 -o managedsingleton managedsingleton.o  /usr/lib64/ -lpthread -lrt -lpcre

This is the example code from Chapter 26, Application singleton design pattern.

Using LIBCXX to build C++ applications without autotools

This is certainly possible, but the autotools support in LIBCXX takes care of many ancillary details. Here's an explanation of what needs to be done by hand, and what the automake macros do:

  • Link with -lcxx; -lcxxtls gets the GnuTLS-based classes. Also, link with -lpthread, -lrt, and -lpcre (for Linux).

  • LIBCXX_INIT sets the C compiler to the same one that was used to build LIBCXX and the correct options (-std=c++0x -fno-omit-frame-pointer).

  • The OPTIONS_GEN macro runs an XSLT processor on the optgen.xsl stylesheet in pkgdatadir, which is usually /usr/share/libcxx or /usr/local/share/libcxx.

  • The MSGDISPATCHER_GEN macro runs an XSLT processor on the msgdispatcher.xsl stylesheet in pkgdatadir, which is usually /usr/share/libcxx or /usr/local/share/libcxx.

    The second parameter to the MSGDISPATCHER_GEN macro is the mode stylesheet parameter. Invoking MSGDISPATCHER_GEN with a list of modes runs the stylesheet once, for each mode. The macro forms the output filename, as described in Chapter 23, Message dispatching-based thread design pattern by including the mode name in the name of the outputfile that the xsltproc's output goes to.

    name=values from the third parameter to MSGDISPATCHER are stylesheet parameters. dispatch=public sets the dispatch parameter to public (--stringparam dispatch public parameters to xsltproc, for example).


1. Throwing exceptions
Throwing customized exceptions
2. Reference-counted objects
Comparison with other implementations of reference-counted objects
Pointers and references
x::const_ref and x::const_ptr
create() - create reference-counted objects
Range-based iteration on reference-counted objects
Specifying a custom base
Multiple inheritance and casting
Creating an x::ref or an x::ptr from this
Multiple inheritance with reference-counted objects
Private inheritance of reference-counted objects
Weak pointers
Destructor callbacks and mcguffins
Using a functor as a destructor callback
A basic destructor callback
A destructor callback guard
Revocable destructor callbacks
Invoking a destructor callback when any of several objects gets destroyed
Waiting for a cascading destructor
Weak containers
Circular strong references
3. Implementing iterators with reference-counted objects
Implementing a reference-counted object-based iterator
Accessing the underlying x::ref and x::ptr
Base class for reference-counted output iterators
Reference-counted output iterator tuples
4. Application properties
5. Application logging
6. File descriptor and stream objects
Other miscellaneous file-related function
Linux epoll() implementation
Linux eventfd() implementation
Linux timerfd() implementation
The file descriptor transport superclass
Lightweight input and output file descriptor iterators
Automatic file descriptor timeouts
Automatic file descriptor terminator
Read limits
Using sockets
File attributes
Stream objects
String stream objects
File descriptor listeners and servers
POSIX shared memory segments, and memory-mapped files
7. Signals and signal file descriptors
Blocking signals
Signal file descriptors
Signal handlers
8. Filename pattern globbing
9. Perl-compatible regular expressions
10. Network interfaces
Network interface addresses
11. IO filter classes
12. iconv(3) IO filter
13. Reading directory contents
Reading the contents of a single directory
Reading the contents of a directory hierarchy
Miscellaneous functions
14. Singleton objects
15. Threads and related objects
Mutex-protected objects
Readers/writer mutex pairs
Mutex objects
Condition variable objects
Readers-writer lock objects
Execution threads
Checking the results of an execution thread
Arguments to run() methods must be copy-constructible
Optional superclasses of thread-executing objects
Running a lambda inside a separate thread
Cleanup thread
Stick a fork() in it: you're done
Thread logging
Timer threads
Using mcguffins to cancel recurring tasks
Weak local thread objects
Local thread singleton objects
Thread worker pools
A simple worker pool thread
Notifying an event file descriptor
Notifying an event queue
Thread-safe semaphores
16. Forking other processes
Redirecting file descriptors
17. Locale objects
Character type functions using input or output streams
Wide/narrow character conversion
Wide/narrow character conversion using input iterators
Wide/narrow character conversion using output iterators
Message catalogs
Single and plural forms
18. Parsing command line options
Option parser generator
Specifying option types
Mutually exclusive options
Combining numeric options
Default option values
Option groups
Defining an option parsing subclass
Localizing option strings
Using gettextmsg() with localizable strings
GNU make macros
Using GNU make macros with automake
19. Event queues
20. Event factories
21. Event callbacks
Using the same callback objects for multiple callbacks
22. Very ImPortant object design pattern
Creating a very important object
Very important object notification callbacks
Read and write locks
An update lock
A registration handler lock
Opportunistic locking
Avoiding and debugging deadlocks
Somewhat-ImPortant object design pattern
23. Message dispatching-based thread design pattern
Sending messages to the thread
The message dispatching thread loop
Stopping the execution thread
Generic stoppable interface
Using a stylesheet to generate a thread-based message dispatching framework
Stylesheet parameters
XML definitions
Optional message class constructor and serialization function
Generating doxygen documentation
GNU make macros
Using GNU make macros with automake
Using mcguffins with a message dispatching-based thread
24. A pool of locks that use event file descriptors
Lock pool starvation option
Read-write lock pools
Mutually-exclusive lock pools
25. Object serialization
Use cases
Supported objects
Serializing an object
Serializing enumerated values
Serializing a beginning/ending iterator range
Calculating the size of the serialized object
Convenience functions for serializing a single object
Deserializing an object
Maximum sequence sizes
Deserializing any one of several objects
Convenience functions for deserializing a single object
Serializing classes
Serialization of object references
Deserialization traits class
Serializing file descriptors
26. Application singleton design pattern
Singleton startup and termination
Signals in singleton processes
Peer validation
Systemwide application singletons
Managed application singletons
Notes on thread concurrency with managed singletons
Example of a managed application singleton
Implementing a managed application singleton as a message dispatching-based thread
27. Date and time intervals
Loading timezone files
Local time
Generic interval parser
28. Format time using strftime
29. Unique identifiers
30. Base64 encoding and decoding
31. Quoted-printable encoding and decoding
32. User, group, and port lookups
33. URIs
Using international domain names
34. Headers
35. Hierarchical container template
Reader locks
Writer locks
Key iterators
Output of the example program