Skip to main content

Module hooks

Module hooks 

Source
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,

  1. raises the cancellation error when the token of the request or task currently executing is cancelled,
  2. calls the callbacks registered with add_hook, each at its own HookTriggers,
  3. 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§

CancelConfig
Cancellation settings of a VM. Set with configure.
HookId
Handle of a callback registered with add_hook.

Functions§

add_hook
Register a hook callback on an isle’s VM.
config
The cancellation settings of a VM.
configure
Set the cancellation settings of a VM.
install
Install (or re-install) the isle hook on lua.
remove_hook
Remove a callback registered with add_hook. Returns whether it was registered.