Pantheios is a diagnostic logging API library for C and C++. Its outstanding features include:

Atomicity - all parts of a statement are emitted (or not) to the back-end transports in a single action.

Efficiency - the length of each element in a statement is determined at most once; the contents of each element in a statement is copied at most once; memory is allocated for the prepared statement at most once (and even then only if the total statement length exceeds 2047 characters).

Filtered - statements are filtered based on a 32-bit severity level, incorporating, but not limited to, the SysLog severity levels. Filtering is the responsibility of the front-end component that is consulted whether a statement of a given severity level should be emitted to a given back-end transport.

Genericity - log statement elements may be of arbitrary type, required only that functions of the string access shimsc_str_len_a and c_str_data_a (in the stlsoft namespace) are accessible to the compiler in a given compilation unit. By default, Pantheios includes the requisite header files for common string types, meaning that types such as char*, char const*, char[], std::string, std::exception (and derived types), struct tm, and so on are already compatible. Further, on a platform-specific basis other types are automatically included and compatible, e.g. on Windows this includes the types HWND, CWindow, VARIANT, FILETIME, SYSTEMTIME, and more.

100% type-safety - because the types of the statement elements must be compatible with the string access shimsc_str_len_a and c_str_data_a, there is no way to subvert type-safety and introduce an element that will break the processing of the statement.

But above all else it adheres to the important principle of C programming that:

You don't pay for what you don't use. If a statement at a given severity level is not to be emitted, no conversions, no concatenations, no memory allocation nor any other expensive operations are carried out. Because Pantheios uses Type Tunneling, the only cost to any particular log statement when its contents are not to be emitted are (i) the test to determine whether to emit (one call to pantheios::isSeverityLogged()) and (ii) the cost in passing the given number of argument references (equivalent to copying a pointer onto the stack). In practice, this is negligible.

Although some of the stock back ends are platform-specific, Pantheios itself is a platform-independent library. It has been tested and used on both UNIX and Windows - in principle, it should work on any operating system for which a (reasonably modern) C++ compiler exists.

If you wish to use Pantheios with a compiler not listed here, you may find the STLSoft header file will issue a #error informing you that your chosen compiler is not supported. This can be overriden by defining the pre-processor symbol _STLSOFT_FORCE_ANY_COMPILER. If you do that, your compiler will be expected to be pretty standards compliant (though nothing that's particularly out-of-this-world, such as export). If you run into any issues with using Pantheios/STLSoft with such a compiler, we'd be happy to hear from you on the STLSoft newsgroup.

Because STLSoft is 100% header-only, there is no need to build anything in order to use STLSoft with Pantheios. Simply define the STLSOFT environment variable, as described in the STLSoft distribution.

An additional component in the Pantheios distribution is the b64 inserter class, which allows binary regions to be expressed in Base-64 form. This component requires the b64 library, which is bundled with the Pantheios distribution.

Pantheios is written by Matthew Wilson, with contributions, opinions and advice by Garth Lancaster.

The Shims concept and the Type Tunnel pattern are both fancies of Matthew's imagination, and are described in detail in Matthew's forthcoming book Breaking Up The Monolith. Pantheios is the best example so far of the power of both.