Event Logging

Functions and support for logging of events. More...

Classes
class	LoggerMonitor
	Logging output monitor. More...
class	Hermes2DLogoMessage
	Generates a logo when the library is loaded and the logo is enabled (a preprocessor directive H2D_NO_LOGO). More...
struct	Hermes2DLogEventInfo
	Info about a log record. Used for output log function. More...
Defines
#define	H2D_LOG_FILE_DELIM_SIZE 80
	A size of a delimiter in a log file.
#define	H2D_BUILD_LOG_INFO(__event) Hermes2DLogEventInfo(__event, H2D_LOG_FILE, __CURRENT_FUNCTION, __FILE__, __LINE__)
	Builds info about an event.
#define	H2D_LOG_FILE "hermes2d.log"
#define	__CURRENT_FUNCTION __PRETTY_FUNCTION__
	A platform-dependent string defining a current function.
#define	H2D_EC_ERROR 'E'
	An event code: errors.
#define	H2D_EC_ASSERT 'X'
	An event code: asserts.
#define	H2D_EC_WARNING 'W'
	An event code: warnings.
#define	H2D_EC_INFO 'I'
	An event code: info about results.
#define	H2D_EC_VERBOSE 'V'
	An event code: more details about details.
#define	H2D_EC_TRACE 'R'
	An event code: execution tracing.
#define	H2D_EC_TIME 'T'
	An event code: time measurements.
#define	H2D_EC_DEBUG 'D'
	An event code: general debugging messages.
#define	error(...) hermes2d_exit_if(hermes2d_log_message_if(true, H2D_BUILD_LOG_INFO(H2D_EC_ERROR), __VA_ARGS__))
	Logs an error and quits the application. For details see Usage Guidelines.
#define	error_if(__cond,...) hermes2d_exit_if(hermes2d_log_message_if(__cond, H2D_BUILD_LOG_INFO(H2D_EC_ERROR), __VA_ARGS__))
	If __cond is true, it logs an error and quits the application.
#define	assert_msg(__cond,...) assert(!hermes2d_log_message_if(!(__cond), H2D_BUILD_LOG_INFO(H2D_EC_ASSERT), __VA_ARGS__))
	If __cond is false, it logs a message and invokes assert().
#define	H2D_RCTR(__var) true
	Defines a condition that can control whether logging of a given event is enabled.
#define	warn(...)
	Logs a warning.
#define	warn_if(__cond,...)
	If __cond is true, it logs a warning.
#define	warn_intr(...)
	Logs an warning about integration. This is used to report integration issues which may occur frequently.
#define	info(...)
	Logs info about a result of an operation.
#define	info_if(__cond,...)
	If __cond is true, it logs info about a result of na operation.
#define	verbose(...)
	Logs detailed info about a result of an operation. It should be used as a second level of the macro info().
#define	trace(...)
	Logs information about executed code portions.
#define	report_time(...)
	Logs information about measured time.
#define	debug_log(...) hermes2d_log_message_if(true && H2D_RCTR(__h2d_report_debug), H2D_BUILD_LOG_INFO(H2D_EC_DEBUG), __VA_ARGS__)
	Logs a general debugging information.
Functions
H2D_API void	hermes2d_exit_if (bool cond, int code=-1)
	Exits the application if the condition is true.
H2D_API bool	hermes2d_log_message_if (bool cond, const Hermes2DLogEventInfo &info, const char *msg,...)
	Logs an event if the condition is true.

Detailed Description

Functions and support for logging of events.

Hermes2D controls even logging through:

compiler directives (e.g. H2D_REPORT_INFO). Directives has to be included prior including Hermes2D header files.
boolean variables (e.g. __h2d_report_info). These variables can be set anytime but their direct use is discouraged because they are integeded to be used by Python wreappers. Initial settings of these variables is given by the compiler directives.

By default, all logs are written into a file 'hermes2d.log' created in the current directory. A logs created by the application can be directed to a separate file. The file is specified through a compiler directive H2D_REPORT_FILE, i.e.,

    #define H2D_REPORT_FILE "application.log"

