Pantheios

Pantheios C/C++ Logging API Library

Stable release	1.0.1 (beta 214) / August 7, 2012
Written in	C/C++
Operating system	MS-Windows, Unix, Mac OS X
Type	Logging library
License	BSD-form license
Website	http://www.pantheios.org/

Pantheios is an open source C/C++ logging API library, whose design focus is performance, robustness and transparency. It claims 100% type-safety, and high efficiency.

Pantheios was forked from a proprietary logging architecture of Synesis Software in 2005, and is now completely free for use in both commercial and non-commercial activities, being licensed under the BSD license. It is platform-independent, working on UNIX (Linux, Solaris, FreeBSD), Mac OS X, and Windows (x86 and x64). It is compiler-independent, and is known to work with Borland, Metrowerks CodeWarrior, Comeau, Digital Mars, GCC, Intel, Sun Studio and Microsoft Visual C++ compilers.

Pantheios provides both C and C++ APIs. The C++ API is infinitely extensible to allowing logging of arbitrary types.

The API is designed to work with any logging transport (aka "back-end"), including existing logging libraries such as ACE and log4cxx.

Design Principles

The principles underpinning Pantheios are:

• the logging subsystem must always be available, including for use by other subsystems that may themselves act before (or after) main()
• the logging subsystem must be completely robust, and should never be the cause of system failure
• the logging subsystem must have extremely low cost when logging is switched off, otherwise users will make decisions about what logging information is important at compile-time, rather than at runtime

Architecture

The Pantheios architecture is divided into four functional areas:

• The Application Layer is a collection of inserter classes and function template suites that are used to define logging statements, and adapt the statement elements into a form to be passed to the core.
• The Core controls initialization of the library, and processed statement elements received from the application layer into a form to be passed to the back-end.
• The Front-end defines the process identity and determines whether each logging statement should be processed (by the core) and emitted (to the back-end).
• The Back-end emits the prepared statement via a specific output mechanism

Division of responsibilities

Use and customization of the library is divided between the library (and its authors) and users as follows:

• The application layer may be extended, by definition of new inserter classes, or by adaptation of application types, by the user, but existing components do not usually need to be changed.
• The core never needs to be modified by the user.
• A number of "stock" front-ends and back-ends are provided in the Pantheios distribution, but for non-trivial requirements the user is expected to replace front-end and/or back-end(s). This supports a primary design parameter of the library: that Pantheios may be layered over existing logging libraries, such as ACE, log4cplus, log4cpp, log4cxx, simply, robustly and in a manner that preserves Pantheios' high efficiency.

Hello, World

Applying Pantheios to the classic Hello, World program gives the following examples:

1. Single argument of literal string

#include <pantheios/pantheios.hpp>

int main(int argc, char** argv)
{
  pantheios::log_NOTICE("Hello world");

  return EXIT_SUCCESS;
}

Notable aspects are:

• inclusion of the main Pantheios C++ header, pantheios/pantheios.hpp
• use of the pantheios::log_NOTICE() application layer function, which causes the statement to be emitted at the PANTHEIOS_SEV_NOTICE (=== 5, aka Syslog's LOG_NOTICE) severity level
• passing the literal C-style string "Hello world!" to pantheios::log_NOTICE()

2. Multiple arguments; different string types

#include <pantheios/pantheios.hpp>
#include <string>

int main(int argc, char** argv)
{
  const char  hello[] = "hello";
  std::string world("world");

  pantheios::log_NOTICE(hello, " ", world);

  return EXIT_SUCCESS;
}

Notable aspects are:

• multiple arguments may be passed to the log statements, up to 32 in the default distribution; more can be achieved by re-running the code-generation script that accompanies the distribution
• the arguments can be of heterogeneous string types; Pantheios uses shims^[1][2] to interpret the argument types and render them as strings

3. Logging an exception

#include <pantheios/pantheios.hpp>
#include <string>
#include <vector>

void say_hello()
{
  std::vector<short>   very_big(1000000000);

  throw std::runtime_error("hello world!");
}

int main(int argc, char** argv)
{
  try
  {
    say_hello();

    return EXIT_SUCCESS;
  }
  catch(std::bad_alloc&)
  {
    pantheios::logputs(PANTHEIOS_LOG_ALERT, "out of memory");
  }
  catch(std::exception& x)
  {
    pantheios::log_ERROR("Exception: ", x);
  }

  return EXIT_FAILURE;
}

Notable aspects are:

• use of the pantheios::log_ERROR() application layer function, which causes the statement to be emitted at the PANTHEIOS_SEV_ERROR (=== 3, aka Syslog's LOG_ERR) severity level
• use of pantheios::logputs() application layer function, which passes a single C-style string directly through to the logging infrastructure and is suitable for logging low-memory conditions, at the PANTHEIOS_SEV_ALERT (=== 1, aka Syslog's LOG_ALERT) severity level
• passing a reference to std::exception directly to the API; Pantheios uses shims to interpret the argument types and render them as strings

Dependencies

Pantheios is dependent on several open-source libraries:

• STLSoft provides compiler and platform discrimination, along with a number of low-level, high-efficiency components
• b64 is a Base-64 encoding library, and is used by the pantheios::b64 inserter class. It is bundled with the Pantheios distribution
• shwild is a pattern matching library, and is used by the automated testing facilities of the library. It is bundled with the Pantheios distribution
• xTests is a unit-testing library, and is used by the automated testing facilities of the library. It is bundled with the Pantheios distribution

Criticisms

Constrained by the design principles, Pantheios has attracted some criticisms, particularly in regard to its packaging and the complexity of its build: it builds many 10s of object libraries for a given target operating-system/compiler.

Other languages

Currently, the Pantheios developers are concerned primarily with C and C++. However, a COM project, Pantheios.COM, is also available from the project website. Furthermore, there are discussions about a D version, and other languages are under discussion.

References

1. Wilson, Matthew (2004). Imperfect C++. Addison-Wesley. ISBN 0-321-22877-4.
2. Wilson, Matthew (2007). Extended STL. Addison-Wesley. ISBN 0-321-30550-7.

Further reading

• Using Callback Back-ends with the Pantheios Logging API Library by Matthew Wilson on Code Project
• An Introduction to Pantheios Back-ends, Part 1: The Back-end API by Matthew Wilson on Code Project
• Adding Logging to C Programs with the Pantheios C API by Matthew Wilson on Code Project

External links

• Pantheios Official Website
• STLSoft Official Website
• STLSoft Musings Blog
• STLSoft newsgroup