Expand description
The Lua debug hook of an isle, shared between cancellation and user callbacks.
Lua has one hook slot per thread, and mlua’s hook setters replace
whatever was there. An isle therefore owns the VM’s hook: it
installs a single global hook (mlua::Lua::set_global_hook)
whose callback, in order,
- raises the cancellation error when the token of the request or task currently executing is cancelled,
- calls the callbacks registered with
add_hook, each at its ownHookTriggers, - yields the running task every N instruction checks when
preemption is enabled (see
CancelConfig::preempt_every).
A global hook is used because a per-thread hook does not reach
coroutines created from Lua (coroutine.create / coroutine.wrap):
Lua copies the C hook into the new thread, but mlua finds no
callback registered for that thread and removes the hook the first
time it fires. The global hook’s callback is shared by every thread
of the VM.
§Do not set hooks directly
Calling mlua::Lua::set_hook, mlua::Lua::set_global_hook or
mlua::Thread::set_hook on an isle’s VM replaces this hook, and
cancellation stops working. Register callbacks with add_hook
instead. An isle re-installs its hook when it notices that
set_hook replaced it (checked at the start of every request), but
a replacement through set_global_hook cannot be detected.
Structs§
- Cancel
Config - Cancellation settings of a VM. Set with
configure. - HookId
- Handle of a callback registered with
add_hook.