Skip to main content

Module runtime

Module runtime 

Source
Expand description

Running Lua on a VM you own: the in-thread layer of the crate.

The crate has two layers. The actors (Isle, AsyncIsle, the pools) put a VM on a thread of their own and take requests over channels. This module is the layer underneath: a host that owns the Lua and drives the executor itself (its own thread and LocalSet) uses it directly, and the actors are built on it.

Vm is the entry point: Vm::attach takes over the VM’s debug hook, stores its Config and creates the task library. The hook part (attach, of, config, set_config, add_hook, remove_hook) is always available; Vm::run, Vm::task_lib, cancellable and current_scope need the tokio feature. With it, setup is three calls (see Vm::run for the full example):

let vm = Vm::attach(&lua, Config { grace: Duration::from_secs(1), ..Default::default() })?;
lua.globals().set("task", vm.task_lib()?)?;
let out = local.run_until(vm.run(&token, main, ())).await?;

§Contracts

  1. When run resolves, nothing the root started is alive. This holds for Lua tasks (task.spawn) and for host tasks spawned through the scope (current_scope() then ScopeHandle::spawn_local), transitively and in any mix, whether the root finished or was cancelled. A host task that ignores its token is dropped when the grace ends. Tasks spawned into a scope that is already ending share its remaining time; a spawn after the remaining time is gone starts nothing. The layer does not drain the host’s LocalSet: a spawn_local that bypasses the scope (for example current_token().child_token() plus a bare tokio::task::spawn_local) is cancelled with the request but is neither waited for nor dropped, and is the host’s responsibility. This holds when run is awaited to the end: dropping the run future instead only schedules the tasks for abort, and a task in a CPU loop blocks run until it yields, which without Config::preempt_every it never does.
  2. One error type, IsleError, on this layer and on the actors, with one payload for a Lua error: IsleError::Lua carries a LuaFailure (kind, message as Lua prints it, traceback, and with the serde feature the raised value as JSON), built on the VM thread from the raised value, the same for run and for every actor request. A cancel is IsleError::Cancelled, recognised by value: the cancel error is mlua::Error::external(Cancelled), found by downcast, never by message.
  3. The layer owns the VM’s debug hook. Register callbacks with Vm::add_hook, never with Lua::set_hook / Lua::set_global_hook, which replace the hook and stop cancellation (see Hooks).
  4. One Config per VM, read and written through Vm (Vm::config, Vm::set_config; a second Vm::attach replaces it).
  5. Cancellation is a token the host creates and passes to run; run spawns nothing and returns no handle. Ctrl-C, a timeout or a hook callback cancel that CancelToken.

Two requirements on the VM itself: attach it before sandboxing its globals (the first Vm::attach captures xpcall), and keep mlua’s default LuaOptions::catch_rust_panics = true, whose xpcall is yieldable (with false every yield in a run root fails; see Vm::attach).

Host functions called from Lua reach the running request or task through the context functions, which read a thread-local and so take no receiver: current_token, cancellable and current_scope.

§Hooks

Lua has one hook slot per thread, and mlua’s hook setters replace whatever was there, so the layer owns the VM’s hook: Vm::attach installs a single global hook (one callback shared by every thread of the VM, including coroutines the Lua code creates) that, in order,

  1. raises the cancellation error (Cancelled) when the token of the request or task currently executing is cancelled (checked every 1000 instructions),
  2. calls the callbacks registered with Vm::add_hook, each at its own HookTriggers,
  3. yields the running root coroutine or task every N checks when preemption is enabled (Config::preempt_every).

Calling Lua::set_hook, Lua::set_global_hook or mlua::Thread::set_hook on the VM replaces this hook, and cancellation stops working. The hook is re-installed when a set_hook replacement is noticed (at the start of every actor request and of every Vm::run), but a replacement through set_global_hook cannot be detected.

§The task library

