libUTL++ Documentation

1. Introduction

libUTL++ is a home for code that I've reused across C++ projects over the years.

Here's a brief (incomplete) overview of what's in the library:

• utl::Object provides a basis for commonly useful functionality such as:
  • copying, cloning, moving
  • comparison
  • serialization
  • isA() (more readable than equivalent dynamic_cast<>)
  • super:: (unfortunately missing from C++)
• streams framework:
  • utl::Stream is a base class for I/O streams
  • utl::BufferedStream provides buffering for a utl::Stream
  • utl::FileStream, utl::BufferedFileStream for file I/O
  • utl::MemStream for streaming to/from a memory buffer
  • utl::Encoder is a base class for encoders (and decoders)
  • utl::Base64encoder encodes to/from base64
  • utl::CRC32 and utl::MD5 non-secure hashes
  • utl::SHA256 is a secure hash (as far as we know)
• containers, iterators, and algorithms:
  • concurrent queues: utl::ConcurrentQueue, utl::RingBuffer
  • utl::Collection is an abstract base for containers
  • utl::SortedCollection is an abstract base for sortable containers
  • sorted/sortable containers: utl::Array, utl::Deque, utl::List, utl::RBtree, utl::SkipList
  • unsorted containers: utl::Hashtable, utl::Heap
  • key->value map for strings: utl::StringVars
  • iterators are STL-compatible (useable with range-based for and <algorithms>)
  • various iterator-based algorithms for searching, sorting, comparing, etc. (many of these only work with utl::FwdIt-based iterators)
• data compression, including:
  • adaptive arithmetic encoding (utl::ArithmeticEncoder)
  • Burrows-Wheeler Transform (utl::BWTencoder)
  • adaptive Huffman encoding (utl::HuffmanEncoder)
  • Lempel-Ziv (utl::LZencoder)
  • RLE (utl::RLencoder)
• networking:
  • utl::NetServer and utl::NetServerClient provide a basis for a
    networked server that serves each client in a separate thread
  • utl::FastCGIserver specializes utl::NetServer to provide a basis for
    a FastCGI responder
  • utl::TCPsocket, utl::BufferedTCPsocket, utl::TCPserverSocket,
    utl::SSLsocket, utl::BufferedSSLsocket,
    utl::InetHostAddress, utl::InetHostname
  • utl::HttpRequest, utl::HttpResponse, utl::URI
  • utl::ReCaptcha for verifying ReCaptcha responses (protocol version 2)
• filesystem interaction: utl::Pathname, utl::File, utl::Directory, utl::Symlink, etc.
• string processing: utl::String, utl::BoyerMooreSearch, utl::Regex, utl::BBcodeParser, utl::RDparser, utl::Tokenizer
• date/time processing: utl::Time, utl::Duration, utl::TimeSpan
• a simple 64-bit decimal type: utl::Decimal
• threads and synchronization:
  • utl::Thread provides basic threads support (spawning, canceling, joining)
  • synchronization: utl::RWlock, utl::RWlockGuard, utl::RWlockLF, utl::RWlockLFguard,
    utl::Mutex, utl::MutexGuard, utl::Semaphore, utl::ConditionVar
• code optimization helpers:
  • utl::clobber(), utl::escape(): for microbenchmarking
  • likely(), unlikely(): optimize conditionals in performance-critical code
  • utl::PointerIntPair: store an integer value in the unused least significant bits of a pointer-like value
    (based on a talk by Chandler Carruth)
• declarative control flow: SCOPE_EXIT, SCOPE_SUCCESS, SCOPE_FAIL
  (based on a talk by Andrei Alexandrescu)
• a few other helpful functions such as:
  • utl::arrayGrow(): grow an allocation
  • utl::cast(): safely cast an object to a utl::Object-derived type (preserves const, also works with pointers)
  • utl::nextPow2(): find the smallest power of 2 >= some value
  • utl::nextMultipleOfPow2(): find the smallest multiple of a power of 2 >= some value
  • utl::reverseBytes(): reverse byte ordering of 16-, 32-, or 64-bit values

2. License

libUTL++ is licensed under the GNU GPL. Make sure you read and understand the license, because it describes your rights in connection with the use and redistribution of this software.

