Pantheios Core API


Detailed Description

The Pantheios core library provides a suite of functions that interact with the application layer, back-end and front-end.

The core has two main responsibilities:

The core consists of the following components:

The core API functions are primarily invoked by the application layer to implement its functionality, but some core elements may also be directly invoked by application code. For example, the core API function pantheios_isSeverityLogged() (or pantheios::isSeverityLogged() for C++ compilation units) may be used to determine whether to logging of a given severity level is enabled before doing any significant amount of log statement preparation.

  if(pantheios::isSeverityLogged(pantheios::debug))
  {
    std::string   stringFormOfSomethingExpensive = . . . //

    pantheios::log_DEBUG("Something expensive: ", stringFormOfSomethingExpensive);
  }

Furthermore, Pantheios logging facilities are available from C client code via the core API directly, via the pantheios_printf() and pantheios_vprintf() functions:

  int   i;
  float f;
  pantheios_printf( PANTHEIOS_SEV_INFORMATIONAL, "int=%d, float=%g"
                  , i, f);

However, it should be noted that the C functions in the core API do not offer either the type-safety or the genericity of the application layer, and so should be eschewed in C++ compilation code.


Modules

 Generated N-ary Core 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.

Classes

struct  pantheios::pan_slice_t
 String slice used by the Pantheios Application Layer API to communicate with the Pantheios Core API. More...

Enumerations

enum  pantheios::pan_severity_t {
  pantheios::PANTHEIOS_SEV_EMERGENCY = 0,
  pantheios::PANTHEIOS_SEV_ALERT = 1,
  pantheios::PANTHEIOS_SEV_CRITICAL = 2,
  pantheios::PANTHEIOS_SEV_ERROR = 3,
  pantheios::PANTHEIOS_SEV_WARNING = 4,
  pantheios::PANTHEIOS_SEV_NOTICE = 5,
  pantheios::PANTHEIOS_SEV_INFORMATIONAL = 6,
  pantheios::PANTHEIOS_SEV_DEBUG = 7
}
 API Severity level. More...

Functions

int pantheios::pantheios_init (void)
 Initialises the pantheios library.
void pantheios::pantheios_uninit (void)
 Uninitialises the pantheios library.
int pantheios::pantheios_isSeverityLogged (pan_sev_t severity)
 Indicates whether a given severity is currently being logged by the process.
char const * pantheios::pantheios_getSeverityString (pan_sev_t severity)
 Returns a constant pointer to a non-modifiable nul-terminated string representing the severity level.
int pantheios::pantheios_log_n (pan_sev_t severity, size_t numSlices, pantheios::pan_slice_t const *slices)
 Core logging function, which receives a severity and an array of string slices, and outputs them to the back-end.
int pantheios::pantheios_printf (pan_sev_t severity, char const *format,...)
 printf()-form of logging function, passing the formatted result to the back-end
int pantheios::pantheios_vprintf (pan_sev_t severity, char const *format, va_list args)
 vprintf()-form of logging function, passing the formatted result to the back-end
int pantheios::pantheios_getNextBackEndId (void)
 Returns a (thread-safe) unique back-end identifier.
void pantheios::pantheios_puts (pan_sev_t severity, char const *message)
 A functional equivalent to puts(), incorporating a severity level.
int pantheios::isSeverityLogged (pan_sev_t severity)
 Equivalent to pantheios_isSeverityLogged().
char const * pantheios::getSeverityString (pan_sev_t severity)
 Equivalent to pantheios_getSeverityString().
void pantheios::puts (pan_sev_t severity, char const *message)
 Equivalent to pantheios_puts().


Enumeration Type Documentation

enum pantheios::pan_severity_t
 

API Severity level.

Remarks:
the enumerator values correspond to those of the SysLog protocol
Note:
This type is not used throughout the Pantheios architecture, serving merely to define the eight stock severity levels. Instead, the pan_sev_t type (a 32-bit signed integer) is used instead. This is because Pantheios supports any severity level (that can be expressed in 32-bits). The definition of these SysLog-inspired values is simply what the stock back ends are implemented to recognise.
Enumerator:
PANTHEIOS_SEV_EMERGENCY  system is unusable
PANTHEIOS_SEV_ALERT  action must be taken immediately
PANTHEIOS_SEV_CRITICAL  critical conditions
PANTHEIOS_SEV_ERROR  error conditions
PANTHEIOS_SEV_WARNING  warning conditions
PANTHEIOS_SEV_NOTICE  normal but significant condition
PANTHEIOS_SEV_INFORMATIONAL  informational
PANTHEIOS_SEV_DEBUG  debug-level messages


Function Documentation

char const* pantheios::getSeverityString pan_sev_t  severity  )  [inline]
 

Equivalent to pantheios_getSeverityString().

Examples:
cpp/example_cpp_custom_severity_levels/example_cpp_custom_severity_levels.cpp.

int pantheios::isSeverityLogged pan_sev_t  severity  )  [inline]
 

Equivalent to pantheios_isSeverityLogged().

Examples:
cpp/example_cpp_custom_type_1/example_cpp_custom_type_1.cpp.

int pantheios::pantheios_getNextBackEndId void   ) 
 

Returns a (thread-safe) unique back-end identifier.

This function provides back-end identiers, useful with custom use of Pantheios back-ends, that are guaranteed unique throughout a given process, even in the case where it is invoked by multiple threads concurrently.

Note:
The returned values from this function are always >1000, so as not to clash with any of the pre-defined values used by the Pantheios infrastructure.

