Skip to main content

Crate mlua_isle

Crate mlua_isle 

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

  1. Lua is !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 without Send issues.

  2. 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, AsyncIsle and the pools put a VM on a thread of their own; Send handles send requests over channels.
  • The in-thread layer (runtime): for a host that owns the mlua::Lua and drives the executor itself. runtime::Vm owns the VM’s debug hook, its runtime::Config (cancel grace, preemption) and the task library, and runs a root coroutine under a CancelToken (Vm::run, tokio feature).

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.70.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::configVm::set_config / Vm::config
hooks::add_hook / hooks::remove_hookVm::add_hook / Vm::remove_hook
hooks::CancelConfigruntime::Config (the old name is an alias)
hooks::HookIdruntime::HookId
tasks::install(lua) (tokio)Vm::attach(lua, config)?.task_lib() (tokio)
the hooks / tasks modulesruntime

§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§

hooksDeprecated
Deprecated: the hook API moved to runtime::Vm.
runtime
Running Lua on a VM you own: the in-thread layer of the crate.

Structs§

CancelToken
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§

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

Functions§

current_tokenDeprecated
Token of the request or task currently executing on this thread. Forwards to runtime::current_token.