Vm::task_lib (tokio feature) returns the VM’s task table, conventionally set as the global task:

Luameaning
task.spawn(f, ...)Start f(...) as a concurrent task of the current coroutine request or task. Returns a handle.
h:join()Wait for the task. Returns true, ... (what f returned) or false, err, where err is the raw Lua error value, or task.CANCELLED if the task was cancelled. A handle can be joined once.
h:cancel()Request cancellation. Does not wait.
h:done()Whether the task has finished.
local h <close> = task.spawn(...)On scope exit, a task that was not joined is cancelled and waited for.
task.is_cancelled(err)Whether err is a cancellation: the error a cancel raises (caught with pcall, or received by a __close handler) or task.CANCELLED. false for any other value.
task.CANCELLEDWhat join returns as err for a cancelled task.

Tasks are structured: when a coroutine request or task finishes, the tasks it spawned and did not join are cancelled, and it waits for them before its own result is delivered. Cancelling a request or task cancels all of its tasks (their tokens are children of its token, see CancelToken::child_token), and the cancelled request or task still resolves only after they, and their own tasks, have finished or been dropped. The grace is one deadline for the whole tree: a task spawned during cleanup gets the time that remains, not a fresh grace period.

task.spawn works inside Vm::run, inside coroutine requests (AsyncIsle::coroutine_eval / coroutine_call) and inside tasks (including host tasks). Sync requests (eval / call / exec) cannot await, so task.spawn raises an error there.

A cancel reaches Lua code as an error: the cancel hook raises it while Lua code runs, and an async host function wrapped with cancellable returns it while the coroutine awaits. Its value is mlua::Error::external(Cancelled) (a userdata to Lua); task.is_cancelled(err) is the test, and it is also true for task.CANCELLED, so one predicate covers both:

local ok, err = pcall(sleep, 1000)
if not ok and task.is_cancelled(err) then
  -- cancelled: clean up and let the cancel continue
  error(err, 0)
end

The predicate lives in the library: a VM that runs without the task table has no task.is_cancelled; Rust code tests an mlua::Error with e.downcast_ref::<Cancelled>().

A task that runs a CPU loop never yields on its own, so a sibling on the same thread cannot run to cancel it; enable Config::preempt_every for that. Cancelling from another thread (an AsyncTask handle) works without it.

§Host tasks

A host function that starts work of its own takes the scope of the running request or task with current_scope() and spawns into it with ScopeHandle::spawn_local. Such a task is structured like a Lua task: it is cancelled when the request or task ends or is cancelled, gets the grace (one deadline for the whole tree), is dropped when the grace ends, and is waited for. Take the handle in the synchronous part of the host function (the create_function body, or a create_async_function body before its first .await) and move it into the future; current_scope() is Some only while a coroutine request or task is being polled, so it is None in a sync request. spawn_local returns a ScopedTask; there are three ways to let go of it: await it (wait for the value), keep it for as long as the task should run (dropping it cancels the task now), or detach() it (fire and forget: the task runs on without a handle and is still cancelled, given the grace, dropped and waited for when the scope ends).

let bg = lua.create_function(|_, ()| {
    let scope = current_scope().expect("inside a coroutine request");
    scope.spawn_local(async move { /* host work */ }).detach();
    Ok(())
})?;

Structs§

CancelToken
Cancellation signal shared between caller and Lua thread.
Cancelled
The error a cancellation raises in Lua.
Config
Settings of a VM. One per VM, read and written through Vm (Vm::attach, Vm::config, Vm::set_config).
HookId
Handle of a callback registered with Vm::add_hook.
LuaFailure
A Lua error, as it crosses from the VM thread to Rust.
Vm
The in-thread handle of a Lua VM run by this crate.

Enums§

IsleError
Errors returned by Isle operations.
LuaErrorKind
What kind of Lua error a LuaFailure is.

Functions§

current_token
Token of the request or task currently executing on this thread.