MeVisLab Toolbox Reference
Logging Macros

Macros that can be used for logging of errors/warnings and information strings. More...

Macros to print debug information.

Defines all ML debug, tracing and error handling macros.

Debug printing is controllable in and by the ML and there is some stuff for selective debug printing. The required files are automatically included when using the standard ML include file mlModuleIncludes.h. The ML controls debug printing by the instance MLErrorOutput of the class ErrorOutput (from Project mlUtils). There the configuration of debug outputs and the error handling system takes place. However you should not use this instance or class directly. Better use the CoreControl module which makes the important settings available (if that is possible by an e.g., application like MeVisLab). There debug printing can be enabled/disabled for the entire ML and debugging can be enabled/disabled for certain classes by the use of environment variables/debug symbols.

The following macros are currently available to be inserted in program code:

Normally each debug output is related to a debug symbol which must be enabled in the ML before the debug information can be printed.

Such a debug symbol can be defined as

  • an environment variable before the ML or the application is started,
  • as a debug symbol in the CoreControl module when used in an application like MeVisLab
  • or directly via programming in the global MLErrorOutput instance of the ML

The third way, however, should be used only in modules dedicated for debug control or diagnostics and not in normal code.

All debug macros are NOT compiled in release mode to improve performance and reduce the amount of code.

If debugging is enabled and the related debug symbol (or environment variable) for the macro is defined then any of the debug macros will sent the

  • file name
  • time stamp
  • line number
  • the debug symbol and
  • the passed macro parameter COUTS

to the global instance MLErrorOutput of the ML. That instance then will sent this information to all registered instances e.g., modules like MLConsole, MLLogFile and application consoles like in MeVisLab.

#define mlDebugConst(ENV_VAR, COUTS)   _mlDebugConst(ENV_VAR, COUTS)
 Public macro to be used instead of print debug information.
 
#define mlDebug(COUTS)
 This macro prints debug information given by COUTS.
 
#define mlDebugConditional(COND_SYM, COUTS)
 Macro to specify subsets of debug outputs for a debug symbol which is given by the runtime type of the class.
 
#define mlDebugPrint(COUTS)   _mlDebugConst(ML_DEBUG_ENV_NAME, COUTS)
 Macro for printing debug information.
 
#define mlDebugClass(CLASS_NAME, COUTS)
 Macro for printing debug information.
 

Public macros to handle (fatal) errors, warnings, information and trace log information.

#define ML_PRINT_FATAL_ERROR(FUNC_NAME, REASON, HANDLING)    _ML_PRINT_FATAL_ERROR_DUMP(FUNC_NAME, REASON, HANDLING, nullptr, nullptr)
 Like ML_PRINT_FATAL_ERROR_DUMP(FUNC_NAME, REASON, HANDLING, RT_OBJ) without a runtime object to be dumped.
 
#define ML_PRINT_ERROR(FUNC_NAME, REASON, HANDLING)    _ML_PRINT_ERROR_DUMP(FUNC_NAME, REASON, HANDLING, nullptr, nullptr)
 Like ML_PRINT_ERROR_DUMP(FUNC_NAME, REASON, HANDLING, RT_OBJ) without a runtime object to be dumped.
 
#define ML_PRINT_WARNING(FUNC_NAME, REASON, HANDLING)    _ML_PRINT_WARNING_DUMP(FUNC_NAME, REASON, HANDLING, nullptr, nullptr)
 Like ML_PRINT_WARNING_DUMP(FUNC_NAME, REASON, HANDLING, RT_OBJ) without a runtime object to be dumped.
 
#define ML_PRINT_INFORMATION(FUNC_NAME, REASON, HANDLING)    _ML_PRINT_INFORMATION_DUMP(FUNC_NAME, REASON, HANDLING, nullptr, nullptr)
 Like ML_PRINT_INFORMATION_DUMP(FUNC_NAME, REASON, HANDLING, RT_OBJ) without a runtime object to be dumped.
 
#define ML_PRINT_INFO(FUNC_NAME, HANDLING)    _ML_PRINT_INFORMATION_DUMP(FUNC_NAME, ML_RESULT_OK, HANDLING, nullptr, nullptr)
 Convenience version of ML_PRINT_INFORMATION(FUNC_NAME, REASON, HANDLING) with REASON = ML_RESULT_OK.
 

