Class to handle all ML debug prints, errors, warnings, and information. More...

#include <mlErrorOutput.h>

Public Types
typedef void	ErrorOutputCB(void usrData, const char errStr, const ErrorOutputInfos &infos)
	Function type which can be passed to the ErrorOutput class.

typedef char *	DumpCB(const void dumpObj, const RuntimeType dumpObjRT)
	Definition of a callback type which can be registered at the ML C-API.

Public Member Functions
	ErrorOutput ()
	Constructor.

	~ErrorOutput ()
	Destructor.

void	reset ()
	Resets instance to construction state.

Initialization and destruction of the ErrorOutput class.
void	init ()
	Only to force an access to instances of this class to make the objects automatically initialized during dll initialization to be sure that error handler exists surely before other global objects.

void	destroy ()
	Destroys global settings; to be called during ML or mlUtils destruction, not to be called by applications.

The way how the ML shall handle messages.
For each message type an ML termination mode can be defined. Default is continue for all message types except of fatal errors where an abort is used in debug and in release mode.
void	setTerminationType (MLMessageType level, MLTerminator term)
	Sets the way how the ML shall handle a specific message type, note that ML_ALL_MESSAGES is not a valid parameter.

MLTerminator	getTerminationType (MLMessageType level) const
	Return the way how the ML shall handle messages.

Specifies which kinds of messages are handled y the ErrorOutput class.
void	setMessageFilter (MLuint32 messageType)
	Sets messages to be handled by MLErrorOutput as set bits in messageType.

MLuint32	getMessageFilter ()
	Returns the bit mask specifying the message filter which is composed from binary ORed MLMessageTypes enums.

Handling/setting/getting runtime dump callbacks.
void	setDumpCB (DumpCB *dumpCB)
	Registers a dump function dumpCB which will be called by the ML to dump object structures e.g., to a log file or something like that.

DumpCB *	getDumpCB () const
	Returns the currently registered dump callback. Default is NULL.

Enables/Disables/Queries whether debug printing is enabled.
If `on` is `true`, all debug messages are handled by the ML errorOutput and passed to the output channels. Otherwise only selective debug prints are passed to the output. By default debug printing is off. Note that during ML initialization the variable ML_DEBUG_ALL is evaluated which might lead to enabled full debug printing.
void	setFullDebuggingOn (bool on)
	Enables/disables full debugging by passing true / false as `on`.

bool	isFullDebuggingOn () const
	Returns `true` if full debugging is enabled, otherwise `false`.

Management of callback functions for (error) message handling.
void	addErrorOutputCB (void userData, ErrorOutputCB callback)
	Registers a function called when any message is sent MLErrorOutput.

void	removeErrorOutputCB (void userData, ErrorOutputCB callback)
	Removes error print function from function list if both parameters are identical with their corresponding registered versions.

bool	hasErrorOutputCB (void userData, ErrorOutputCB callback) const
	Returns `true` if the output function is registered, i.e., if both parameters are identical with their corresponding registered versions otherwise `false` is returned.

void	removeAllErrorOutputCBs ()
	Removes all registered error print functions from list.

size_t	getNumOutputCBs () const
	Returns the number of registered callbacks.

void	addDebugEnvName (const std::string &envName)
	Adds debug environment string whose information shall be printed.

void	removeDebugEnvName (const std::string &envName)
	Removes a registered debug environment string whose information shall not be printed any more.

bool	hasDebugEnvName (const std::string &envName) const
	Returns `true` if the debug environment name exists.

const std::vector< std::string > &	getDebugEnvNames () const
	Returns a list of debug environment names.

void	removeAllDebugEnvNames ()
	Removes all registered debug environment strings from list.

size_t	getNumDebugEnvNames () const
	Return number of registered debug environment names.

Sending messages to Visual Studio.
void	setOutputMessagesInVisualStudio (bool flag)
	Sets if messages should be printed in Visual Studio (turned on by default in debug mode).

bool	shouldOutputMessagesInVisualStudio () const
	Returns wheter messages should be printed in Visual Studio.

