mlua_isle/lib.rs
1//! Thread-isolated Lua VM with cancellation for mlua.
2//!
3//! `mlua-isle` runs a Lua VM on a dedicated thread and communicates via
4//! channels. This solves two fundamental problems with mlua:
5//!
6//! 1. **`Lua` is `!Send`** — it cannot cross thread boundaries. By
7//! confining the VM to one thread and sending requests over a channel,
8//! callers on any thread (UI, async runtime, etc.) can interact with
9//! Lua without `Send` issues.
10//!
11//! 2. **Cancellation** — long-running Lua code (including blocking Rust
12//! callbacks like HTTP calls) can be interrupted via a cancel token
13//! that triggers both a Lua debug hook and a caller-side signal.
14//!
15//! # Architecture
16//!
17//! ```text
18//! ┌─────────────────┐ mpsc ┌──────────────────┐
19//! │ caller thread │─────────►│ Lua thread │
20//! │ (UI / async) │ │ (mlua confined) │
21//! │ │◄─────────│ │
22//! │ Isle handle │ oneshot │ Lua VM + hook │
23//! └─────────────────┘ └──────────────────┘
24//! ```
25//!
26//! # Example
27//!
28//! ```rust
29//! use mlua_isle::Isle;
30//!
31//! let isle = Isle::spawn(|lua| {
32//! lua.globals().set("greeting", "hello")?;
33//! Ok(())
34//! }).unwrap();
35//!
36//! let result: String = isle.eval("return greeting").unwrap();
37//! assert_eq!(result, "hello");
38//!
39//! isle.shutdown().unwrap();
40//! ```
41
42mod error;
43mod handle;
44mod hook;
45pub mod hooks;
46#[cfg(feature = "pool")]
47mod pool;
48mod task;
49mod thread;
50
51#[cfg(feature = "tokio")]
52mod async_isle;
53#[cfg(all(feature = "pool", feature = "tokio"))]
54mod async_pool;
55#[cfg(feature = "tokio")]
56mod async_task;
57#[cfg(feature = "tokio")]
58mod scope;
59#[cfg(feature = "tokio")]
60pub mod tasks;
61
62pub use error::IsleError;
63pub use handle::Isle;
64pub use hook::{current_token, CancelToken};
65#[cfg(feature = "tokio")]
66pub use scope::{cancellable, run_root};
67pub use task::Task;
68
69#[cfg(feature = "pool")]
70pub use pool::{IslePool, PoolConfig, PoolStrategy, PooledIsle};
71
72#[cfg(feature = "tokio")]
73pub use async_isle::{AsyncIsle, AsyncIsleBuilder, AsyncIsleDriver};
74#[cfg(all(feature = "pool", feature = "tokio"))]
75pub use async_pool::{AsyncIslePool, AsyncPooledIsle};
76#[cfg(feature = "tokio")]
77pub use async_task::AsyncTask;
78
79/// Type alias for exec closures to keep the `Request` enum readable.
80pub(crate) type ExecFn = Box<dyn FnOnce(&mlua::Lua) -> Result<String, IsleError> + Send>;
81
82/// Channel sender for results.
83pub(crate) type ResultTx = std::sync::mpsc::Sender<Result<String, IsleError>>;
84
85/// Request sent from caller to the Lua thread.
86pub(crate) enum Request {
87 /// Evaluate a Lua chunk and return the result as a string.
88 Eval {
89 code: String,
90 cancel: CancelToken,
91 tx: ResultTx,
92 },
93 /// Call a named global function with string arguments.
94 Call {
95 func: String,
96 args: Vec<String>,
97 cancel: CancelToken,
98 tx: ResultTx,
99 },
100 /// Execute an arbitrary closure on the Lua thread.
101 Exec {
102 f: ExecFn,
103 cancel: CancelToken,
104 tx: ResultTx,
105 },
106 /// Graceful shutdown.
107 Shutdown,
108}