Application Layer

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
be.COMErrorObject
be.fprintf

fprintf()

be.null

Null Object

be.syslog
be.WindowsConsole
be.WindowsDebugger
be.WindowsSyslog
be.WindowsEventLog

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.


pantheios Library documentation © Matthew Wilson & Synesis Software, 2006-2011