# mlua-isle
Thread-isolated Lua VM with cancellation and async bridge for [mlua](https://crates.io/crates/mlua).
## Problem
`mlua::Lua` is `!Send` — it cannot cross thread boundaries. This makes it
difficult to use from async runtimes, UI threads, or any multi-threaded context.
**mlua-isle** solves this by confining the Lua VM to a dedicated thread and
communicating via channels.
## Features
- **Thread isolation** — Lua VM runs on a dedicated thread; callers interact
via a `Send + Sync` handle
- **Cancellation** — long-running Lua code can be interrupted via `CancelToken`
using a Lua debug hook
- **Sync API** — blocking `Isle` handle with `Task<T>` for non-blocking usage
- **Async API** (optional, `tokio` feature) — `AsyncIsle` handle with
Handle/Driver separation, bounded channel backpressure, and `AsyncTask<T>`
which implements `Future`
- **Coroutine execution** (optional, `tokio` feature) — cooperative
multitasking via `coroutine_eval` / `coroutine_call`. Multiple Lua
coroutines share the same VM and yield when awaiting async Rust functions
- **Connection pool** (optional, `pool` feature) — `IslePool` manages
multiple `Isle` instances with checkout/return semantics. Supports
`Cold` (fresh VM) and `Warm` (reuse) strategies
- **Async connection pool** (optional, `pool` + `tokio` features) —
`AsyncIslePool` is the async counterpart of `IslePool`: `checkout` /
`try_checkout` / `checkout_timeout` are async, idle wait uses
`tokio::sync::Notify`, and each slot owns both an `AsyncIsle` handle
and its `AsyncIsleDriver` so VMs can be joined on shutdown
- **Channels and select** (optional, `tokio` feature) — Lua tasks pass
values through `task.channel` (buffered or rendezvous) and wait on several
sources at once with `task.select` (receive, send, timer, task-finish
cases); `runtime::channel` feeds a running Lua loop from a `Send` Rust
task, with request / reply, and `runtime::channel_to_host` hands values
from Lua back to one
- **Typed errors** — one error type, `IsleError`; a Lua error arrives as
`IsleError::Lua(LuaFailure)` with its kind, message, traceback and
(`serde` feature) the raised value, and a cancel is recognised by value
- **Zero unsafe in user code** — both `Isle` and `AsyncIsle` are safe to
share across threads
## Architecture
### Sync (`Isle`)
```text
┌─────────────────┐ std mpsc ┌──────────────────┐
│ caller thread │──────────►│ Lua thread │
│ │ │ (mlua confined) │
│ Isle handle │◄──────────│ │
│ │ oneshot │ Lua VM + hook │
└─────────────────┘ └──────────────────┘
```
### Async (`AsyncIsle`, requires `tokio` feature)
```text
┌──────────────────┐ ┌──────────────────┐
│ tokio tasks │ tokio mpsc │ Lua thread │
│ │──────────────►│ (mlua confined) │
│ AsyncIsle handle │ (bounded, │ │
│ (Clone, no Arc) │ backpressure)│ Lua VM + hook │
│ │◄──────────────│ │
│ │ oneshot │ │
├──────────────────┤ │ │
│ AsyncIsleDriver │───done_tx────►│ │
│ (lifecycle owner)│ └──────────────────┘
└──────────────────┘
```
- **Handle** (`AsyncIsle`) — lightweight, cloneable. Share across tasks
without `Arc`.
- **Driver** (`AsyncIsleDriver`) — sole lifecycle owner. Call
`shutdown().await` for clean thread join, or drop to let the channel-close
mechanism terminate the thread naturally.
## Usage
Add to your `Cargo.toml`:
```toml
[dependencies]
mlua-isle = "0.10"
# For async support (includes coroutine execution):
# mlua-isle = { version = "0.10", features = ["tokio"] }
# For connection pool:
# mlua-isle = { version = "0.10", features = ["pool"] }
# Both:
# mlua-isle = { version = "0.10", features = ["tokio", "pool"] }
# The value a Lua error raised, as JSON, on `LuaFailure::value`:
# mlua-isle = { version = "0.10", features = ["serde"] }
```
### Sync API
```rust
use mlua_isle::Isle;
Ok(())
}).unwrap();
let result: String = isle.eval("return greeting").unwrap();
assert_eq!(result, "hello");
isle.shutdown().unwrap();
```
### Async API
```rust
# #[tokio::main]
# async fn main() -> Result<(), Box<dyn std::error::Error>> {
use mlua_isle::AsyncIsle;
Ok(())
}).await?;
// Clone freely — no Arc needed.
let isle2 = isle.clone();
let result: String = isle.eval("return greeting").await?;
assert_eq!(result, "hello");
driver.shutdown().await?;
# Ok(())
# }
```
### Typed results and arguments
A request converts its result on the VM thread and hands back a `Send`
value of the type you ask for (`T: FromLuaMulti + Send + 'static`), so
nothing is flattened to a string on the way:
```rust
use mlua_isle::Isle;
function count(...) return select('#', ...) end").exec()
}).unwrap();
let n: i64 = isle.eval("return 1 + 1").unwrap(); // 2
let pair: (i64, bool) = isle.eval("return 1, true").unwrap(); // several return values
let none: Option<String> = isle.eval("return nil").unwrap(); // `nil` is `None`
isle.eval::<()>("counter = 0").unwrap(); // ignore the result
// Arguments are `IntoLuaMulti`: a tuple keeps each value's Lua type.
let (d, f, s): (i64, bool, String) = isle.call("info", (21, true, "x")).unwrap();
assert_eq!((n, pair, none, d, f, s.as_str()), (2, (1, true), None, 42, false, "x"));
// A run-time number of arguments: `Variadic` (a `Vec` is one argument, a table).
let args = mlua::Variadic::from_iter(["a", "b"].map(String::from));
let count: i64 = isle.call("count", args).unwrap();
assert_eq!(count, 2);
isle.shutdown().unwrap();
```
A value that does not convert is `IsleError::Lua` with kind
`LuaErrorKind::Conversion`. The conversions are mlua's own: a number
converts to `String`, `bool` is Lua truthiness, and `mlua::BString` holds
the raw bytes of a Lua string (UTF-8 or not). A `FromLua` of your own
that fails with an error raised by Lua code it runs is `IsleError::Lua`
with that error's kind. `Table`, `Function`, `Value` and `MultiValue`
hold references into the VM and, without mlua's `send` feature, are not
`Send`, so asking for them does not compile. Convert them inside `exec`,
whose closure returns any `T: Send + 'static` as is, or ask for a
`mlua::RegistryKey` (which is `Send`) and read the value in a later
`exec`:
```rust
use mlua_isle::Isle;
`AsyncTask<T>`), and so do the coroutine requests.
### Coroutine execution (async)
```rust
# #[tokio::main]
# async fn main() -> Result<(), Box<dyn std::error::Error>> {
use mlua_isle::AsyncIsle;
lua.globals().set("sleep_ms", lua.create_async_function(|_, ms: u64| async move {
tokio::time::sleep(std::time::Duration::from_millis(ms)).await;
Ok(())
})?)?;
Ok(())
}).await?;
// Multiple coroutines share the same VM cooperatively
let t1 = isle.spawn_coroutine_eval::<String>("sleep_ms(10) return 'a'");
let t2 = isle.spawn_coroutine_eval::<String>("sleep_ms(10) return 'b'");
let (r1, r2) = tokio::join!(t1, t2);
assert_eq!(r1?, "a");
assert_eq!(r2?, "b");
driver.shutdown().await?;
# Ok(())
# }
```
### Connection pool
```rust
use mlua_isle::{IslePool, PoolConfig, PoolStrategy};
let pool = IslePool::new(
|lua| {
lua.globals().set("greeting", "hello")?;
Ok(())
},
PoolConfig {
max_size: 4,
strategy: PoolStrategy::Warm,
},
).unwrap();
{
let isle = pool.checkout().unwrap();
let result: String = isle.eval("return greeting").unwrap();
assert_eq!(result, "hello");
} // isle returned to pool automatically
pool.shutdown();
```
### Cancellation (sync)
```rust
use mlua_isle::Isle;
use std::time::Duration;
use std::thread;
thread::sleep(Duration::from_millis(50));
task.cancel();
let result = task.wait();
assert!(result.is_err()); // IsleError::Cancelled
```
### Cancellation (async)
```rust
# #[tokio::main]
# async fn main() -> Result<(), Box<dyn std::error::Error>> {
use mlua_isle::AsyncIsle;
use std::time::Duration;
tokio::spawn(async move {
tokio::time::sleep(Duration::from_millis(100)).await;
token.cancel();
});
let result = task.await; // Err(Cancelled)
assert!(result.is_err());
driver.shutdown().await?;
# Ok(())
# }
```
Dropping a `Task` / `AsyncTask` before it resolves cancels the operation.
Call `.detach()` to let it run without keeping the handle.
### Structured tasks (async)
`vm.task_lib()` gives Lua code a `task` library. Tasks are structured:
cancelling a request cancels every task it spawned (and theirs), and a
request, whether it finishes or is cancelled, does not resolve before
the tasks it did not join have been cancelled and have finished or been
dropped. The cancel grace period is one deadline for the request and
all of its tasks. Host code joins the same structure through
`runtime::current_scope()` (see [Host tasks](#host-tasks-in-the-requests-scope)).
Dropping a `vm.run` future (rather than cancelling its token and
awaiting it) only schedules its tasks for abort.
```rust
# #[tokio::main]
# async fn main() -> Result<(), Box<dyn std::error::Error>> {
use mlua_isle::runtime::{cancellable, Config, Vm};
use mlua_isle::AsyncIsle;
use std::time::Duration;
// A cancelled coroutine may run its cleanup for up to 100 ms.
grace: Duration::from_millis(100),
// Yield CPU-bound tasks so that siblings can run and cancel them.
preempt_every: Some(1),
})?;
// `?` converts `IsleError` into the closure's `mlua::Error`.
lua.globals().set("task", vm.task_lib()?)?;
// `cancellable` turns a cancel into a Lua error at this await point,
// so `__close` handlers of the coroutine run and may await.
let sleep = lua.create_async_function(|_, ms: u64| {
cancellable(async move {
tokio::time::sleep(Duration::from_millis(ms)).await;
Ok(())
})
})?;
lua.globals().set("sleep", sleep)
})
.await?;
let r: String = isle
.coroutine_eval(
r#"
local a = task.spawn(function() sleep(10) return "a" end)
local b = task.spawn(function() error({ code = 42 }) end)
local _, va = a:join() -- true, "a"
local _, err = b:join() -- false, { code = 42 }
local slow <close> = task.spawn(function() sleep(10000) end)
return va .. err.code -- `slow` is cancelled and awaited here
"#,
)
.await?;
assert_eq!(r, "a42");
driver.shutdown().await?;
# Ok(())
# }
```
The isle owns the VM's Lua debug hook. Register your own hook callbacks
with `vm.add_hook` rather than `Lua::set_hook`, which would replace
the cancel hook. The config can also be set without the init closure,
through `AsyncIsle::builder().config(..)`.
### Channels and select (async)
With the `task` library, Lua tasks pass values through channels and wait
on several sources with `task.select`; the host feeds a running Lua loop
through `runtime::channel` and receives from it through
`runtime::channel_to_host`. The contracts (ordering, closing, delivery
under cancellation, rendezvous channels, requests) are in the `runtime`
module docs.
```rust
# #[tokio::main]
# async fn main() -> Result<(), Box<dyn std::error::Error>> {
use mlua_isle::runtime::{channel, channel_to_host, Config, Vm};
use mlua_isle::AsyncIsle;
let (isle, driver, (events, mut reports)) = AsyncIsle::builder()
.spawn_with(|lua| {
let vm = Vm::attach(lua, Config::default())?;
lua.globals().set("task", vm.task_lib()?)?;
let (events, inbox) = channel::<String>(lua, 16)?;
let (outbox, reports) = channel_to_host::<String>(lua, 16)?;
lua.globals().set("inbox", inbox)?;
lua.globals().set("outbox", outbox)?;
Ok((events, reports))
})
.await?;
let main = isle.spawn_coroutine_eval::<()>(
r#"
while true do
local stop = task.select({
inbox:on(function(ev, ok)
if not ok then return true end -- the host dropped its Sender
outbox:send("got " .. ev)
return false
end),
task.after(1000):on(function()
outbox:send("idle")
return false
end),
})
if stop then return end
end
"#,
);
events.send("a".to_string()).await?;
assert_eq!(reports.recv().await.as_deref(), Some("got a"));
drop(events); // closes `inbox`: the loop returns
main.await?;
driver.shutdown().await?;
# Ok(())
# }
```
### Errors
Every function returns `IsleError`. A Lua error of a request or root is
`IsleError::Lua(LuaFailure)`, built on the VM thread from the raised
value, the same on every path (`Isle`, `AsyncIsle` sync and coroutine
requests, `Vm::run`):
```rust
use mlua_isle::{Isle, IsleError, LuaErrorKind};
use mlua_isle::runtime::{CancelToken, Config, Vm};
use std::time::Duration;
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?;
```
`vm.run` resolves only after every task the root started has ended (Lua
tasks, and host tasks spawned through `current_scope()`, below), and
returns `Err(IsleError::Cancelled)` once `token` is cancelled (Ctrl-C,
a timeout, a hook callback). The `task` table is never set as a global
by the crate. `vm.config()` / `vm.set_config()` read and write the one
`Config` of the VM, and `vm.add_hook` registers hook callbacks next to
the cancel check. An `AsyncIsle` takes the same `Config` through
`AsyncIsle::builder().config(..)`; the pools have no such setting yet,
so configure their VMs from the factory closure.
### Host tasks in the request's scope
A host function that starts work of its own spawns it into the scope of
the running request or task. The task is then structured like a
`task.spawn` task: it is cancelled when the request ends or is
cancelled, gets the grace (the same deadline as the rest of the tree),
is dropped when the grace ends even if it never looks at its token, and
the request resolves only after it is gone. This works on the
`AsyncIsle` path and on `vm.run`.
```rust
use mlua_isle::runtime::current_scope;