Synesis Software STLSoft - ... Robust, Lightweight, Cross-platform, Template Software ...

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 diagnostic logging facilities are available from C client code via the core API directly, via the pantheios_logprintf() and pantheios_logvprintf() functions:

  int   i;
  float f;
  pantheios_logprintf(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  pan_slice_t
 String slice used by the Pantheios Application Layer API to communicate with the Pantheios Core API. More...

Enumerations

enum  pan_severity_t {
  SEV_EMERGENCY = 0,
  SEV_ALERT = 1,
  SEV_CRITICAL = 2,
  SEV_ERROR = 3,
  SEV_WARNING = 4,
  SEV_NOTICE = 5,
  SEV_INFORMATIONAL = 6,
  SEV_DEBUG = 7
}
 API Severity level. More...

Functions

pan_uint32_t pantheios_getVersion (void)
 Returns information about the version of Pantheios.
int pantheios_init (void)
 Initialises the Pantheios library.
void pantheios_uninit (void)
 Uninitialises the Pantheios library.
int pantheios_isSeverityLogged (pan_sev_t severity)
 Indicates whether a given severity is currently being logged by the process.
int 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_logprintf (pan_sev_t severity, pan_char_t const *format,...)
 printf()-form of logging function, passing the formatted result to the back-end
int pantheios_logvprintf (pan_sev_t severity, pan_char_t const *format, va_list args)
 vprintf()-form of logging function, passing the formatted result to the back-end
int pantheios_getNextBackEndId (void)
 Returns a (thread-safe) unique back-end identifier.
void pantheios_logputs (pan_sev_t severity, pan_char_t const *message)
 A functional equivalent to puts(), incorporating a severity level.
void pantheios_puts (pan_sev_t severity, pan_char_t const *message)
 [DEPRECATED] Equivalent to pantheios_logputs().
int isSeverityLogged (pan_sev_t severity)
 Equivalent to pantheios_isSeverityLogged().
pan_char_t const * getStockSeverityString (pan_sev_t severity)
 Equivalent to pantheios_getStockSeverityString().
size_t getStockSeverityStringLength (pan_sev_t severity)
 Equivalent to pantheios_getStockSeverityStringLength().
char const * getInitCodeString (int code)
 Equivalent to pantheios_getInitCodeString().
size_t getInitCodeStringLength (int code)
 Equivalent to pantheios_getInitCodeStringLength().
void logputs (pan_sev_t severity, pan_char_t const *message)
 Equivalent to pantheios_logputs().
void puts (pan_sev_t severity, pan_char_t const *message)
 [DEPRECATED] Equivalent to pantheios_logputs().
int logprintf (pan_sev_t severity, pan_char_t const *format,...)
 Equivalent to pantheios_logprintf().
int logvprintf (pan_sev_t severity, pan_char_t const *format, va_list args)
 Equivalent to pantheios_logvprintf().

Enumeration Type Documentation

enum 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:
SEV_EMERGENCY  system is unusable
SEV_ALERT  action must be taken immediately
SEV_CRITICAL  critical conditions
SEV_ERROR  error conditions
SEV_WARNING  warning conditions
SEV_NOTICE  normal but significant condition
SEV_INFORMATIONAL  informational
SEV_DEBUG  debug-level messages

Function Documentation

char const* pantheios::getInitCodeString ( int  code  )  [inline]

Equivalent to pantheios_getInitCodeString().

size_t pantheios::getInitCodeStringLength ( int  code  )  [inline]

Equivalent to pantheios_getInitCodeStringLength().

pan_char_t const* pantheios::getStockSeverityString ( pan_sev_t  severity  )  [inline]

Equivalent to pantheios_getStockSeverityString().

Examples:
cpp/misc/example.cpp.misc.extended_severity_information/example.cpp.misc.extended_severity_information.cpp.

size_t pantheios::getStockSeverityStringLength ( pan_sev_t  severity  )  [inline]

Equivalent to pantheios_getStockSeverityStringLength().

int pantheios::isSeverityLogged ( pan_sev_t  severity  )  [inline]

Equivalent to pantheios_isSeverityLogged().

Examples:
cpp/misc/example.cpp.misc.custom_type_1/example.cpp.misc.custom_type_1.cpp.

int pantheios::logprintf ( pan_sev_t  severity,
pan_char_t const *  format,
  ... 
) [inline]

Equivalent to pantheios_logprintf().

void pantheios::logputs ( pan_sev_t  severity,
pan_char_t const *  message 
) [inline]

Equivalent to pantheios_logputs().

Examples:
cpp/backends/example.cpp.backends.callback/example.cpp.backends.callback.cpp, cpp/backends/example.cpp.backends.file.callback/example.cpp.backends.file.callback.cpp, cpp/backends/example.cpp.backends.file.lrsplit/example.cpp.backends.file.lrsplit.cpp, cpp/backends/example.cpp.backends.file/example.cpp.backends.file.cpp, cpp/backends/example.cpp.backends.mx.1/example.cpp.backends.mx.1.cpp, cpp/backends/example.cpp.backends.mx.2/example.cpp.backends.mx.2.cpp, cpp/custom/example.cpp.custom.wrap_log4cplus/example.cpp.custom.wrap_log4cplus.cpp, cpp/custom/example.cpp.custom.wrap_log4cxx/example.cpp.custom.wrap_log4cxx.cpp, cpp/format/example.cpp.format.highres/example.cpp.format.highres.cpp, cpp/format/example.cpp.format.lowres/example.cpp.format.lowres.cpp, cpp/format/example.cpp.format.pad/example.cpp.format.pad.cpp, cpp/frontends/example.cpp.frontends.custom/example.cpp.frontends.custom.cpp, cpp/inserters/example.cpp.inserter.args/example.cpp.inserter.args.cpp, cpp/inserters/example.cpp.inserter.b/example.cpp.inserter.b.cpp, cpp/inserters/example.cpp.inserter.b64/example.cpp.inserter.b64.cpp, cpp/inserters/example.cpp.inserter.blob/example.cpp.inserter.blob.cpp, cpp/inserters/example.cpp.inserter.character/example.cpp.inserter.character.cpp, cpp/inserters/example.cpp.inserter.hex_ptr/example.cpp.inserter.hex_ptr.cpp, cpp/inserters/example.cpp.inserter.hostid/example.cpp.inserter.hostid.cpp, cpp/inserters/example.cpp.inserter.i/example.cpp.inserter.i.cpp, cpp/inserters/example.cpp.inserter.integer/example.cpp.inserter.integer.cpp, cpp/inserters/example.cpp.inserter.m2w/example.cpp.inserter.m2w.cpp, cpp/inserters/example.cpp.inserter.p/example.cpp.inserter.p.cpp, cpp/inserters/example.cpp.inserter.pointer/example.cpp.inserter.pointer.cpp, cpp/inserters/example.cpp.inserter.processid/example.cpp.inserter.processid.cpp, cpp/inserters/example.cpp.inserter.real/example.cpp.inserter.real.cpp, cpp/inserters/example.cpp.inserter.threadid/example.cpp.inserter.threadid.cpp, cpp/inserters/example.cpp.inserter.w2m/example.cpp.inserter.w2m.cpp, cpp/inserters/example.cpp.inserter.xi/example.cpp.inserter.xi.cpp, cpp/inserters/example.cpp.inserter.xp/example.cpp.inserter.xp.cpp, cpp/misc/example.cpp.misc.custom_type_1/example.cpp.misc.custom_type_1.cpp, cpp/misc/example.cpp.misc.extended_severity_information/example.cpp.misc.extended_severity_information.cpp, cpp/misc/example.cpp.misc.hetero1/example.cpp.misc.hetero1.cpp, cpp/misc/example.cpp.misc.strings/example.cpp.misc.strings.cpp, cpp/tracing/example.cpp.tracing.standard/example.cpp.tracing.standard.cpp, and cpp/tracing/example.cpp.tracing.with_function/example.cpp.tracing.with_function.cpp.

int pantheios::logvprintf ( pan_sev_t  severity,
pan_char_t const *  format,
va_list  args 
) [inline]

Equivalent to pantheios_logvprintf().

int pantheios::core::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.
Precondition:
The behaviour of this function is undefined if it is called more than INT_MAX - 1000 times in the lifetime of a process

pan_uint32_t pantheios::pantheios_getVersion ( void   ) 

Returns information about the version of Pantheios.

The value returned is split into 4 x 8 bits, as follows:

Returns:
The value of PANTHEIOS_VER at the time that Pantheios was built
Remarks:
This function may be called without having initialised the Pantheios library

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 any of the __DLL__, _WINDLL or _USRDLL symbols). 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.core.pantheios_logprintf/example.c.core.pantheios_logprintf.c, c/example.c.extended_severity/example.c.extended_severity.c, c/example.c.log_n/example.c.log_n.c, and c/example.c.N/example.c.N.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 diagnostic logging statements.

