b2000::logging Namespace Reference

Classes
class	DBName
class	Logger

Functions
Logger &	get_logger (const std::string &logger_name="")
void	parse_on_logging_option (const std::string &s, const std::string &db_name, const bool dry_run=false)

Variables
Level	critical
Level	error
Level	warning
Level	info
Level	data
Level	debug

Detailed Description

Implementation of a flexible logging system, inspired from the logging module of Python.

Logging namespaces

Logging is performed by calling methods on instances of the Logger class (hereafter called loggers). Each instance has a name, and they are conceptually arranged in a namespace hierarchy using dots (periods) as separators. For example, a logger named "assembler" is the parent of loggers "assembler.natural_boundary_condition", "assembler.stiffness_matrix" and "assembler.essential_boundary_condition". Logger names can be anything you want, and indicate the area of an application in which a logged message originates.

Logging levels

Logged messages also have levels of importance associated with them. The default levels provided are debug, info, data, warning, error and critical. You are not constrained to use these levels: you can specify your own.

Handlers

Logging messages are subjected to a dispatch mechanism through the use of handlers, which are instances of subclasses of the Handler class. Handlers are responsible for ensuring that a logged message ends up in a particular location (or set of locations) which is useful for the target audience for that message. Each logger can have zero, one or more pair handlers/level associated with it (via the add_handler method of Logger). A logged message is sent to all handlers associated with the logger or theses ancestors for which the level is less or equal to the level of the message (each handler is only called one time for a given logging message).

Logged messages are formatted for presentation through instances of subclasses of the Formatter class.

Example

Here is a simple logging example:

// Somewhere at the beginning of a function or better, in a static
// field of a class.
Logger& logger = logging::get_logger("assembler.stiffness_matrix")
 
// When a log message must be emitted.
logger.LOG(logging::info, "The message");
 
// A more convenient form of message submission.
logger << logging::info << "The message " << logging::LOGFLUSH

If the construction of the message is costly, it is better to test if the logger is enable before generating the string:

// Test if the logger is active.
if (logger.is_enabled_for(logging::info) {
   // ...
   logger << logging::info << "The message " << logging::LOGFLUSH;
}

Logging of data to the logging database

The logging facility can be used to stream out data to the logging database. To this end, the data items must be given a name. This is achieved by means of the logging::DBName class.

The following example demonstrates the use of logging::DBName for a 2D quadrilateral element.

double coor[4][3];
if (logger.is_enabled_for(logging::data)) {
    logger << logging::data << "COOR " <<
        logging::DBName("COOR", get_object_name()) <<
        b2linalg::Matrix<double, b2linalg::Mrectangle_constref>(3, 4, coor[0]) <<
        logging::LOGFLUSH;
}

Note that the array "coor" cannot be given directly, it must be given as a b2linalg::Matrix object. The b2linalg::Matrix object uses the column-major format, thus, the data will be stored transposed on the database.

Function Documentation

get_logger()

Logger & b2000::logging::get_logger ( const std::string &  logger_name = "" )

inline

Function to retrieve a reference to a Logger instance. It is called from code that uses the logging facility.

parse_on_logging_option()

void b2000::logging::parse_on_logging_option	(	const std::string &	s,
		const std::string &	db_name,
		const bool	dry_run = false
	)

Parse and set a logging option given as "<level> of <logger> in <formatter>". This is used to parse the contents of the -l option given on the b2000++ processor's command-line.

Variable Documentation

critical

b2000::logging::Level b2000::logging::critical

extern

Indicates a critical program failure (e.g. out of memory). Messages of this level are always printed.

data

b2000::logging::Level b2000::logging::data

extern

For logging to database. Ignored by default.

debug

b2000::logging::Level b2000::logging::debug

extern

Debugging messages (more verbose than logging::info). Ignored by default.

error

b2000::logging::Level b2000::logging::error

extern

Indicates an error or problem. Messages of this level are always printed.

info

b2000::logging::Level b2000::logging::info

extern

Information messages. Ignored by default.

warning

b2000::logging::Level b2000::logging::warning

extern

Indictates a warning. Messages of this level are always printed.