Sending messages to std::cout or std::cerr.
bool	areMessagesSentToCout () const
	Messages are only sent to std::cout if this flag is true.

void	sendMessagesToCout (bool on)
	If `on` is passed as `true`, message sending to std::cout is enabled.

bool	areMessagesSentToCerr () const
	Messages are only sent to std::cerr if this flag is true.

void	sendMessagesToCerr (bool on)
	If `on` is passed as `true` message sending to std::cerr is enabled.

Specification of trace information outputs on errors.
MLuint32	getMaxNumTraceListDumps () const
	Reutrns the maximum number of trace list entries to be shown on fatal error outputs.

void	setMaxNumTraceListDumps (MLGlobalTraceBufferType num)
	Sets the maximum number of trace list entries to be shown on fatal error outputs.

MLuint32	getMaxNumTraceStackDumps () const
	Returns the maximum number of trace stack entries to be shown on fatal error outputs.

void	setMaxNumTraceStackDumps (MLGlobalTraceBufferType num)
	Sets the maximum number of trace stack entries to be shown on fatal error outputs.

MLuint32	getTraceDumpMessageBits () const
	Returns the bit mask describing all message types which shall lead to a trace list and trace stack dump.

void	setTraceDumpMessageBits (MLuint32 bitMask)
	Sets the bit mask describing all message types which shall lead to a trace list and trace stack dump.

HIDDEN STUFF WHICH IS REQUIRED TO BE PUBLIC FOR MACRO USAGE
The following functions are called by macros and therefore they need to be public. Nevertheless these functions should not be called directly by any user or application.
void	printAndNotify (MLMessageType messageType, const std::string &libraryPrefix, const std::string &fPrefix, const std::string &functionName, const std::string &reason, const std::string &handling="", const std::string &file="", int line=-1, const void dumpObj=nullptr, const RuntimeType dumpObjRT=nullptr, MLErrorCode errCode=ML_RESULT_OK) const
	Core error printing function used by all other functions.

void	printAndNotify (MLMessageType messageType, const std::string &libraryPrefix, const std::string &fPrefix, const std::string &functionName, MLErrorCode reason, const std::string &handling="", const std::string &file="", int line=-1, const void dumpObj=nullptr, const RuntimeType dumpObjRT=nullptr) const
	Like the other printAndNotify() function with the difference that `reason` is an MLErrorCode which is automatically translated to a string so that it is not needed to pass it manually as last parameter.

void	handleDebugPrint (const std::string &envVar, const std::string &libraryPrefix, std::stringstream &reason, const char *file, int line) const
	Function called from mlDebugPrint.

void	handleDebugPrint (const std::string &envVar, const std::string &libraryPrefix, const char reason, const char file, int line) const
	Function called from mlDebugPrint.

Protected Member Functions
	ErrorOutput (const ErrorOutput &errorOutput)
	Copy constructor, only to be used by state class of ML.

ErrorOutput &	operator= (const ErrorOutput &errorOutput)
	Assignment operator, only to be used by state class of ML.

Friends
class	ml::State
	Allows access to ErrorOutput only to save/restore state of ML.

std::ostream &	std::operator<< (std::ostream &s, const ErrorOutput &errorOutput)
	Makes stream output of ErrorOutput class a friend to provide access to internals.

Detailed Description

Class to handle all ML debug prints, errors, warnings, and information.

Thread-safety: This class is not thread-safe, but offers a thread-safe printAndNotify() method. Changing the state of an ErrorOutput instance while another thread is inside printAndNotify() can lead to undesired behavior and crashes. If this proves to be a problem (currently the global ErrorOutput instance is not changed while other threads are running), the whole API should be made thread-safe.

The class ErrorOutput is the central error handle and redirection class for the ML. It contains a set of methods to print debug and trace log information, information, warnings, errors and fatal errors.

It also offers a registration mechanism where the application can register itself to be notified when an error, tracing, warning, information or debug information shall be printed or handled.

