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
//! 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.
//!
//! # Removed in 0.9.0
//!
//! The in-thread API of 0.7, deprecated in 0.8.0, is removed. Each old
//! name and its `runtime` replacement:
//!
//! | 0.7 (removed) | since 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`] |
//! | `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;
/// 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