Quirrel4.41.0

debug.setdebughook

Defined in module "debug"
from "debug" import setdebughook
setdebughook(hook: function|null)

Installs the given function as the VM debug hook; null clears it

examples/debug/setdebughook-basic.nut
from "debug" import setdebughook

local calls = 0
setdebughook(function(_kind, _src, _line, _name) { calls += 1 })

// a fresh thread call gives the hook a call boundary; this top-level script,
// already running, would not be seen
let worker = newthread(function() { return 1 })
worker.call()
setdebughook(null)

println("calls > 0 =", calls > 0)
Output:
calls > 0 = true

Parameters

hookfunction|nullcalled as hook(kind, src, line, funcname) on call, line, and return events; null clears the hook

Notes

kind is the event's character code, not a one-character string: 'c' for a call, 'l' for a line, 'r' for a return.

The check for whether to call the hook is compiled into a call's own frame when that call begins, so installing the hook takes effect only for calls that start afterward. A call already running when setdebughook runs, including the script that just called setdebughook, keeps executing without it.

While the hook itself runs, the VM does not call it again for the hook's own call and line events, so a hook that runs script code cannot recurse into itself.

Example

examples/debug/setdebughook.nut
from "debug" import setdebughook

let counts = {}
setdebughook(function(kind, src, line, name) {
  if (kind in counts) counts[kind] = counts[kind] + 1
  else counts[kind] <- 1
})

// a fresh thread call gives the hook a call boundary that starts after it was
// installed; this whole top-level script, already running, would not be seen
let co = newthread(function(a, b) { return a + b })
co.call(1, 2)

setdebughook(null)
println("calls:", counts['c'])
println("returns:", counts['r'])
Output:
calls: 1
returns: 1

See also

seterrorhandlerInstalls the given function as the VM error handler; null clears it
debugmodule index