int pantheios::core::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_logprintf ( pan_sev_t  severity,
pan_char_t 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.core.pantheios_logprintf/example.c.core.pantheios_logprintf.c, and c/example.c.extended_severity/example.c.extended_severity.c.

void pantheios::pantheios_logputs ( pan_sev_t  severity,
pan_char_t const *  message 
)

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

Using this function skips the application layer entirely and, if the given seveirty level is enabled, goes straight to the back-end. 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.
Examples:
c/example.c.N/example.c.N.c.

int pantheios::pantheios_logvprintf ( pan_sev_t  severity,
pan_char_t 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 4095 characters.
Warning:
This function is not type-safe. C++ application code should prefer the application layer functions.

void pantheios::pantheios_puts ( pan_sev_t  severity,
pan_char_t const *  message 
)

[DEPRECATED] Equivalent to pantheios_logputs().

Deprecated:
This function is now obsolete, and will be removed from a future version of Pantheios; instead use pantheios_logputs()

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 any of the __DLL__, _WINDLL or _USRDLL symbols). 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.core.pantheios_logprintf/example.c.core.pantheios_logprintf.c, c/example.c.extended_severity/example.c.extended_severity.c, c/example.c.log_n/example.c.log_n.c, and c/example.c.N/example.c.N.c.

void pantheios::puts ( pan_sev_t  severity,
pan_char_t const *  message 
) [inline]

[DEPRECATED] Equivalent to pantheios_logputs().

Deprecated:
This function is now obsolete, and will be removed from a future version of Pantheios; instead use pantheios_logputs()

pantheios Library documentation © Matthew Wilson & Synesis Software, 2006-2011 SourceForge.net Logo