Public macros for logging errors, warnings and information messages

Each of the macros returns an ostream which allows to pipe additional details into the message.

These macros are equivalent to the older ML_PRINT_* macros which only took a string for the message details. The error code is an optional second argument. If it is omitted, ML_BAD_PARAMETER is used.

Example:

if (outIndex<0) {
mlError("SomeClass::SomeMethod", ML_BAD_PARAMETER) << "returning NULL, excepted outIndex>=0, but got outIndex==" << outIndex;
}
if (outIndex>3) {
mlError("SomeClass::SomeMethod") << "returning NULL, excepted outIndex<=3, but got outIndex==" << outIndex;
}
ML_BAD_PARAMETER
#define ML_BAD_PARAMETER
A bad/invalid parameter (or even an inappropriate image) has been passed to a module or an algorithm;...
Definition mlTypeDefs.h:823
mlError
#define mlError(FUNCTION,...)
Logs an error for FUNCTION with optional MLErrorCode.
Definition mlLogging.h:52
mlrange_cast
Target mlrange_cast(Source arg)
Generic version of checked ML casts.
Definition mlRangeCasts.h:332
#define mlFatalError(FUNCTION, ...)    ML_NAMESPACE::internal::LogCollector(__FILE__, __LINE__, ML_FATAL, ML_NAMESPACE::internal::LogCollector::getErrorCode(__VA_ARGS__) ,FUNCTION).getStream()
 Logs a fatal error for FUNCTION with optional MLErrorCode.
 
#define mlError(FUNCTION, ...)    ML_NAMESPACE::internal::LogCollector(__FILE__, __LINE__, ML_ERROR, ML_NAMESPACE::internal::LogCollector::getErrorCode(__VA_ARGS__) , FUNCTION).getStream()
 Logs an error for FUNCTION with optional MLErrorCode.
 
#define mlWarning(FUNCTION, ...)    ML_NAMESPACE::internal::LogCollector(__FILE__, __LINE__, ML_WARNING, ML_NAMESPACE::internal::LogCollector::getErrorCode(__VA_ARGS__) , FUNCTION).getStream()
 Logs a warning for FUNCTION with optional MLErrorCode.
 
#define mlInfo(FUNCTION)    ML_NAMESPACE::internal::LogCollector(__FILE__, __LINE__, ML_INFORMATION, ML_RESULT_OK, FUNCTION).getStream()
 Logs an informational message.
 
#define mlFatalErrorWithDump(FUNCTION, ERRORCODE, OBJECT)    ML_NAMESPACE::internal::LogCollector(__FILE__, __LINE__, ML_FATAL, ERRORCODE, FUNCTION, (OBJECT), ML_NAMESPACE::internal::MLSecureGetRuntimeTypeId((OBJECT))).getStream()
 Logs a fatal error for FUNCTION with MLErrorCode ERRORCODE and additionally dumps the given OBJECT (which needs to support getTypeId()).
 
#define mlErrorWithDump(FUNCTION, ERRORCODE, OBJECT)    ML_NAMESPACE::internal::LogCollector(__FILE__, __LINE__, ML_ERROR, ERRORCODE, FUNCTION, (OBJECT), ML_NAMESPACE::internal::MLSecureGetRuntimeTypeId((OBJECT))).getStream()
 Logs an error for FUNCTION with MLErrorCode ERRORCODE and additionally dumps the given OBJECT (which needs to support getTypeId()).
 
#define mlWarningWithDump(FUNCTION, ERRORCODE, OBJECT)    ML_NAMESPACE::internal::LogCollector(__FILE__, __LINE__, ML_WARNING, ERRORCODE, FUNCTION, (OBJECT), ML_NAMESPACE::internal::MLSecureGetRuntimeTypeId((OBJECT))).getStream()
 Logs a warning for FUNCTION with MLErrorCode ERRORCODE and additionally dumps the given OBJECT (which needs to support getTypeId()).
 
