5.4. The Class ErrorOutput and Configuring Message Outputs

5.4. The Class `ErrorOutput` and Configuring Message Outputs
	Chapter 5. Debugging and Error Handling

5.4. The Class `ErrorOutput` and Configuring Message Outputs

The class ErrorOutput is the central error handle and redirection class for the ML. It contains a set of methods to print debug and tracing information, warnings, errors and fatal errors, and to configure a lot of error and message output settings, to specify special behavior (e.g., aborting) on some message types and much more. It also offers a registration mechanism where the application can register itself to be notified when an error, tracing, warning or debug information is to be printed or handled. They permit to register functions to notify the application, to control a set of debug environment variables, etc.

The ML provides a global instance MLErrorOutput of this class which is normally used by debug and error handling macros as well as by the ML API (see Section 6.3, “mlAPI.h”). You do not have to create an instance on your own.

Note

	Note
Usually, you should not use this class directly. Since this class is subject to change, use debug or error handling macros instead. If you need to configure the error handling system e.g., for your application, use the `CoreControl` module (if available in your application) or functionality of ML API (see Section 6.3, “mlAPI.h”).

Usually, you should not use this class directly.

Since this class is subject to change, use debug or error handling macros instead.

If you need to configure the error handling system e.g., for your application, use the CoreControl module (if available in your application) or functionality of ML API (see Section 6.3, “mlAPI.h”).

See the header file documentation of


          mlErrorOutput.h

and


          mlErrorOutputInfos.h

for detailed information on how to use the following methods.

The class ErrorOutput offers methods to

specify what the ML shall do on debug messages, (fatal) errors, etc.
1. void setTerminationType(MLMessageType level, MLTerminator term);
2. MLTerminator getTerminationType(MLMessageType level) const;
specify a filter to suppress any type of undesired messages (e.g., debug infos, std::cout, std::cerr or other messages)
1. void setMessageFilter(unsigned int messageType);
2. unsigned int getMessageFilter();
install a dump callback function that is called when any error occurs on a runtime type. It permits dumping a runtime typed object as a string into the error message:
1. void setDumpCB(DumpCB *dumpCB);
2. DumpCB *getDumpCB() const;
enable/disable debug message handling:
1. void setFullDebuggingOn(bool on);
2. bool isFullDebuggingOn() const;
manage registered callback functions that will be called when messages are sent to this class:
1. void addErrorOutputCB(void *userData, ErrorOutputCB *callback);
2. void removeErrorOutputCB(void *userData, ErrorOutputCB *callback);
3. bool hasErrorOutputCB(void *userData, ErrorOutputCB *callback) const;
4. void removeAllErrorOutputCBs();
5. unsigned long getNumOutputCBs() const;
manage a set of debug symbols (also see Section 5.1, “Printing Debug Information”):
1. void addDebugEnvName(const std::string &envName);
2. void removeDebugEnvName(const std::string &envName);
3. bool hasDebugEnvName(const std::string &envName) const;
4. const std::vector<std::string> &getDebugEnvNames() const;
5. void removeAllDebugEnvNames();
6. unsigned long getNumDebugEnvNames() const;
suppress std::cout and std::cerr prints to the standard console outputs:
1. bool areMessagesSentToCout() const;
2. void sendMessagesToCout(bool on);
3. bool areMessagesSentToCerr() const;
4. void sendMessagesToCerr(bool on);
send messages to an instance of this class that are used by debug and error handling macros (see also Section 5.2, “Handling Errors” and Section 5.1, “Printing Debug Information”):
1. void printAndNotify(...) const;
2. void handleDebugPrint(...) const;
configures and returns which message types shall be dumped:
1. size_t getTraceDumpMessageBits() const;
2. void setTraceDumpMessageBits(MLuint32 bitMask);
configure the length of the list of recently called functions and when to dump the current call stack into the registered error handling callbacks (see also TracingAndExceptionHandling):
1. size_t getMaxNumTraceListDumps() const;
2. void setMaxNumTraceListDumps(MLGlobalTraceBufferType num);
3. size_t getMaxNumTraceStackDumps() const;
4. void setMaxNumTraceStackDumps(MLGlobalTraceBufferType num);


5.3. Registering Error Handlers		5.5. Tracing, Exception Handling and Checked Object Construction/Destruction