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 configure.ac in order to set up the environment to develop and build applications with LibCXX:

configure.ac:
LIBCXX_INIT
Makefile.am:
@LIBCXX_AM@

bin_PROGRAMS=application

application_SOURCES=source1.C source2.C
application_LDADD=-lcxx

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 22, Message dispatching-based thread design pattern and Chapter 17, 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/libcxx.so -lpthread -lrt -lpcre

This is the example code from Chapter 25, 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.

Index

1. Throwing exceptions
Throwing customized exceptions
2. Reference-counted objects
Comparison with other implementations of reference-counted objects
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
isa()
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. Singleton objects
14. Threads and related objects
Introduction
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
15. Forking other processes
Redirecting file descriptors
16. Locale objects
Message catalogs
gettextmsg()
Single and plural forms
17. 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
18. Event queues
19. Event factories
20. 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
21. Derived values
22. 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
23. A pool of locks that use event file descriptors
Lock pool starvation option
Shared lock pools
Mutually-exclusive lock pools
24. 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
25. 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
26. Date and time intervals
Loading timezone files
Local time
Generic interval parser
27. Format time using strftime
28. Unique identifiers
29. Base64 encoding and decoding
Encoding
Decoding
30. Quoted-printable encoding and decoding
31. User, group, and port lookups
32. URIs
Using international domain names
33. Headers
34. Hierarchical container template
Locks
Reader locks
Writer locks
Shortcuts
Key iterators
Output of the example program