#define mlInfoWithDump(FUNCTION, OBJECT)    ML_NAMESPACE::internal::LogCollector(__FILE__, __LINE__, ML_INFORMATION, ML_RESULT_OK, FUNCTION, (OBJECT), ML_NAMESPACE::internal::MLSecureGetRuntimeTypeId((OBJECT))).getStream()
 Logs an informational message for FUNCTION and additionally dumps the given OBJECT (which needs to support getTypeId()).
 

Detailed Description

Macros that can be used for logging of errors/warnings and information strings.

Macro Definition Documentation

◆ ML_PRINT_ERROR

#define ML_PRINT_ERROR ( FUNC_NAME,
REASON,
HANDLING )    _ML_PRINT_ERROR_DUMP(FUNC_NAME, REASON, HANDLING, nullptr, nullptr)

Like ML_PRINT_ERROR_DUMP(FUNC_NAME, REASON, HANDLING, RT_OBJ) without a runtime object to be dumped.

Have a look at mlError for new style logging.

Definition at line 346 of file mlErrorMacros.h.

Referenced by __ML_KERNEL_CASE_CODE_clearAndHandleError(), ml::TVirtualVolume< DATATYPE >::_init(), ml::ITKMLBaseWrapper< OBJ_TYPE, OBJ_TYPE_POINTER, WRAPPER_CLASS_NAME >::addInputBaseField(), ml::ITKMLBaseWrapper< OBJ_TYPE, OBJ_TYPE_POINTER, WRAPPER_CLASS_NAME >::addOutputBaseField(), ml::PCLSupportTools::appendFillPattern(), ml::PCLMLTools::appendSubImageVoxelsToPointCloud(), ml::PCLMLTools::createPointCloudFromBaseList(), ml::getInputAsItkImportImageAndSubImg(), ml::TKernel< KDATATYPE >::manipulateKernelElements(), ML_ITK_ML_PRINT_ERROR(), ml::PCLInventorTools::setMFVecFromPointCloud(), ml::setMLWorldFromITKScaleOriginAndOrientation(), and ml::ListTemplate< T >::setPersistentState().

◆ ML_PRINT_FATAL_ERROR

#define ML_PRINT_FATAL_ERROR ( FUNC_NAME,
REASON,
HANDLING )    _ML_PRINT_FATAL_ERROR_DUMP(FUNC_NAME, REASON, HANDLING, nullptr, nullptr)

Like ML_PRINT_FATAL_ERROR_DUMP(FUNC_NAME, REASON, HANDLING, RT_OBJ) without a runtime object to be dumped.

Have a look at mlFatalError for new style logging.

Definition at line 337 of file mlErrorMacros.h.

Referenced by ml::TKernel< KDATATYPE >::_addCoordinate(), ml::TKernel< KDATATYPE >::_calculateRealKernelExt(), ml::TVirtualVolume< DATATYPE >::_init(), ml::Engine::Engine(), ml::TKernel< KDATATYPE >::getSeparableDimIndex(), ml::CopyBase< BASE_DERIVED_CLASS >::handleNotification(), ml::ITKIndexFromMLVec6(), ml::ITKIndexFromMLVector(), ml::ITKSizeFromMLVector(), ml::MLTStdTypeInfos< VTYP >::MLTStdTypeInfos(), ml::KernelLineApplicatorBase< DATATYPE, KDATATYPE >::operator=(), ml::TKernel< KDATATYPE >::setKernel(), ml::TSubImage< DATATYPE >::TSubImage(), ml::TSubImage< DATATYPE >::TSubImage(), ml::TSubImage< DATATYPE >::TSubImage(), ml::tsubimage_cast(), ml::tsubimage_cast(), ml::tsubimage_cast(), and ml::tsubimage_cast().

◆ ML_PRINT_INFO

#define ML_PRINT_INFO ( FUNC_NAME,
HANDLING )    _ML_PRINT_INFORMATION_DUMP(FUNC_NAME, ML_RESULT_OK, HANDLING, nullptr, nullptr)

Convenience version of ML_PRINT_INFORMATION(FUNC_NAME, REASON, HANDLING) with REASON = ML_RESULT_OK.

Have a look at mlInfo for new style logging.

Definition at line 372 of file mlErrorMacros.h.

◆ ML_PRINT_INFORMATION

#define ML_PRINT_INFORMATION ( FUNC_NAME,
REASON,
HANDLING )    _ML_PRINT_INFORMATION_DUMP(FUNC_NAME, REASON, HANDLING, nullptr, nullptr)

