Application-Layer
The Pantheios application layer consists of:
-
One suite of (32) log() functions,
catering for between 1 and 32 parameters.
- Eight suites of 32 severity-specific functions
(log_DEBUG(),
log_INFORMATIONAL(),
log_NOTICE(),
log_WARNING(),
log_ERROR(),
log_CRITICAL(),
log_ALERT()
and
log_EMERGENCY(). Each of these is
equivalent to a call to the requisite
log() with an explicit severity
level.)
-
Two inserter classes for handling numeric types:
integer,
and
real.
-
One inserter class for handling numeric and pointer:
pointer.
-
One inserter class for representing untyped areas of memory:
blob.
(Note: there's also an extension class,
b64, that represents untyped areas
of memory as Base-64. This requires the headers and libraries
from the
b64
library, which is not part of the Pantheios distribution.)
With these functions and inserter classes diagnostic logging statements can be
written into application code in a simple and succinct manner, as
shown in the follow examples:
- Log an exception (with the ERROR severity):
. . .
}
catch(std::exception &x)
{
pantheios::log_ERROR("Exception encountered: ", x);
}
- Log the parameters to a function call (with the INFORMATIONAL severity):
void func(std::string const& s1, char const* s2, struct tm const* t)
{
pantheios::log_INFORMATIONAL("func(", s1, ", ", s2, ", ", t, ")");
. . .
}
- Log a mix of types (with a custom severity level):
int i;
float f;
HWND hwnd;
GUID guid;
pantheios::log_NOTICE("int=", pantheios::integer(i)
, " float=", pantheios::real(f)
, " HWND=", hwnd
, " GUID=", guid);
The application layer is entirely header-only, accessed via the
pantheios/pantheios.hpp and, if the
inserter classes are required,
pantheios/inserters.hpp.
#include <pantheios/pantheios.hpp> // Pantheios log and log_XXX functions
#include <pantheios/inserters.hpp> // Pantheios inserter classes
Front-end
The Pantheios front-end is a library of four functions that
together provide the process identity used in the log statements
and determine, at runtime, whether a given severity level is to
be logged:
PANTHEIOS_CALL(int) pantheios_fe_init( int reserved
, void** ptoken);
PANTHEIOS_CALL(void) pantheios_fe_uninit( void* token);
PANTHEIOS_CALL(char const*) pantheios_fe_processIdentity( void* token);
PANTHEIOS_CALL(int) pantheios_fe_isSeverityLogged(void* token
, int severity
, int backEndId);
pantheios_fe_init(),
pantheios_fe_uninit() and
pantheios_fe_processIdentity() are invoked
at most once, during library initialisation. (See the documentation included
with the library for more details.)
pantheios_fe_isSeverityLogged() is invoked each
time an application layer log statement is invoked, and determines whether
the statement is to be emitted to the back end
based on the statement's severity level. In this way, the Pantheios core
may be married to any application scheme for filtering log statements based
on severity level.
The front-end is selected at link time. Pantheios comes with one stock
front-end called fe.simple.
Back-end
The Pantheios back-end is a library of three functions that together
provide the back-end transport:
PANTHEIOS_CALL(int) pantheios_be_init( char const* processIdentity
, int reserved
, void** ptoken);
PANTHEIOS_CALL(void) pantheios_be_uninit( void* token);
PANTHEIOS_CALL(int) pantheios_be_logEntry(void* feToken
, void *beToken
, int severity
, char const* entry
, size_t cchEntry);
pantheios_be_init() and
pantheios_be_uninit() are invoked
at most once, during library initialisation. (See the documentation included
with the library for more details.)
pantheios_be_logEntry() is invoked each
time an application layer log statement is invoked, as long as
pantheios_fe_isSeverityLogged() returned
non-zero.
The back-end is selected at link time. Pantheios comes with several
stock back-ends:
- be.ACE
- output is via the ACE diagnostic logging infrastructure.
- be.COMErrorObject
- output is written to the COM Error Object.
- be.fprintf
- output is to the console via fprintf().
- be.null
- output is stubbed (the Null Object pattern).
- be.syslog
- output is via the Syslog protocol, using the native UNIX SysLog API.
- be.WindowsConsole
- output is via the Windows console, with severity-dependent statement colouring.
- be.WindowsDebugger
- output is via the Windows debugger.
- be.WindowsSyslog
- output is via the SysLog protocol, using a
custom implementation. This is a useful library independent of Pantheios.
- be.WindowsEventLog
- output is via the Windows Event Log.
There is also a back-end, be.lrsplit, that implements the
Composite Pattern to split output into local and remote
streams using any of the stock (or custom) back-ends.