char const* pantheios::pantheios_getSeverityString pan_sev_t  severity  ) 
 

Returns a constant pointer to a non-modifiable nul-terminated string representing the severity level.

Parameters:
severity The severity level whose string equivalent is to be returned. Must be one of the PANTHEIOS_SEV_* enumerators, otherwise, the empty string ("") will be returned.
Note:
The return value is undefined if an invalid severity level is specified

int pantheios::pantheios_init void   ) 
 

Initialises the pantheios library.

Returns:
Indicates
Return values:
<0 initialisation has failed, and the library cannot be used
>=0 initialisation has succeeded, and the library can be used. pantheios_uninit() should be called when the library is no longer needed
Note:
C++ compilation units that include pantheios/pantheios.hpp do not need to explicitly call pantheios_init() / pantheios_uninit(), since they will be automatically called by the pantheios_initialiser Schwarz counter class defined by the C++ inclusion. Further note that this is disabled by the definition of the PANTHEIOS_NO_AUTO_INIT, which is automatically defined by a Windows DLL build (as detected by the presence of the _DLL symbol). Auto-initialisation can be forced regardless of the definition of PANTHEIOS_NO_AUTO_INIT by the definition of the symbol PANTHEIOS_FORCE_AUTO_INIT.
Examples:
c/example_c_log_n/example_c_log_n.c, and c/example_c_printf/example_c_printf.c.

int pantheios::pantheios_isSeverityLogged pan_sev_t  severity  ) 
 

Indicates whether a given severity is currently being logged by the process.

Parameters:
severity The severity level to test. Usually one of the PANTHEIOS_SEV_* enumerators.
Return values:
0 The given severity level is not being logged.
1 The given severity level is being logged.
This function is used by Application Layer API for filtering statements prior to formatting their elements for output. It is also useful in those rare circumstances where you may need to undertake a significant amount of client-side preparation of arguments to be passed to the logging statements.

int pantheios::pantheios_log_n pan_sev_t  severity,
size_t  numSlices,
pantheios::pan_slice_t const *  slices
 

Core logging function, which receives a severity and an array of string slices, and outputs them to the back-end.

Parameters:
severity The severity of the log entry
slices Pointer to the array of slices
numSlices The number of slices
Returns:
An indicator of success
Return values:
<0 An error occurred
>=0 The log entry was successfully passed to the back-end

int pantheios::pantheios_printf pan_sev_t  severity,
char const *  format,
  ...
 

printf()-form of logging function, passing the formatted result to the back-end

Parameters:
severity The severity of the log entry
format The format string
Warning:
This function is not type-safe. C++ application code should prefer the application layer functions.
Examples:
c/example_c_printf/example_c_printf.c.

void pantheios::pantheios_puts pan_sev_t  severity,
char const *  message
 

A functional equivalent to puts(), incorporating a severity level.

Using this function skips the application layer entirely, and goes straight to the core. It is therefore more suitable for use in emergency bail-out situations, such as in an application-level catch(...) clauses.

Parameters:
severity The severity of the message to be output.
message The message to be output.

void pantheios::pantheios_uninit void   ) 
 

Uninitialises the pantheios library.

Should be called for every call to pantheios_init() that returns a non-negative code

Note:
C++ compilation units that include pantheios/pantheios.hpp do not need to explicitly call pantheios_init() / pantheios_uninit(), since they will be automatically called by the pantheios_initialiser Schwarz counter class defined by the C++ inclusion. Further note that this is disabled by the definition of the PANTHEIOS_NO_AUTO_INIT, which is automatically defined by a Windows DLL build (as detected by the presence of the _DLL symbol). Auto-initialisation can be forced regardless of the definition of PANTHEIOS_NO_AUTO_INIT by the definition of the symbol PANTHEIOS_FORCE_AUTO_INIT.
Examples:
c/example_c_log_n/example_c_log_n.c, and c/example_c_printf/example_c_printf.c.

int pantheios::pantheios_vprintf pan_sev_t  severity,
char const *  format,
va_list  args
 

vprintf()-form of logging function, passing the formatted result to the back-end

Parameters:
severity The severity of the log entry
format The format string
args va_list form of the arguments
Note:
The behaviour is undefined if the total size of the formatted output exceeds 2048 characters.
Warning:
This function is not type-safe. C++ application code should prefer the application layer functions.

void pantheios::puts pan_sev_t  severity,
char const *  message
[inline]
 

Equivalent to pantheios_puts().

Examples:
cpp/example_cpp_b64/example_cpp_b64.cpp, cpp/example_cpp_blob/example_cpp_blob.cpp, cpp/example_cpp_callback_be/example_cpp_callback_be.cpp, cpp/example_cpp_character/example_cpp_character.cpp, cpp/example_cpp_custom_fe/example_cpp_custom_fe.cpp, cpp/example_cpp_custom_severity_levels/example_cpp_custom_severity_levels.cpp, cpp/example_cpp_custom_type_1/example_cpp_custom_type_1.cpp, cpp/example_cpp_hetero1/example_cpp_hetero1.cpp, cpp/example_cpp_integer/example_cpp_integer.cpp, cpp/example_cpp_pointer/example_cpp_pointer.cpp, cpp/example_cpp_real/example_cpp_real.cpp, cpp/example_cpp_strings/example_cpp_strings.cpp, and cpp/example_cpp_wrap_3pty_log_lib/example_cpp_wrap_3pty_log_lib.cpp.

pantheios Library documentation Matthew Wilson, 2006 SourceForge.net Logo