Like ML_PRINT_INFORMATION_DUMP(FUNC_NAME, REASON, HANDLING, RT_OBJ) without a runtime object to be dumped.

Have a look at mlInfo for new style logging.

Definition at line 364 of file mlErrorMacros.h.

◆ ML_PRINT_WARNING

#define ML_PRINT_WARNING ( FUNC_NAME,
REASON,
HANDLING )    _ML_PRINT_WARNING_DUMP(FUNC_NAME, REASON, HANDLING, nullptr, nullptr)

Like ML_PRINT_WARNING_DUMP(FUNC_NAME, REASON, HANDLING, RT_OBJ) without a runtime object to be dumped.

Have a look at mlWarning for new style logging.

Definition at line 355 of file mlErrorMacros.h.

Referenced by ml::RasterFunction::_fillRaster(), ml::ITKMatrixFromMLMatrix(), ml::ITKPointSetFromBasePointer(), ml::ITKPolylineFromBasePointer(), ml::MLMatrixFromITKMatrix(), ml::MLVectorFromITKIndex(), and ml::MLVectorFromITKSize().

◆ mlDebug

#define mlDebug ( COUTS)

This macro prints debug information given by COUTS.

It requires that the class has the runtime type system implemented. So it accesses the type id and creates the debug symbol by using 'ML_' + the class name. This is the normal macro used in implementations of ML modules. See header documentation for more information about debug printing.

Parameters
COUTSThe stream output redirected to the MLErrorOutput instance if the corresponding debug symbol is activated.

Definition at line 130 of file mlDebug.h.

◆ mlDebugClass

#define mlDebugClass ( CLASS_NAME,
COUTS )

Macro for printing debug information.

It requires that the class CLASS_NAME has the runtime type system implemented. So it accesses the type id and creates debug environment name. See header documentation for more information about debug printing.

Parameters
CLASS_NAMEThe class type used to generate the debug symbol on which the output of COUTS is activated.
COUTSThe stream output sent to the error/debug output if the debug symbol created from CLASS_NAME is activated.

Definition at line 204 of file mlDebug.h.

◆ mlDebugConditional

#define mlDebugConditional ( COND_SYM,
COUTS )

Macro to specify subsets of debug outputs for a debug symbol which is given by the runtime type of the class.

It prints debug information in two different cases:

  • If the class name (given by the runtime type) is specified as symbol or
  • If the class name + "-" + COND_SYM is specified.

E.g., if the following macro is used in the class "MyModule":

mlDebugConditional("CASES", "Message1");
mlDebugConditional
#define mlDebugConditional(COND_SYM, COUTS)
Macro to specify subsets of debug outputs for a debug symbol which is given by the runtime type of th...
Definition mlDebug.h:172

the debug information "Message1" is printed if the debug symbol "ML_MYMODULE" is defined or if the the debug symbol "ML_MYMODULE-CASES" is specified. If only "ML_MYMODULE-CASES" is specified then only "Message1" is printed but nothing else from class MyModule.

This macro requires that the class in which it is used has the runtime type system implemented. So it accesses the type id and creates debug environment name from it. See header documentation for more information about debug printing.

Parameters
COND_SYMspecifies the additional symbol added to the class symbol (separated by a "-")
COUTSThe stream output sent to the error/debug output if the symbol given by the class name + "-" + COND_SYM is activated.

Definition at line 172 of file mlDebug.h.

◆ mlDebugConst

#define mlDebugConst ( ENV_VAR,
COUTS )   _mlDebugConst(ENV_VAR, COUTS)

Public macro to be used instead of print debug information.

See header documentation of this file for full documentation.

Definition at line 110 of file mlDebug.h.

◆ mlDebugPrint

#define mlDebugPrint ( COUTS)    _mlDebugConst(ML_DEBUG_ENV_NAME, COUTS)

Macro for printing debug information.

It uses the ML_DEBUG_ENV_VAR as name of the class to be debugged. ML_DEBUG_ENV_VAR is required to be defined. Useful for classes which do not have a runtime interface. See header documentation for more information about debug printing.

