What is Pantheios?
Version 1.0.1-beta208
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).
- Extensibility - the back-end transport can be customised by the user to any conceivable transport, should the several stock back ends prove insufficient for a particular need. The stock back ends include SysLog (UNIX and simulated on Windows), stdio (via
fprintf()), COM Error Object, Windows Console, Windows Debugger, Windows Event Log, and others. - 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 shims c_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 shims c_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.
Pantheios is written in C and C++, and presents a C API along with a C++ Application Layer API.
There is a COM mapping (written in C++, using ATL and STLSoft) called pantheios.COM, which is available separately from the website.
There is a prototype pantheios.NET in use in one of Matthew's commercial projects, but it is some way from being ready for generalisation and release.
The slice structure used by the core API is deliberately binary-compatible with the slices used in the D language, so don't be too surprised to see a pantheios.D sometime in the future.
Pantheios is released under the BSD license, which basically means its free for any use, but you can't claim it's yours.
Pantheios works on with many compilers, is platform independent, and requires only one other library. It also provides Base-64 representation as an extension, using a third-part library, which is not required for the rest of the library to function.
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.
Pantheios is written in standard C/C++, and should be compilable with any modern C/C++ compiler that provides an implementation of the C & C++ standard libraries.
Pantheios has been built and tested with the following compilers:
- Borland C/C++ 5.5.1
- Borland C/C++ 5.6
- Borland C/C++ 5.6.4
- Metrowerks CodeWarrior 8
- Comeau C++ 4.3.3
- Digital Mars 8.50+
- GNU C/C++ 3.2
- GNU C/C++ 3.3
- GNU C/C++ 3.3
- GNU C/C++ 4.0-4.4
- Intel C/C++ 6.0
- Intel C/C++ 7.0
- Intel C/C++ 8.0
- Visual C++ 5.0 (for core and front/back-ends. Some STLSoft string access shims are not supported)
- Visual C++ 6.0
- Visual C++ 7.0
- Visual C++ 7.1
- Visual C++ 8.0
- Visual C++ 9.0
- Visual C++ 10.0
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.
Pantheios is dependent on the STLSoft libraries, version 1.9.102, or later.
STLSoft provides the following important features:
- Compiler feature discrimination, standard library feature discrimination, memory utility classes, multi-threading classes and functions, various STL extension algorithms and iterator adaptors.
- The application layer uses the string access shims defined by the STLSoft main project and several sub-projects to effect the genericity, 100% type-safety and zero-overhead when not logging.
- The core completely avoids memory allocation when the total extent of a logged message is less than 2048 bytes by using the highly efficient
stlsoft::auto_buffer component. - Several stock back ends use STLSoft components for their implementation.
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.
