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 that can be passed to the ErrorOutput class. More...

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

Public Member Functions
	ErrorOutput ()
	Constructor. More...

	~ErrorOutput ()
	Destructor. More...

void	reset ()
	Resets instance to construction state. More...

Initialization and destruction of the ErrorOutput class.
void	init ()
	Only to force access to instances of this class to make the objects automatically initialize during DLL initialization, ensuring that the error handler exists before other global objects. More...

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

The way how the ML shall handle messages.
For each message type, an ML termination mode can be defined. Default is to 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. More...

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

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

MLuint32	getMessageFilter ()
	Returns the bit mask specifying the message filter that is composed from binary OR'd MLMessageTypes enums. More...

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

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

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 an enabled full debug printing.
void	setFullDebuggingOn (bool on)
	Enables/disables full debugging by passing `true` or `false` as `on`. More...

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

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

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

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. More...

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

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

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

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

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

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

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

size_t	getNumDebugEnvNames () const
	Returns the number of registered debug environment names. More...

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

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

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

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

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

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

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

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

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

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

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

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

HIDDEN CODE 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. More...

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
	Similar to the other printAndNotify() function with the difference that `reason` is an MLErrorCode that is automatically translated to a string so that it is not needed to pass it manually as the last parameter. More...

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

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

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

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

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

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

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 an 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 an 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 that 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 the two parameters is NULL, the call shall be ignored.

Parameters

dumpObj	A pointer to the runtime typed object causing this error and that shall be dumped and returned as string. If NULL is passed, then NULL is returned.
dumpObjRT	The runtime type of the object that shall be dumped or NULL. If NULL is passed, then NULL is returned.

Returns: NULL on failure or any NULL parameter. A NULL-terminated character string is returned otherwise that 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 that can be passed to the ErrorOutput class.

This way, 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 the ML.

Member Function Documentation

◆ addDebugEnvName()

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

Adds a 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 from 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

Returns 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 that is composed from binary OR'd MLMessageTypes enums.

◆ getNumDebugEnvNames()

size_t ml::ErrorOutput::getNumDebugEnvNames ( ) const

Returns the 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

Returns the way how the ML shall handle messages.

◆ getTraceDumpMessageBits()

MLuint32 ml::ErrorOutput::getTraceDumpMessageBits ( ) const

inline

Returns the bit mask describing all message types that 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 access to instances of this class to make the objects automatically initialize during DLL initialization, ensuring that the error handler exists 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, it returns false.

◆ operator=()

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

protected

Assignment operator, only to be used by state class of the 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 the 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 anymore.

◆ removeErrorOutputCB()

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

Removes an error-print function from the 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, the sending of a message 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, the sending of a message to std::cout is enabled.

Otherwise, nothing is sent to that stream.

◆ setDumpCB()

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

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

Resetting the function can be done by passing NULL.

◆ setFullDebuggingOn()

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

Enables/disables full debugging by passing true or 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 additions 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 whether messages should be printed in Visual Studio (turned on by default in debug mode).

Definition at line 279 of file mlErrorOutput.h.

◆ 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 that 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 Function Documentation

◆ ml::State

friend class ml::State

friend

Allows access to ErrorOutput only to save/restore state of the 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 Function Documentation

◆ ml::State

◆ std::operator<<