Some methods are available to control the error output of the ML. They permit registering functions to notify the application, to control a set of debug environment variables.

The ML provides a global instance MLErrorOutput of this class which is normally used. Creating an instance on your own is not necessary.

Definition at line 93 of file mlErrorOutput.h.

Member Typedef Documentation

◆ DumpCB

typedef char * ml::ErrorOutput::DumpCB(const void *dumpObj, const RuntimeType *dumpObjRT)

Definition of a callback type which can be registered at the ML C-API.

If such a callback type is registered there then it will be called after some ML (fatal) errors or warnings if the error is caused by a runtime type object. The callback then has the chance to dump the runtime typed object into a log file, to a mail or to an output channel where developers can analyze it. If any of both parameters is NULL the call shall be ignored.

Parameters

dumpObj	runtimeTypeObject is a pointer to the runtime typed object causing this error and which shall be dumped and returned as string. If NULL is passed then NULL is returned.
dumpObjRT	is the runtime type of the object which shall be dumped or NULL. If NULL is passed then NULL is returned.

Returns: is NULL on failure or any NULL parameter. A null terminated character string is returned otherwise which contains the string dump of dumpObj. It must be freed by the caller after usage with MLFree() or ml::Memory::freeMemory().

Definition at line 121 of file mlErrorOutput.h.

◆ ErrorOutputCB

typedef void ml::ErrorOutput::ErrorOutputCB(void *usrData, const char *errStr, const ErrorOutputInfos &infos)

Function type which can be passed to the ErrorOutput class.

So any application can register itself to receive debug or error information or a callback to handle a request to kill or restart the application.

Definition at line 102 of file mlErrorOutput.h.

Constructor & Destructor Documentation

◆ ErrorOutput() [1/2]

ml::ErrorOutput::ErrorOutput ( )

Constructor.

◆ ~ErrorOutput()

ml::ErrorOutput::~ErrorOutput ( )

Destructor.

◆ ErrorOutput() [2/2]

ml::ErrorOutput::ErrorOutput ( const ErrorOutput & errorOutput )

protected

Copy constructor, only to be used by state class of ML.

Member Function Documentation

◆ addDebugEnvName()

void ml::ErrorOutput::addDebugEnvName ( const std::string & envName )

Adds debug environment string whose information shall be printed.

◆ addErrorOutputCB()

void ml::ErrorOutput::addErrorOutputCB	(	void *	userData,
		ErrorOutputCB *	callback )

Registers a function called when any message is sent MLErrorOutput.

Note that this callback may be called from any thread, not only the main thread. Thus the callback has to support being called from multiple threads. Since a lock is used internally, it is safe to assume that the callback will not be called from multiple threads at the same time.

◆ areMessagesSentToCerr()

bool ml::ErrorOutput::areMessagesSentToCerr ( ) const

inline

Messages are only sent to std::cerr if this flag is true.

Definition at line 299 of file mlErrorOutput.h.

◆ areMessagesSentToCout()

bool ml::ErrorOutput::areMessagesSentToCout ( ) const

inline

Messages are only sent to std::cout if this flag is true.

Definition at line 292 of file mlErrorOutput.h.

◆ destroy()

void ml::ErrorOutput::destroy ( )

Destroys global settings; to be called during ML or mlUtils destruction, not to be called by applications.

◆ getDebugEnvNames()

const std::vector< std::string > & ml::ErrorOutput::getDebugEnvNames ( ) const

Returns a list of debug environment names.

◆ getDumpCB()

DumpCB * ml::ErrorOutput::getDumpCB ( ) const

Returns the currently registered dump callback. Default is NULL.

◆ getMaxNumTraceListDumps()

MLuint32 ml::ErrorOutput::getMaxNumTraceListDumps ( ) const

inline

Reutrns the maximum number of trace list entries to be shown on fatal error outputs.

Definition at line 311 of file mlErrorOutput.h.

◆ getMaxNumTraceStackDumps()

MLuint32 ml::ErrorOutput::getMaxNumTraceStackDumps ( ) const

inline

