File MIES_Debugging.ipf

Holds functions for handling debugging information.

Functions

static variable FindFirstOutsideCaller(string *func, string *line, string *file)

Return the first function from the stack trace not located in this file.

variable DEBUGPRINTv(variable var, string format = defaultValue)

Output debug information and return the parameter var.

Debug function especially designed for usage in return statements.

For example calling the following function

Function doStuff()
    variable var = 1 + 2
    return DEBUGPRINTv(var)
End

will output

DEBUG doStuff(...)#L5: return value 3
to the history.

Parameters:
  • var – numerical argument for debug output

  • format – optional format string to override the default of “%g”

wave DEBUGPRINTw(WaveOrNull wv, string format = defaultValue)

Output debug information and return the wave wv.

Debug function especially designed for usage in return statements.

For example calling the following function

Function/WAVE doStuff()
    Make/D/N=5 data = p
    return DEBUGPRINTw(data)
End

will output

DEBUG doStuff(...)#L5: return value {0, 1, 2, 3, 4}
to the history.

Parameters:
  • wv – wave argument for debug output

  • format – optional format string to override the default of “%g”

string DEBUGPRINTs(string str, string format = defaultValue)

Output debug information and return the parameter str.

Debug function especially designed for usage in return statements.

For example calling the following function

Function/s doStuff()
    variable str= "a" + "b"
    return DEBUGPRINTs(str)
End

will output
DEBUG doStuff(...)#L5: return value ab
to the history.

Parameters:
  • str – string argument for debug output

  • format – optional format string to override the default of “%s”

variable DEBUGPRINT(string msg, variable var = defaultValue, string str = defaultValue, WaveOrNull wv = defaultValue, string format = defaultValue)

Generic debug output function.

Outputs variables and strings with optional format argument.

Examples:

DEBUGPRINT("before a possible crash")
DEBUGPRINT("some variable", var=myVariable)
DEBUGPRINT("my string", str=myString)
DEBUGPRINT("Current state", var=state, format="%.5f")

Parameters:
  • msg – descriptive string for the debug message

  • var – variable

  • str – string

  • wv – wave (can be null)

  • format – format string overrides the default of “%g” for variables and “%s” for strings

variable DEBUGPRINT_TS(string msg, variable var = defaultValue, string str = defaultValue, string format = defaultValue)

Generic debug output function (threadsafe variant)

Outputs variables and strings with optional format argument.

Examples:

DEBUGPRINT("before a possible crash")
DEBUGPRINT("some variable", var=myVariable)
DEBUGPRINT("my string", str=myString)
DEBUGPRINT("Current state", var=state, format="%.5f")

Parameters:
  • msg – descriptive string for the debug message

  • var – variable

  • str – string

  • format – format string overrides the default of “%g” for variables and “%s” for strings

variable DEBUGPRINTSTACKINFO()

Print a nicely formatted stack trace to the history.

static variable CreateHistoryLog()

Creates a notebook with the special name “HistoryCarbonCopy” which will hold a copy of the history

static variable SaveHistoryLog()

Save the contents of the history notebook on disk in the same folder as this experiment as timestamped file “run_*_*.log”

variable DEBUGPRINT_OR_ABORT(string msg)

Prints a message to the command history in debug mode, aborts with dialog in release mode.

variable DEBUG_TIMER_START()

Start a timer for performance measurements.

Usage:

variable referenceTime = DEBUG_TIMER_START()
// part one to benchmark
DEBUGPRINT_ELAPSED(referenceTime)
// part two to benchmark
DEBUGPRINT_ELAPSED(referenceTime)

variable DEBUGPRINT_ELAPSED(variable referenceTime)

Print the elapsed time for performance measurements in seconds.

variable DEBUGPRINT_ELAPSED_WAVE(variable referenceTime)

Print and store the elapsed time for performance measurements.

variable EnableDebugMode()

Enable debug mode.

variable DisableDebugMode()

Disable debug mode.

variable EnableEvilMode()

Enable evil mode.

variable DisableEvilMode()

Disable evil mode.

variable DisableThreadsafeSupport()

Disable threadsafe support.

variable EnableThreadsafeSupport()

Enable threadsafe support again (default on IP startup)

variable DisableWaveCache()

Disable wave caching support.

variable EnableWaveCache()

Enable wave caching support again.

variable EnableDangerousDebugging()

Enable dangerous debugging (allows to call user-defined functions in the debugger)

static variable ReportBugToLogfile(string msg, WaveTextOrNull keys, WaveTextOrNull values)
variable BUG(string msg, WaveText keys = defaultValue, WaveText values = defaultValue)

Complain and ask the user to report the error.

In nearly all cases ASSERT() is the more appropriate method to use.

If a testcase wants to trigger a BUG message and needs to treat that as non-fatal, it needs to set bugCount to NaN before.

variable BUG_TS(string msg, WaveText keys = defaultValue, WaveText values = defaultValue)

Threadsafe variant of BUG()

variable GetSizeOfAllWavesInExperiment()

Debug helper which creates a textwave which will hold the names of all waves and their size in MiB.

variable CheckAllDimensionLabels()

Check that all stored waves (permanent and free) adhere to the liberal naming rules.

These are only enforced since IP9 beta9 or later.

Returns:

Number of waves not matching

static string CheckDimensionLabels(WaveOrNull wv)
variable DEBUG_STOREFUNCTION()

Variables

static const string functionReturnMessage = "return value"