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
- When
runresolves, nothing the root started is alive. This holds for Lua tasks (task.spawn) and for host tasks spawned through the scope (current_scope()thenScopeHandle::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’sLocalSet: aspawn_localthat bypasses the scope (for examplecurrent_token().child_token()plus a baretokio::task::spawn_local) is cancelled with the request but is neither waited for nor dropped, and is the host’s responsibility. This holds whenrunis awaited to the end: dropping therunfuture instead only schedules the tasks for abort, and a task in a CPU loop blocksrununtil it yields, which withoutConfig::preempt_everyit never does. - One error type,
IsleError, on this layer and on the actors, with one payload for a Lua error:IsleError::Luacarries aLuaFailure(kind, message as Lua prints it, traceback, and with theserdefeature the raised value as JSON), built on the VM thread from the raised value, the same forrunand for every actor request. A cancel isIsleError::Cancelled, recognised by value: the cancel error ismlua::Error::external(Cancelled), found by downcast, never by message. - The layer owns the VM’s debug hook. Register callbacks with
Vm::add_hook, never withLua::set_hook/Lua::set_global_hook, which replace the hook and stop cancellation (see Hooks). - One
Configper VM, read and written throughVm(Vm::config,Vm::set_config; a secondVm::attachreplaces it). - Cancellation is a token the host creates and passes to
run;runspawns nothing and returns no handle. Ctrl-C, a timeout or a hook callback cancel thatCancelToken.
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,
- raises the cancellation error (
Cancelled) when the token of the request or task currently executing is cancelled (checked every 1000 instructions), - calls the callbacks registered with
Vm::add_hook, each at its ownHookTriggers, - 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:
| Lua | meaning |
|---|---|
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.CANCELLED | What 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)
endThe 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§
- Cancel
Token - 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§
- Isle
Error - Errors returned by Isle operations.
- LuaError
Kind - What kind of Lua error a
LuaFailureis.
Functions§
- current_
token - Token of the request or task currently executing on this thread.