Returns the maximum number of trace stack entries to be shown on fatal error outputs.

Definition at line 317 of file mlErrorOutput.h.

◆ getMessageFilter()

MLuint32 ml::ErrorOutput::getMessageFilter ( )

Returns the bit mask specifying the message filter which is composed from binary ORed MLMessageTypes enums.

◆ getNumDebugEnvNames()

size_t ml::ErrorOutput::getNumDebugEnvNames ( ) const

Return number of registered debug environment names.

◆ getNumOutputCBs()

size_t ml::ErrorOutput::getNumOutputCBs ( ) const

inline

Returns the number of registered callbacks.

Definition at line 245 of file mlErrorOutput.h.

◆ getTerminationType()

MLTerminator ml::ErrorOutput::getTerminationType ( MLMessageType level ) const

Return the way how the ML shall handle messages.

◆ getTraceDumpMessageBits()

MLuint32 ml::ErrorOutput::getTraceDumpMessageBits ( ) const

inline

Returns the bit mask describing all message types which shall lead to a trace list and trace stack dump.

Default is ML_FATAL.

Definition at line 324 of file mlErrorOutput.h.

◆ hasDebugEnvName()

bool ml::ErrorOutput::hasDebugEnvName ( const std::string & envName ) const

Returns true if the debug environment name exists.

◆ hasErrorOutputCB()

bool ml::ErrorOutput::hasErrorOutputCB	(	void *	userData,
		ErrorOutputCB *	callback ) const

Returns true if the output function is registered, i.e., if both parameters are identical with their corresponding registered versions otherwise false is returned.

◆ init()

void ml::ErrorOutput::init ( )

Only to force an access to instances of this class to make the objects automatically initialized during dll initialization to be sure that error handler exists surely before other global objects.

Does nothing special. to be called when ML or mlUtils dlls are initialized, not to be called by applications.

◆ isFullDebuggingOn()

bool ml::ErrorOutput::isFullDebuggingOn ( ) const

Returns true if full debugging is enabled, otherwise false.

◆ operator=()

ErrorOutput & ml::ErrorOutput::operator= ( const ErrorOutput & errorOutput )

protected

Assignment operator, only to be used by state class of ML.

◆ removeAllDebugEnvNames()

void ml::ErrorOutput::removeAllDebugEnvNames ( )

Removes all registered debug environment strings from list.

Avoid using this because all registered functions from other applications or modules are also removed.

◆ removeAllErrorOutputCBs()

void ml::ErrorOutput::removeAllErrorOutputCBs ( )

Removes all registered error print functions from list.

Avoid using this because all registered functions from other applications or modules are also removed.

◆ removeDebugEnvName()

void ml::ErrorOutput::removeDebugEnvName ( const std::string & envName )

Removes a registered debug environment string whose information shall not be printed any more.

◆ removeErrorOutputCB()

void ml::ErrorOutput::removeErrorOutputCB	(	void *	userData,
		ErrorOutputCB *	callback )

Removes error print function from function list if both parameters are identical with their corresponding registered versions.

◆ reset()

void ml::ErrorOutput::reset ( )

Resets instance to construction state.

◆ sendMessagesToCerr()

void ml::ErrorOutput::sendMessagesToCerr ( bool on )

If on is passed as true message sending to std::cerr is enabled.

Otherwise nothing is sent to that stream.

◆ sendMessagesToCout()

void ml::ErrorOutput::sendMessagesToCout ( bool on )

If on is passed as true, message sending to std::cout is enabled.

Otherwise nothing is sent to that stream.

◆ setDumpCB()

void ml::ErrorOutput::setDumpCB ( DumpCB * dumpCB )

Registers a dump function dumpCB which will be called by the ML to dump object structures e.g., to a log file or something like that.

Resetting the function can be done by passing NULL.

◆ setFullDebuggingOn()

void ml::ErrorOutput::setFullDebuggingOn ( bool on )

Enables/disables full debugging by passing true / false as on.

◆ setMaxNumTraceListDumps()