Parameters
COUTSThe stream output sent to the error/debug output if the symbol defined in ML_DEBUG_ENV_NAME is activated.

Definition at line 184 of file mlDebug.h.

◆ mlError

#define mlError ( FUNCTION,
... )    ML_NAMESPACE::internal::LogCollector(__FILE__, __LINE__, ML_ERROR, ML_NAMESPACE::internal::LogCollector::getErrorCode(__VA_ARGS__) , FUNCTION).getStream()

Logs an error for FUNCTION with optional MLErrorCode.

If MLErrorCode is omitted, ML_BAD_PARAMETER is used.

Definition at line 52 of file mlLogging.h.

Referenced by ml::TypedComputeClusters::process().

◆ mlErrorWithDump

#define mlErrorWithDump ( FUNCTION,
ERRORCODE,
OBJECT )    ML_NAMESPACE::internal::LogCollector(__FILE__, __LINE__, ML_ERROR, ERRORCODE, FUNCTION, (OBJECT), ML_NAMESPACE::internal::MLSecureGetRuntimeTypeId((OBJECT))).getStream()

Logs an error for FUNCTION with MLErrorCode ERRORCODE and additionally dumps the given OBJECT (which needs to support getTypeId()).

Definition at line 71 of file mlLogging.h.

◆ mlFatalError

#define mlFatalError ( FUNCTION,
... )    ML_NAMESPACE::internal::LogCollector(__FILE__, __LINE__, ML_FATAL, ML_NAMESPACE::internal::LogCollector::getErrorCode(__VA_ARGS__) ,FUNCTION).getStream()

Logs a fatal error for FUNCTION with optional MLErrorCode.

If MLErrorCode is omitted, ML_BAD_PARAMETER is used.

Definition at line 47 of file mlLogging.h.

◆ mlFatalErrorWithDump

#define mlFatalErrorWithDump ( FUNCTION,
ERRORCODE,
OBJECT )    ML_NAMESPACE::internal::LogCollector(__FILE__, __LINE__, ML_FATAL, ERRORCODE, FUNCTION, (OBJECT), ML_NAMESPACE::internal::MLSecureGetRuntimeTypeId((OBJECT))).getStream()

Logs a fatal error for FUNCTION with MLErrorCode ERRORCODE and additionally dumps the given OBJECT (which needs to support getTypeId()).

Definition at line 67 of file mlLogging.h.

◆ mlInfo

#define mlInfo ( FUNCTION)     ML_NAMESPACE::internal::LogCollector(__FILE__, __LINE__, ML_INFORMATION, ML_RESULT_OK, FUNCTION).getStream()

Logs an informational message.

Definition at line 62 of file mlLogging.h.

◆ mlInfoWithDump

#define mlInfoWithDump ( FUNCTION,
OBJECT )    ML_NAMESPACE::internal::LogCollector(__FILE__, __LINE__, ML_INFORMATION, ML_RESULT_OK, FUNCTION, (OBJECT), ML_NAMESPACE::internal::MLSecureGetRuntimeTypeId((OBJECT))).getStream()

Logs an informational message for FUNCTION and additionally dumps the given OBJECT (which needs to support getTypeId()).

Definition at line 79 of file mlLogging.h.

◆ mlWarning

#define mlWarning ( FUNCTION,
... )    ML_NAMESPACE::internal::LogCollector(__FILE__, __LINE__, ML_WARNING, ML_NAMESPACE::internal::LogCollector::getErrorCode(__VA_ARGS__) , FUNCTION).getStream()

Logs a warning for FUNCTION with optional MLErrorCode.

If MLErrorCode is omitted, ML_BAD_PARAMETER is used.

Definition at line 57 of file mlLogging.h.

◆ mlWarningWithDump

#define mlWarningWithDump ( FUNCTION,
ERRORCODE,
OBJECT )    ML_NAMESPACE::internal::LogCollector(__FILE__, __LINE__, ML_WARNING, ERRORCODE, FUNCTION, (OBJECT), ML_NAMESPACE::internal::MLSecureGetRuntimeTypeId((OBJECT))).getStream()

Logs a warning for FUNCTION with MLErrorCode ERRORCODE and additionally dumps the given OBJECT (which needs to support getTypeId()).

Definition at line 75 of file mlLogging.h.