Pantheios

Pantheios C/C++ Logging API Library

Stable release|

1.0.1 (beta 214) / August 7, 2012; 9 years ago (2012-08-07)

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 (a.k.a. "back-end"), including existing logging libraries such as ACE and log4cxx.

## Contents

* 1 Design Principles
* 2 Architecture
* 2.1 Division of responsibilities
* 3 Hello, World
* 3.1 1\. Single argument of literal string
* 3.2 2\. Multiple arguments; different string types
* 3.3 3\. Logging an exception
* 4 Dependencies
* 5 Criticisms
* 6 Other languages
* 7 References
* 8 Further reading
* 9 External links

## 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, a.k.a. 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, a.k.a. 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, a.k.a. 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

0.00

(0 votes)

|

Retrieved from "https://handwiki.org/wiki/index.php?title=Pantheios&oldid=2315048"