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