Expand description
Thread-isolated Lua VM with cancellation for mlua.
mlua-isle runs a Lua VM on a dedicated thread and communicates via
channels. This solves two fundamental problems with mlua:
-
Luais!Send— it cannot cross thread boundaries. By confining the VM to one thread and sending requests over a channel, callers on any thread (UI, async runtime, etc.) can interact with Lua withoutSendissues. -
Cancellation — long-running Lua code (including blocking Rust callbacks like HTTP calls) can be interrupted via a cancel token that triggers both a Lua debug hook and a caller-side signal.
§Architecture
┌─────────────────┐ mpsc ┌──────────────────┐
│ caller thread │─────────►│ Lua thread │
│ (UI / async) │ │ (mlua confined) │
│ │◄─────────│ │
│ Isle handle │ oneshot │ Lua VM + hook │
└─────────────────┘ └──────────────────┘§Layers
The crate has two layers:
- The actor layer (crate root):
Isle,AsyncIsleand the pools put a VM on a thread of their own;Sendhandles send requests over channels. - The in-thread layer (
runtime): for a host that owns themlua::Luaand drives the executor itself.runtime::Vmowns the VM’s debug hook, itsruntime::Config(cancel grace, preemption) and thetasklibrary, and runs a root coroutine under aCancelToken(Vm::run,tokiofeature).
The actors are built on runtime: each attaches a runtime::Vm
to its VM, and a coroutine request is a Vm::run. The runtime
module docs are the canonical description of the in-thread layer:
its contracts, the hook, and the Lua task library.
§Moved to runtime in 0.8.0
The in-thread API of 0.7 is deprecated; each old name forwards to
its runtime replacement and will be removed in the release after
0.8.0.
| 0.7 | 0.8 |
|---|---|
run_root(lua, token, f, args) | Vm::attach once, then vm.run(&token, f, args) |
cancellable(fut) (root) | runtime::cancellable(fut) |
current_token() (root) | runtime::current_token() |
hooks::install(lua) | Vm::attach(lua, config) |
hooks::configure / hooks::config | Vm::set_config / Vm::config |
hooks::add_hook / hooks::remove_hook | Vm::add_hook / Vm::remove_hook |
hooks::CancelConfig | runtime::Config (the old name is an alias) |
hooks::HookId | runtime::HookId |
tasks::install(lua) (tokio) | Vm::attach(lua, config)?.task_lib() (tokio) |
the hooks / tasks modules | runtime |
§Example
use mlua_isle::Isle;
let isle = Isle::spawn(|lua| {
lua.globals().set("greeting", "hello")?;
Ok(())
}).unwrap();
let result: String = isle.eval("return greeting").unwrap();
assert_eq!(result, "hello");
isle.shutdown().unwrap();Modules§
- hooks
Deprecated - Deprecated: the hook API moved to
runtime::Vm. - runtime
- Running Lua on a VM you own: the in-thread layer of the crate.
Structs§
- Cancel
Token - Cancellation signal shared between caller and Lua thread.
- Cancelled
- The error a cancellation raises in Lua.
- Isle
- Handle to a thread-isolated Lua VM.
- LuaFailure
- A Lua error, as it crosses from the VM thread to Rust.
- Task
- Handle to a pending Lua operation whose result is a
T.
Enums§
- Isle
Error - Errors returned by Isle operations.
- LuaError
Kind - What kind of Lua error a
LuaFailureis.
Functions§
- current_
token Deprecated - Token of the request or task currently executing on this thread.
Forwards to
runtime::current_token.