Purpose

The module RuntimeDump installs a function in the ML error handler that can dump ML modules and other runtime-typed objects of the ML if the ML considers them as the probable reason for an error or crash.

This module can be added for diagnostic purposes to a module network to get a string dump of error causing ML modules.

Usage

Simply add this module to your module network.

The RuntimeDump module will attempt to install its dump function in the ML error handler. Normally, this will work; however, if another application or RuntimeDump has already installed that function, the module will notify you in its :field:stateInfo field.

If the function is installed successfully, all possible states of error-causing ML modules will be dumped to the “Handling” section of the generated error messages.

Note that primarily fatal errors will trigger such dumping, and in debug mode, the ML is configured to terminate after handling the error. You need to reconfigure the ML error handler to catch fatal errors and continue afterward to see the dumped results.

Currently, the installed dump function dumps objects of the following (runtime) class types if they are passed to any of the macros _ML_PRINT_FATAL_ERROR, _DUMP _ML_PRINT_ERROR_DUMP, or _ML_PRINT_WARNING_DUMP:

  • Field
  • FieldContainer
  • SubImage
  • MemoryImage
  • PagedImage
  • MedicalImageProperties
  • ImageProperties
  • Module

Tips

You can also use the RuntimeDump module in applications that run in release mode to obtain additional error information in the case of fatal errors caught by the ML. This information in the error outputs will facilitate debugging, especially in release mode, where detailed debug information is normally not available.

Note that objects causing exceptions tend to be in a state that may make it impossible to dump them correctly. Although the dump functionality is implemented quite safely within exception handlers, it may happen that dumping does not work or even fails if such an object is completely destroyed. Therefore, crashes within the RuntimeDump module may occur in problematic contexts.

Example network

The example network is comprised of the following modules:

  • A CoreControl to configure the ML core for correct error and exception handling.
  • An ErrorTest module can be used to create an exception to force the ML error handling system to create a fatal error and to call the dump function.
  • A RuntimeDump module installs the dump function to dump the error causing module (ErrorTest).
  • A Console module in which the error information can be viewed.

If you work in debug mode, be aware that the ML will handle exceptions by executing an abort() statement to initiate the debugger. You need to enable exception handling in the CoreControl module within the Error Handling panel, and you must set On Fatals Error to Continue to allow the ML to continue after exceptions. You can then force an exception in the ErrorTest module by pressing Access NULL Address. The console module will display a fatal error message and a dump of the ErrorTest module that caused the error.

Windows

Default Panel

../../../Modules/ML/MLDiagnosis/mhelp/Images/Screenshots/RuntimeDump._default.png

Parameter Fields

Visible Fields

State Info

name: stateInfo, type: String, persistent: no

Shows whether the dump functionality is installed or not or why it could be (un)installed.

Install Dump Function

name: installDumpFunction, type: Bool, default: TRUE

If checked, the module will try install the dump functionality in the ML error handler.

Otherwise, it will try to uninstall it. The success will be reported in State Info as well as failures.