1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
//! 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
//!
//! ```text
//! ┌─────────────────┐ 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.7 | 0.8 |
//! |---|---|
//! | `run_root(lua, token, f, args)` | [`Vm::attach`](runtime::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)`](runtime::Vm::attach) |
//! | `hooks::configure` / `hooks::config` | [`Vm::set_config`](runtime::Vm::set_config) / [`Vm::config`](runtime::Vm::config) |
//! | `hooks::add_hook` / `hooks::remove_hook` | [`Vm::add_hook`](runtime::Vm::add_hook) / [`Vm::remove_hook`](runtime::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
//!
//! ```rust
//! 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();
//! ```
pub use ;
pub use Isle;
pub use CancelToken;
pub use Task;
pub use ;
pub use ;
pub use ;
pub use AsyncTask;
/// Token of the request or task currently executing on this thread.
/// Forwards to [`runtime::current_token`].
/// Make an async host function's future stop when the calling request
/// or task is cancelled. Forwards to `runtime::cancellable`.
pub async
/// Run `func(args)` as a root coroutine under `token`. Forwards to
/// [`Vm::run`](runtime::Vm::run) on the VM's [`Vm`](runtime::Vm),
/// attaching it with its stored config first if it is not attached.
///
/// Migration: `Vm::attach(&lua, config)?` once, then
/// `vm.run(&token, func, args).await`.
///
/// # Errors
///
/// As [`Vm::run`](runtime::Vm::run), plus the error of
/// [`Vm::attach`](runtime::Vm::attach) when the VM was not attached.
pub async
/// The work of one request, run on the VM thread.
///
/// A job owns everything its request needs: the code or the arguments,
/// and the typed sender its result goes back through. It converts the
/// result on the VM thread (`FromLuaMulti`, or the `exec` closure's own
/// `T`) and sends a `Send` value, so the request type needs no type
/// parameter. A coroutine job `spawn_local`s its future and returns.
pub type Job = ;
/// Request sent from a handle ([`Isle`], `AsyncIsle`) to the VM thread.
pub