libUTL++ also bundles randutils.hpp by Melissa E. O'Neill, which she has shared under the MIT License. randutils "makes good seeding easier, and makes using RNGs easy while retaining all the power". In my own words: Melissa's work builds on top of the standard library's RNG facilities to provide easy access to good RNG. The STL's RNG facilities only seem "over-engineered" when there is no convenient wrapper for them. Also, std::random_device can't be depended on to provide a good seed, even though it may seem at first glance to be suitable for that purpose. I hope to see randutils (or something much like it) adopted into the standard library in the future.

A few links for randutils:

• randutils.hpp on GitHub
• "Ease of Use without Loss of Power"
• RandUtils.h (a short wrapper with a workaround for targets without std::this_thread)
• randutils.hpp (clang-formatted, and I commented out 2 unused variables)

3. Supported Platforms

Currently Linux and Windows/MinGW amd64 targets are supported, as these are the platforms I've targeted in my projects. The library should also work for those systems on x86 (32-bit), but I haven't been testing that myself lately. Not many people care about 32-bit anymore.

4. Building libUTL++

4.1 Required Software

You will need the following packages to build the library:

• GNU make
• GNU binutils
• GNU g++
• GNU libstdc++6
• Zsh
• Doxygen
• Graphviz

You need these installed when building for Linux:

• jemalloc
• OpenSSL

4.2 MinGW-w64 Build Environment

The MinGW-w64 project has made it easy to cross-compile for Windows on the Linux platform. The included build configuration for MinGW-w64 assumes the cross-targeted binutils & g++ compiler are accessible in the system PATH and named with the prefix x86_64-w64-mingw32-. For example, on my Debian system I installed the package g++-mingw-w64, and the MinGW-targeted g++ is named x86_64-w64-mingw32-g++.

4.3 Build Procedure

First, unpack the sources and change into the libUTL++ source root:

% tar xzvf libutl-1.1.x.tar.gz    # unpack sources
% cd libutl-1.1.x                 # change into source root directory

Next, if you're building on a system other than Linux (such as MinGW), you have to configure the build system for that target by using the config shell script located in the makefiles directory:

% cd makefiles                    # change into makefiles directory
% ./config mingw                  # configure build system for MinGW target
% cd ..                           # change back to source root

Then build and install libUTL++:

% make install-dist

You can use INST_ROOT to override the installation root. For example:

% make INST_ROOT=/usr/local/ install-dist

The build process may take a few minutes. Several versions of the library will be built, including:

• DEBUG : libutl_g.a, libutl_g.so.1
  [built with -g, enabled runtime assertions and debug new/delete]
• DEBUG_RELEASE : libutl_gr.a, libutl_gr.so.1
  [built with -g, disabled runtime assertions and debug new/delete]
• RELEASE : libutl.a, libutl.so.1
  [built with -Ofast, disabled runtime assertions and debug new/delete]

5. Using libUTL++

To use libUTL++ in your project:

• #include <libutl/libutl.h> near the start of your source files
  (before #include'ing any other header files from libUTL++)
• call utl::init() when your application starts
• call utl::deInit() before your application exits
• link against the appropriate version of the library

If you subclass utl::Application, it will take care of the utl::init() and utl::deInit() calls for you.

To learn the library, the best way to get started is to study the bundled applications and example programs (installed in $INST_ROOT/share/libutl/), as well as the documentation (installed in $INST_ROOT/share/doc/libutl-doc/).

6. Compatibility With Other Libraries

libUTL++ should be able to happily coexist with other libraries:

• C++ symbols are in the utl namespace
• most preprocessor symbols are prefixed with UTL_

One thing to watch for is that in a DEBUG build, libUTL++ overloads the new operator to keep track of active allocations (remembering the source file and line # where they were made). This can be a problem when including some C++ header files. You can solve it this way:

#undef new
#include <some/thing.h>
#include <libutl/gblnew_macros.h>

7. Links

• Summary Page
• Browse and Report Bugs
• Download
• MinGW-w64 Project
• MinGW-w64 Downloads

8. Contact the Author

You can reach me via e-mail: adam@.nosp@m.acms.nosp@m.proje.nosp@m.ct.o.nosp@m.rg

Please contact me if you've found a bug, or if you have any ideas for improving the library.