minxlib::logging Class Reference

Interface for logging via Python. More...

#include <logging.hh>

Public Member Functions
	logging ()
	Default constructor. More...
log	debug ()
	Write debug messages to Minx log. More...
log	info ()
	Write informational messages to Minx log. More...
log	warning ()
	Write warnings to Minx log. More...
log	error ()
	Write errors to Minx log. More...
log	critical ()
	Write critical errors to Minx log. More...

Static Public Member Functions
static logging	get_logger (const std::string &name)
	Create a logger object for the specified class. More...

Detailed Description

Interface for logging via Python.

This class provides an API for the remaining minxlib classes to emit log messages via Python's standard logging module. This stratgey allows minxlib's log messages to be integrated with the log messages output by the rest of Minx and avoid implementing a custom logging facility within minxlib.

Additionally, leveraging Python's existing logging functionality ensures that end-users can configure Minx's logging support in a uniform way. That is, end-users don't have to be aware of the fact that minxlib is actually written in C++; to them, all of Minx is a collection of Python modules and classes whose logging support works the same.

This class does not have a Python interface. It is meant to be used only within minxlib. The following snippet of code illustrates the typical and intended usage pattern:

namespace minxlib {

// Global logger object for some minxlib class
static logging logger ;

void some_class::pythonize()
{
    // After exporting some_class to Python via Boost.Python:
    logger = logging::get_logger("some_class") ;
}

void some_class::some_func()
{
    int i = 5 ;
    logger.debug() << "the value of i is " << i ;
    logger.info () << "this is an informational message" ;
    if (something_horrible_has_happened)
        logger.critical() << "all hell just broke loose!" ;
}

} // namespace minxlib

Constructor & Destructor Documentation

minxlib::logging::logging

(

)

Default constructor.

Returns

Nothing really.

This logging API is meant to be used in the following manner: each minxlib class that needs to emit log messages should define a static global logger object in its .cc file and initialize the object in its Pythonize function by calling this class's get_logger() method. The client class can then use the logger object to emit log messages at different levels.

The default constructor allows "empty" logger objects to be created at global scope within a .cc file. It has no other purpose. Therefore, this constructor is not (and should not be) used in any other situation.

Member Function Documentation

log minxlib::logging::critical

(

)

Write critical errors to Minx log.

Returns

A log object whose stream operator will emit a log message.

This function returns an object that you can use to emit messages about critical errors with the stream output operator. The usage pattern is the same as described for the debug() function.

log minxlib::logging::debug

(

)

Write debug messages to Minx log.

Returns

A log object whose stream operator will emit a log message.

This function returns an object that you can use to emit debug messages with the stream output operator. Here is some sample code that shows how the object returned by this function is meant to be used:

logger.debug() << "value of x = " << x ;

In the above snippet, logger will usually be a static global variable within the client class's .cc file and it would have been initialized in the client class's Pythonize function. The sample code in the class description shows more details.

Note

The object returned by this function is an instance of a private inner class defined inside the logging class. Therefore, you cannot store the returned object in a local variable. The only thing you can do with it is use the stream output operator as shown above. This ensures that the inner class that takes care of the details of logging can only be used as a temporary so that, when it goes out of scope, its destructor can write the debug message to the Minx log via Python's logging module.

log minxlib::logging::error

(

)

Write errors to Minx log.

Returns

A log object whose stream operator will emit a log message.

This function returns an object that you can use to emit errors with the stream output operator. The usage pattern is the same as described for the debug() function.

static logging minxlib::logging::get_logger ( const std::string &  name)

static

Create a logger object for the specified class.

Parameters

name	minxlib class for which we want a logger.

Returns

A logger object for the specified class.

This function returns a logger object that can be used by the named class to send log messages to the Minx log. It is meant to be called by the Pythonize functions of the various minxlib modules that send log messages to the Minx log. The .cc files for these modules should define a static global logger object that is initialized by calling this function in the Pythonize function of the above-mentioned classes.

See the sample code in the class description for intended usage pattern.

log minxlib::logging::info

(

)

Write informational messages to Minx log.

Returns

A log object whose stream operator will emit a log message.

This function returns an object that you can use to emit informational messages with the stream output operator. The usage pattern is the same as described for the debug() function.

log minxlib::logging::warning

(

)

Write warnings to Minx log.

Returns

A log object whose stream operator will emit a log message.

This function returns an object that you can use to emit warnings with the stream output operator. The usage pattern is the same as described for the debug() function.