In a case, the application is a test (i.e., a directive H2D_TEST is defined), the output is directed to a file 'test.log'. The output to a file can be suppressed specifying H2D_REPORT_NO_FILE.

Supported Directives

The following list contains directives that controls even logging.

H2D_REPORT_WARN: Define to allow warning.
H2D_REPORT_WARN_INTRO: Define to allow warning about integration issues.
H2D_REPORT_INFO: Define to allow info.
H2D_REPORT_VERBOSE: Define to allow verbose.
H2D_REPORT_TIME: Define to allow time measurement reports.
H2D_REPORT_TRACE: Define to allow execution tracing.
H2D_REPORT_FILE "my_file.log": Define to direct output of a file my_file_log.
H2D_REPORT_NO_FILE: Define to avoid any output file. It always overrides H2D_REPORT_FILE.
H2D_REPORT_REPORT_ALL: Define to allow all events to be reported except integration warnings (H2D_REPORT_WARN_INTRO). It overrides all settings.
H2D_REPORT_RUNTIME_CONTROL: Define to allow controling of event logging through boolean variables. Notice this will enforce evaluation of all parameters of logging macros even though a logging of a given event is not enabled.
H2D_NO_LOGO: Define to disable logo message. This directive has to be defined at the compilation time of Hermes2D library.

Usage Guidelines

Do not put any computation (e.g., it++) into parameters if the result of the computation is used outside the macro. If a given event is not logged, no code may be generated and therefore your computation will never be executed.
Do not use new line characters (i.e. \n or \r) inside the message. Used a space or an exclamation mark instead, see below.
Use an exclamation mark at the beginning of the message to emphasize the message.
Use a space at the beginning of the message to generate a sub-info.
Use the event logging wisely since every line is flushed to a file if file output is enabled. This allows to obtain all logged vents in a case a SIGSEGV happens on a remote machine, e.g., if an application is executed using a batch system on a cluster.
The format of the message is similar to the function printf().

Supported Directives

The following code

    #define H2D_REPORT_WARN
    #define H2D_REPORT_INFO
    #define H2D_REPORT_VERBOSE
    #define H2D_REPORT_FILE "application.log"
    #include <hermes2d.h>
    #include <solver_umfpack.h>

will enable logging of events warning, info and verbose in the application and it copies the output to a file application.log.

The following code

    info("Result is %d", 32);
    info(" Probability of error is %g", 0.1);
    trace("Computation is done.");
    info("!Done");

will generate

    I Result is 32
      Probability of error is 0.1
    R Computation is done.

    I Done.

on screen if all events are enabled.

Define Documentation

#define __CURRENT_FUNCTION __PRETTY_FUNCTION__

A platform-dependent string defining a current function.

For internal use only.

#define assert_msg	(	__cond,
		...		)	assert(!hermes2d_log_message_if(!(__cond), H2D_BUILD_LOG_INFO(H2D_EC_ASSERT), __VA_ARGS__))

If __cond is false, it logs a message and invokes assert().

Similar to the function assert() if NDEBUG is defined, no code may be generated for the macro. For usage guidelines, see Usage Guidelines.

#define debug_log ( ... ) hermes2d_log_message_if(true && H2D_RCTR(__h2d_report_debug), H2D_BUILD_LOG_INFO(H2D_EC_DEBUG), __VA_ARGS__)

Logs a general debugging information.

This macro should be used for debugging outputs and it is suggested to remove almost all of them an debugged issue is solved. If NDEBUG is defined, no code may be generated for the macro. For usage guidelines, see Usage Guidelines.

#define error ( ... ) hermes2d_exit_if(hermes2d_log_message_if(true, H2D_BUILD_LOG_INFO(H2D_EC_ERROR), __VA_ARGS__))

Logs an error and quits the application. For details see Usage Guidelines.

#define error_if	(	__cond,
		...		)	hermes2d_exit_if(hermes2d_log_message_if(__cond, H2D_BUILD_LOG_INFO(H2D_EC_ERROR), __VA_ARGS__))

If __cond is true, it logs an error and quits the application.

For usage guidelines, see Usage Guidelines.

