Pantheios Application Layer API

---

Detailed Description

The Pantheios application layer library is the suite of C++ function templates that provide a simple, generic, 100% type-safe interface to the diagnostic logging functionality provided by the Pantheios core.

The application layer has but one responsibility:

• Tunnel the log statement elements, in the form of parameters to one of the function templates, through to the core, in a degenerate form (as instances of pantheios::pan_slice_t).

This responsibility is carried out using string access shims, a powerful generalising mechanism.

The core consists of the following;

• One suite of (32) pantheios::log() functions, catering for between 1 and 32 parameters.
• Eight suites of 32 severity-specific functions (pantheios::log_DEBUG(), pantheios::log_INFORMATIONAL(), pantheios::log_NOTICE(), pantheios::log_WARNING(), pantheios::log_ERROR(), pantheios::log_CRITICAL(), pantheios::log_ALERT() and pantheios::log_EMERGENCY(). Each of these is equivalent to a call to the requisite pantheios::log() with an explicit severity level.)
• Two inserter classes for handling numeric types:
  • integer - for integers
  • real - for floating-point types
• One inserter class for handling characters:
  • character
• One inserter class for handling pointers:
  • pointer
• One inserter class for representing untyped areas of memory:
  • blob

Note:

There's also an additional inserter 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:

1. Log an exception (with the ERROR severity):

    . . .
  }
  catch(std::exception &x)
  {
    pantheios::log_ERROR("Exception encountered: ", x);
  }

2. 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, ")");
    . . .
  }

3. 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 primary header file pantheios/pantheios.hpp:

  #include <pantheios/pantheios.hpp>  // Pantheios log and log_XXX functions

The inserter classes are accessed via their respective header files:

  #include <pantheios/inserters/blob.hpp>      // for pantheios::blob
  #include <pantheios/inserters/character.hpp> // for pantheios::character
  #include <pantheios/inserters/integer.hpp>   // for pantheios::integer
  #include <pantheios/inserters/pointer.hpp>   // for pantheios::pointer
  #include <pantheios/inserters/real.hpp>      // for pantheios::real

or you can just include all the above with the header file pantheios/inserters.hpp:

  #include <pantheios/inserters.hpp>  // Pantheios inserter classes

There are several full examples provided in the distribution. Click on the Examples button at the top of the page.

The C++ function templates - supporting between 1 and 32 parameters (more may be easily effected by regenerating the headers from the Ruby script provided with the library) - apply the STLSoft string access shims c_str_data_a() and c_str_len_a() to each parameter, to form instances of the pantheios::pan_slice_t structure, which are then passed down to the Pantheios Core API function pantheios_log_n(), wherein they are formed into a single log entry before being passed to the back-end (see Pantheios Back-end API) for transmission.

The application layer accepts any type for which an STLSoft string access shim is defined. Since the file pantheios/pantheios.hpp includes the two standard STLSoft header files stlsoft/string_access.hpp and stlsoft/exception_string_access.hpp, c-style strings, instances of std::string and standard exceptions are all covered. In addition, string access shims for the Pantheios types pantheios::pan_slice_t, pantheios::integer, pantheios::pointer and pantheios::real are also defined within the stlsoft namespace.

Other classes from the STLSoft libraries (and some other libraries, such as Open-RJ and recls) that may be represented as strings always define these string access shims in the stlsoft namespace, so you can simply pass them to Pantheios, and it will know what to do with them.

To make your own custom types compatible with the Pantheios Application Layer API you need only define stlsoft::c_str_data_a() and stlsoft::c_str_len_a(), e.g.

  class MyClass;

  char const*  c_str_data_a(MyClass const& mc);
  size_t       c_str_len_a(MyClass const& mc);

You will know if your type does not have a suitable string access shim defined because the compiler will complain that one of several shim functions are not compatible with a given argument to a Pantheios diagnostic logging function. Although these compiler messages tend to be quite verbose, and not a little unfriendly, they almost always boil down to the same problem.

Note:

If your class does not have a suitable or straightforward conversion to a c-style string representation, you may need to consider returning a shim string. There's an example showing a variety of compatibility mechanisms included in the distribution.

Modules
	Inserters
	String inserters for fundamental types.
	Generated N-ary Application-Layer Functions
	Auto-generated functions that constitute the Type Tunnel, which acts as the bridge between the Pantheios Core API and the Pantheios Application Layer API.

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