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:

Initialise and uninitiliase the front-end and back-end libraries
Format logging requests and emit them to the back-end transport component(s).

The core consists of the following components:

Definitions of basic and log-specific types:
- pan_uint8_t, pan_uint16_t, pan_uint32_t, and pan_uint64_t
- pan_slice_t
Definition of stock logging severity level types:
- pan_severity_t
- pan_sev_t
Definition of the API functions:
- pantheios_init() and pantheios_uninit()
- pantheios_isSeverityLogged() (pantheios::isSeverityLogged() for C++ compilation units)
- pantheios_log_n()
- pantheios_printf(), pantheios_vprintf() and pantheios_puts() (pantheios::puts() for C++ compilation units)
Definition of the Generated N-ary Core Functions

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 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

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.

char const * pantheios_getSeverityString (pan_sev_t severity)

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

size_t pantheios_getSeverityStringLength (pan_sev_t severity)

Returns the length of the string returned by pantheios_getSeverityString().

char const * pantheios_getInitErrorString (int errCode)

Returns a constant pointer to a non-NULL non-modifiable nul-terminated string representing the initialisation error.

size_t pantheios_getInitErrorStringLength (int errCode)

Returns the length of the string returned by pantheios_getInitErrorString().

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, char const *format,...)

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

int pantheios_logvprintf (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_getNextBackEndId (void)

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

void pantheios_puts (pan_sev_t severity, char const *message)

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

int isSeverityLogged (pan_sev_t severity)

Equivalent to pantheios_isSeverityLogged().

char const * getSeverityString (pan_sev_t severity)

Equivalent to pantheios_getSeverityString().

size_t getSeverityStringLength (pan_sev_t severity)

Equivalent to pantheios_getSeverityStringLength().

char const * getInitErrorString (int errCode)

Equivalent to pantheios_getInitErrorString().

size_t getInitErrorStringLength (int errCode)

Equivalent to pantheios_getInitErrorStringLength().

void puts (pan_sev_t severity, char const *message)

Equivalent to pantheios_puts().

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::getInitErrorString ( int errCode ) [inline]

Equivalent to pantheios_getInitErrorString().

size_t pantheios::getInitErrorStringLength ( int errCode ) [inline]

Equivalent to pantheios_getInitErrorStringLength().

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.

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

Equivalent to pantheios_getSeverityStringLength().

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.

char const* pantheios::pantheios_getInitErrorString ( int errCode )

Returns a constant pointer to a non-NULL non-modifiable nul-terminated string representing the initialisation error.

Parameters:

errCode The initialisation error code whose string explanation is to be returned. If the error code is not recognised, the empty string ("") will be returned.

size_t pantheios::pantheios_getInitErrorStringLength ( int errCode )

Returns the length of the string returned by pantheios_getInitErrorString().

Parameters:

errCode

The initialisation error code whose string equivalent is to be returned. If the error code is not recognised, 0 will be returned.

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-NULL 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.

size_t pantheios::pantheios_getSeverityStringLength ( pan_sev_t severity )

Returns the length of the string returned by pantheios_getSeverityString().

Parameters:

severity

The severity level whose string equivalent is to be returned. Must be one of the PANTHEIOS_SEV_* enumerators, otherwise, 0 will be returned.

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, _USRDLL or _AFXDLL 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.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 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_logprintf	(	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.

int pantheios::pantheios_logvprintf	(	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 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,
		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.

Examples:: c/example.c.N/example.c.N.c.

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, _USRDLL or _AFXDLL 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.log_n/example.c.log_n.c, and c/example.c.N/example.c.N.c.

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

Equivalent to pantheios_puts().

Examples:: cpp/example.cpp.args/example.cpp.args.cpp, 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.file/example.cpp.file.cpp, cpp/example.cpp.hetero1/example.cpp.hetero1.cpp, cpp/example.cpp.highres/example.cpp.highres.cpp, cpp/example.cpp.integer/example.cpp.integer.cpp, cpp/example.cpp.lowres/example.cpp.lowres.cpp, cpp/example.cpp.pointer/example.cpp.pointer.cpp, cpp/example.cpp.process_id/example.cpp.process_id.cpp, cpp/example.cpp.real/example.cpp.real.cpp, cpp/example.cpp.strings/example.cpp.strings.cpp, cpp/example.cpp.thread_id/example.cpp.thread_id.cpp, cpp/example.cpp.tracing.with_function/example.cpp.tracing.with_function.cpp, cpp/example.cpp.tracing/example.cpp.tracing.cpp, and cpp/example.cpp.wrap_3pty_log_lib/example.cpp.wrap_3pty_log_lib.cpp.

pantheios Library documentation � Matthew Wilson, 2006-2008


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
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.
char const *	pantheios_getSeverityString (pan_sev_t severity)
	Returns a constant pointer to a non-NULL non-modifiable nul-terminated string representing the severity level.
size_t	pantheios_getSeverityStringLength (pan_sev_t severity)
	Returns the length of the string returned by pantheios_getSeverityString().
char const *	pantheios_getInitErrorString (int errCode)
	Returns a constant pointer to a non-NULL non-modifiable nul-terminated string representing the initialisation error.
size_t	pantheios_getInitErrorStringLength (int errCode)
	Returns the length of the string returned by pantheios_getInitErrorString().
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, char const *format,...)
	printf()-form of logging function, passing the formatted result to the back-end
int	pantheios_logvprintf (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_getNextBackEndId (void)
	Returns a (thread-safe) unique back-end identifier.
void	pantheios_puts (pan_sev_t severity, char const *message)
	A functional equivalent to `puts()`, incorporating a severity level.
int	isSeverityLogged (pan_sev_t severity)
	Equivalent to pantheios_isSeverityLogged().
char const *	getSeverityString (pan_sev_t severity)
	Equivalent to pantheios_getSeverityString().
size_t	getSeverityStringLength (pan_sev_t severity)
	Equivalent to pantheios_getSeverityStringLength().
char const *	getInitErrorString (int errCode)
	Equivalent to pantheios_getInitErrorString().
size_t	getInitErrorStringLength (int errCode)
	Equivalent to pantheios_getInitErrorStringLength().
void	puts (pan_sev_t severity, char const *message)
	Equivalent to pantheios_puts().