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 library. Some templates also require linking with the -lcourier-unicode library.

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

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 to your 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++20 -fno-omit-frame-pointer -pthread). The -export-dynamic compiler flag is also recommended, but is not required.

LIBCXX_INIT defines the LIBCXX_AM automake macro which pulls in Makefile macros 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 -std=c++20 -fno-omit-frame-pointer -pthread -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 -std=c++20 -fno-omit-frame-pointer -pthread -I/usr/include/p11-kit-1     -o managedsingleton managedsingleton.o -lcxx

libtool: link: g++ -g -O2 -fno-omit-frame-pointer -std=c++20 -fno-omit-frame-pointer -pthread -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:

  • Use pkgconf/pkg-config to extract the relevant configuration settings:

    • --cflags and --libs compiler flags for building and linking C++ source.

    • The --variable=pkgdatadir option returns the directory with makefile fragments for the options parser generator, thread-based message dispatcher generator, and other supporting tools.

    • The --variable=CXX and --variable=CC options returns the compiler invocation commands.

  • Link with -lcxx; -lcxxtls gets the GnuTLS-based classes. Also, link with -lrt, and -lpcre. Most Linux distributions also require the -pthread compiler and link flag even if without direct usage of thread-related methods and classes like x::run(), or x::start_threadmsgdispatcher. This is because the library has internal references to them that require runtime resolution.


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
Restricting overload resolution
Creating an x::ref or an x::ptr from this
Second phase constructor
Using deduction guides with an x::ref or an x::ptr
Multiple inheritance with reference-counted objects
Private inheritance of reference-counted objects
Comparing x::refs and x::ptrs
Weak pointers
Reference and pointer traits
Constructing a collection of references
Destructor callbacks and mcguffins
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
Mcguffin 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
Linux Inotify 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
Transferrable mutex locks
Mutex-protected references
Mutex objects
Condition variable objects
Shared 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 semaphore queue
A fixed semaphore
16. Forking other processes
Redirecting file descriptors
17. Locale objects
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. Very ImPortant object design pattern
Creating a very important object
Read and write locks
An update lock
A registration handler lock
Opportunistic locking
Optional template parameters
Avoiding deadlocks
Somewhat-ImPortant object design pattern
22. Derived values
23. Message dispatching-based thread design pattern
Sending messages to the thread
Starting the message-dispatching execution thread
The message queue
Using the message queue
Auxiliary message queues
Stopping the execution thread
Generic stoppable interface
Using a stylesheet to generate a thread-based message dispatching framework
XML definitions
Generating doxygen documentation
GNU make macros
Using GNU make macros with automake
24. A pool of locks that use event file descriptors
Lock pool starvation option
Shared 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