#define H2D_BUILD_LOG_INFO ( __event ) Hermes2DLogEventInfo(__event, H2D_LOG_FILE, __CURRENT_FUNCTION, __FILE__, __LINE__)

Builds info about an event.

For internal use only.

#define H2D_EC_ASSERT 'X'

An event code: asserts.

For internal use only.

#define H2D_EC_DEBUG 'D'

An event code: general debugging messages.

For internal use only.

#define H2D_EC_ERROR 'E'

An event code: errors.

For internal use only.

#define H2D_EC_INFO 'I'

An event code: info about results.

For internal use only.

#define H2D_EC_TIME 'T'

An event code: time measurements.

For internal use only.

#define H2D_EC_TRACE 'R'

An event code: execution tracing.

For internal use only.

#define H2D_EC_VERBOSE 'V'

An event code: more details about details.

For internal use only.

#define H2D_EC_WARNING 'W'

An event code: warnings.

For internal use only.

#define H2D_LOG_FILE "hermes2d.log"

#define H2D_LOG_FILE_DELIM_SIZE 80

A size of a delimiter in a log file.

For internal use only.

#define H2D_RCTR ( __var ) true

Defines a condition that can control whether logging of a given event is enabled.

For internal use only.

An argument __var spefies a variable which can control a logging of a given event during runtime if runtime control is enabled through a preprocessor directive H2D_REPORT_RUNTIME_CONTROL.

#define info ( ... )

Logs info about a result of an operation.

If H2D_REPORT_INFO is not defined, no code may be generated for the macro. For usage guidelines, see Usage Guidelines.

#define info_if	(	__cond,
		...		)

If __cond is true, it logs info about a result of na operation.

If H2D_REPORT_WARN is not defined, no code may be generated for the macro. For usage guidelines, see Usage Guidelines.

#define report_time ( ... )

Logs information about measured time.

If H2D_REPORT_TIME is not defined, no code may be generated for the macro. For usage guidelines, see Usage Guidelines.

#define trace ( ... )

Logs information about executed code portions.

If H2D_REPORT_TRACE is not defined, no code may be generated for the macro. For usage guidelines, see Usage Guidelines.

#define verbose ( ... )

Logs detailed info about a result of an operation. It should be used as a second level of the macro info().

If H2D_REPORT_VERBOSE is not defined, no code may be generated for the macro. For usage guidelines, see Usage Guidelines.

#define warn ( ... )

Logs a warning.

If H2D_REPORT_WARN is not defined, no code may be generated for the macro. For usage guidelines, see Usage Guidelines.

#define warn_if	(	__cond,
		...		)

If __cond is true, it logs a warning.

If H2D_REPORT_WARN is not defined, no code may be generated for the macro. For usage guidelines, see Usage Guidelines.

#define warn_intr ( ... )

Logs an warning about integration. This is used to report integration issues which may occur frequently.

If H2D_REPORT_INTR_WARNING is not defined, no code may be generated for the macro. For usage guidelines, see Usage Guidelines.

Function Documentation

H2D_API void hermes2d_exit_if	(	bool	cond,
		int	code = `-1`
	)

Exits the application if the condition is true.

For internal use only.

Used by macros error() and error_if().

Parameters:

`[in]`	cond	True if the function should exit.
`[in]`	code	Exit code returned by the application throught exit().

H2D_API bool hermes2d_log_message_if	(	bool	cond,
		const Hermes2DLogEventInfo &	info,
		const char *	msg,
			...
	)

Logs an event if the condition is true.

For internal use only.

Used by all even logging macros. Since this function returns a copy of the parameter cond, it can be used to call a function hermes2d_exit_if() or a function(). Thanks to that, the macro behaves as a function rather than a block of code. Also, this allows a debugger to a particular code.

Parameters:

`[in]`	cond	True if the event should be logged.
`[in]`	info	Info about the event.
`[in]`	msg	A message or prinf-like formatting string.

Returns:: A value of the parameter cond.

Event Logging

Classes

Defines

Functions

Detailed Description

Supported Directives

Usage Guidelines

Supported Directives

Define Documentation

Function Documentation