void ml::ErrorOutput::setMaxNumTraceListDumps ( MLGlobalTraceBufferType num )

Sets the maximum number of trace list entries to be shown on fatal error outputs.

◆ setMaxNumTraceStackDumps()

void ml::ErrorOutput::setMaxNumTraceStackDumps ( MLGlobalTraceBufferType num )

Sets the maximum number of trace stack entries to be shown on fatal error outputs.

◆ setMessageFilter()

void ml::ErrorOutput::setMessageFilter ( MLuint32 messageType )

Sets messages to be handled by MLErrorOutput as set bits in messageType.

Binary adds of MLMessageTypes are allowed e.g., messageType = ML_FATAL | ML_ERROR handles all ML_FATAL and \ ML_ERROR messages by calling the registered callback functions.

◆ setOutputMessagesInVisualStudio()

void ml::ErrorOutput::setOutputMessagesInVisualStudio ( bool flag )

inline

Sets if messages should be printed in Visual Studio (turned on by default in debug mode).

Definition at line 279 of file mlErrorOutput.h.

References mlrange_cast().

◆ setTerminationType()

void ml::ErrorOutput::setTerminationType	(	MLMessageType	level,
		MLTerminator	term )

Sets the way how the ML shall handle a specific message type, note that ML_ALL_MESSAGES is not a valid parameter.

◆ setTraceDumpMessageBits()

void ml::ErrorOutput::setTraceDumpMessageBits ( MLuint32 bitMask )

Sets the bit mask describing all message types which shall lead to a trace list and trace stack dump.

Default is ML_FATAL.

◆ shouldOutputMessagesInVisualStudio()

bool ml::ErrorOutput::shouldOutputMessagesInVisualStudio ( ) const

inline

Returns wheter messages should be printed in Visual Studio.

Definition at line 282 of file mlErrorOutput.h.

Friends And Related Symbol Documentation

◆ ml::State

friend class ml::State

friend

Allows access to ErrorOutput only to save/restore state of ML.

Definition at line 443 of file mlErrorOutput.h.

◆ std::operator<<

std::ostream & std::operator<<	(	std::ostream &	s,
		const ErrorOutput &	errorOutput )

friend

Makes stream output of ErrorOutput class a friend to provide access to internals.

The documentation for this class was generated from the following file:

MeVis/Foundation/Sources/MLUtilities/mlErrorOutput.h

Public Types

Public Member Functions

Protected Member Functions

Friends

Detailed Description

Member Typedef Documentation

◆ DumpCB

◆ ErrorOutputCB

Constructor & Destructor Documentation

◆ ErrorOutput() [1/2]

◆ ~ErrorOutput()

◆ ErrorOutput() [2/2]

Member Function Documentation

◆ addDebugEnvName()

◆ addErrorOutputCB()

◆ areMessagesSentToCerr()

◆ areMessagesSentToCout()

◆ destroy()

◆ getDebugEnvNames()

◆ getDumpCB()

◆ getMaxNumTraceListDumps()

◆ getMaxNumTraceStackDumps()

◆ getMessageFilter()

◆ getNumDebugEnvNames()

◆ getNumOutputCBs()

◆ getTerminationType()

◆ getTraceDumpMessageBits()

◆ hasDebugEnvName()

◆ hasErrorOutputCB()

◆ init()

◆ isFullDebuggingOn()

◆ operator=()

◆ removeAllDebugEnvNames()

◆ removeAllErrorOutputCBs()

◆ removeDebugEnvName()

◆ removeErrorOutputCB()

◆ reset()

◆ sendMessagesToCerr()

◆ sendMessagesToCout()

◆ setDumpCB()

◆ setFullDebuggingOn()

◆ setMaxNumTraceListDumps()

◆ setMaxNumTraceStackDumps()

◆ setMessageFilter()

◆ setOutputMessagesInVisualStudio()

◆ setTerminationType()

◆ setTraceDumpMessageBits()

◆ shouldOutputMessagesInVisualStudio()

Friends And Related Symbol Documentation

◆ ml::State

◆ std::operator<<