mlua_isle/runtime.rs
1//! Running Lua on a VM you own: the in-thread layer of the crate.
2//!
3//! The crate has two layers. The actors ([`Isle`](crate::Isle),
4//! `AsyncIsle`, the pools) put a VM on a thread of their own and take
5//! requests over channels. This module is the layer underneath: a host
6//! that owns the [`Lua`] and drives the executor itself (its own thread
7//! and [`LocalSet`](https://docs.rs/tokio/latest/tokio/task/struct.LocalSet.html))
8//! uses it directly, and the actors are built on it.
9//!
10//! [`Vm`] is the entry point: [`Vm::attach`] takes over the VM's debug
11//! hook, stores its [`Config`] and creates the `task` library. The
12//! hook part (`attach`, `of`, `config`, `set_config`, `add_hook`,
13//! `remove_hook`) is always available; `Vm::run`, `Vm::task_lib`,
14//! `cancellable` and `current_scope` need the `tokio` feature. With
15//! it, setup is three calls (see `Vm::run` for the full example):
16//!
17//! ```text
18//! let vm = Vm::attach(&lua, Config { grace: Duration::from_secs(1), ..Default::default() })?;
19//! lua.globals().set("task", vm.task_lib()?)?;
20//! let out = local.run_until(vm.run(&token, main, ())).await?;
21//! ```
22//!
23//! # Contracts
24//!
25//! 1. **When `run` resolves, nothing the root started is alive.** This
26//! holds for Lua tasks (`task.spawn`) and for host tasks spawned
27//! through the scope (`current_scope()` then
28//! `ScopeHandle::spawn_local`), transitively and in any mix,
29//! whether the root finished or was cancelled. A host task that
30//! ignores its token is dropped when the grace ends. Tasks spawned
31//! into a scope that is already ending share its remaining time; a
32//! spawn after the remaining time is gone starts nothing. The layer
33//! does not drain the host's `LocalSet`: a `spawn_local` that bypasses the
34//! scope (for example `current_token().child_token()` plus a bare
35//! `tokio::task::spawn_local`) is cancelled with the request but is
36//! neither waited for nor dropped, and is the host's
37//! responsibility. This holds when `run` is awaited to the end:
38//! dropping the `run` future instead only schedules the tasks for
39//! abort, and a task in a CPU loop blocks `run` until it yields,
40//! which without [`Config::preempt_every`] it never does.
41//! 2. **One error type**, [`IsleError`], on this layer and on the
42//! actors, with one payload for a Lua error: [`IsleError::Lua`]
43//! carries a [`LuaFailure`] (kind, message as Lua prints it,
44//! traceback, and with the `serde` feature the raised value as
45//! JSON), built on the VM thread from the raised value, the same
46//! for `run` and for every actor request. A cancel is
47//! [`IsleError::Cancelled`], recognised by value: the cancel error
48//! is `mlua::Error::external(`[`Cancelled`]`)`, found by downcast,
49//! never by message.
50//! 3. **The layer owns the VM's debug hook.** Register callbacks with
51//! [`Vm::add_hook`], never with `Lua::set_hook` /
52//! `Lua::set_global_hook`, which replace the hook and stop
53//! cancellation (see [Hooks](#hooks)).
54//! 4. **One [`Config`] per VM**, read and written through [`Vm`]
55//! ([`Vm::config`], [`Vm::set_config`]; a second [`Vm::attach`]
56//! replaces it).
57//! 5. **Cancellation is a token the host creates** and passes to
58//! `run`; `run` spawns nothing and returns no handle. Ctrl-C, a
59//! timeout or a hook callback cancel that [`CancelToken`].
60//!
61//! Two requirements on the VM itself: attach it before sandboxing its
62//! globals (the first [`Vm::attach`] captures `xpcall`), and keep mlua's
63//! default `LuaOptions::catch_rust_panics = true`, whose `xpcall` is
64//! yieldable (with `false` every yield in a `run` root fails; see
65//! [`Vm::attach`]).
66//!
67//! Host functions called from Lua reach the running request or task
68//! through the context functions, which read a thread-local and so take
69//! no receiver: [`current_token`], `cancellable` and `current_scope`.
70//!
71//! # Hooks
72//!
73//! Lua has one hook slot per thread, and mlua's hook setters replace
74//! whatever was there, so the layer owns the VM's hook: [`Vm::attach`]
75//! installs a single **global** hook (one callback shared by every
76//! thread of the VM, including coroutines the Lua code creates) that,
77//! in order,
78//!
79//! 1. raises the cancellation error ([`Cancelled`]) when the token of
80//! the request or task currently executing is cancelled (checked
81//! every 1000 instructions; a check that lands in the code mlua uses
82//! to return an async host function's results is deferred, see
83//! [Channels, timers and select](#channels-timers-and-select)),
84//! 2. calls the callbacks registered with [`Vm::add_hook`], each at its
85//! own [`HookTriggers`],
86//! 3. yields the running root coroutine or task every N checks when
87//! preemption is enabled ([`Config::preempt_every`]).
88//!
89//! Calling [`Lua::set_hook`], [`Lua::set_global_hook`] or
90//! [`mlua::Thread::set_hook`] on the VM replaces this hook, and
91//! cancellation stops working. The hook is re-installed when a
92//! `set_hook` replacement is noticed (at the start of every actor
93//! request and of every `Vm::run`), but a replacement through
94//! `set_global_hook` cannot be detected.
95//!
96//! # The `task` library
97//!
98//! `Vm::task_lib` (`tokio` feature) returns the VM's `task` table,
99//! conventionally set as the global `task`:
100//!
101//! | Lua | meaning |
102//! |---|---|
103//! | `task.spawn(f, ...)` | Start `f(...)` as a concurrent task of the current coroutine request or task. Returns a handle. |
104//! | `h:join()` | Wait for the task. Returns `true, ...` (what `f` returned) or `false, err`, where `err` is the raw Lua error value, or `task.CANCELLED` if the task was cancelled. A handle can be joined once (a chosen `h:on` / `h:arm` case counts as the join). |
105//! | `h:cancel()` | Request cancellation. Does not wait. |
106//! | `h:done()` | Whether the task has finished. |
107//! | `local h <close> = task.spawn(...)` | On scope exit, a task that was not joined is cancelled and waited for. |
108//! | `task.is_cancelled(err)` | Whether `err` is a cancellation: the error a cancel raises (caught with `pcall`, or received by a `__close` handler) or `task.CANCELLED`. `false` for any other value. |
109//! | `task.CANCELLED` | What `join` returns as `err` for a cancelled task. |
110//! | `task.channel(cap)` | A local channel holding up to `cap` values (`cap >= 0`; `cap = 0` is a rendezvous channel). See [Channels, timers and select](#channels-timers-and-select). |
111//! | `ch:send(v)` | Push `v`; waits while the channel is full (rendezvous: until a receiver has taken `v`). Raises when the channel is closed. |
112//! | `ch:try_send(v)` | Push `v` without waiting: `true`, or `false` when full (rendezvous: `true` only if a receiver is waiting right now). Raises when the channel is closed. |
113//! | `ch:recv()` | Take the value at the front; waits while the channel is empty. Returns `v, true`, or `nil, false` when the channel is closed and empty. |
114//! | `ch:try_recv()` | Take without waiting. Returns `v, ok, ready`: `v, true, true` (a value), `nil, false, true` (closed and empty) or `nil, false, false` (empty, not closed). |
115//! | `ch:close()` | Close the channel. Idempotent. |
116//! | `ch:closed()`, `ch:len()`, `ch:cap()` | Whether it is closed; how many values it holds; its capacity. |
117//! | `task.after(ms)` | A one-shot timer, ready `ms` milliseconds after this call (`ms <= 0`: at once) and from then on. |
118//! | `t:wait()` | Wait until the timer is ready. |
119//! | `task.ticker(ms)` | A receive-only channel of capacity 1 that receives a tick every `ms` milliseconds (`ms > 0`): the tick's time in milliseconds since the ticker started. Stops with the scope that created it. |
120//! | `tk:stop()` | Stop the ticker and close its channel. Idempotent. |
121//! | `ch:on(f)`, `ch:on_send(v, f)`, `t:on(f)`, `h:on(f)` | A case for `task.select`: receive from `ch` and call `f(v, ok)`; send `v` into `ch` and call `f(sent)` (`sent = false`: the channel was closed); call `f()` when `t` is ready; call `f(ok, ...)` with what `h:join()` returns once the task `h` has finished. |
122//! | `task.select(cases, opts)` | Wait until one case is ready, take it, call its handler and return what the handler returns. `opts.biased` (default `false`): check the cases in order instead of round robin. `opts.default = f`: if no case is ready, call `f()` instead of waiting. |
123//! | `ch:arm_recv()`, `ch:arm_send(v)`, `t:arm()`, `h:arm()` | A case for `task.select_raw`. |
124//! | `task.select_raw(arms, opts)` | As `task.select`, without handlers: returns the index of the chosen case and its values (`i, v, ok` for a receive, `i, sent` for a send, `i` for a timer, `i, ok, ...` for a task). `opts.default = true`: return `0` if no case is ready. |
125//! | `req.value`, `req:reply(v)`, `req:replied()`, `local req <close> = ...` | A `Request` received from a host channel. See [Host channels and requests](#host-channels-and-requests). |
126//!
127//! A host channel (`channel`) and a ticker are `Channel` objects like
128//! `task.channel`'s, receive-only: `send` / `try_send` and send cases
129//! raise. A channel to the host (`channel_to_host`) is one too,
130//! send-only: `recv` / `try_recv` / `on` / `arm_recv` and receive cases
131//! raise.
132//!
133//! Tasks are **structured**: when a coroutine request or task finishes,
134//! the tasks it spawned and did not join are cancelled, and it waits
135//! for them before its own result is delivered. Cancelling a request
136//! or task cancels all of its tasks (their tokens are children of its
137//! token, see [`CancelToken::child_token`]), and the cancelled request
138//! or task still resolves only after they, and their own tasks, have
139//! finished or been dropped. The [grace](Config::grace) is one deadline
140//! for the whole tree: a task spawned during cleanup gets the time that
141//! remains, not a fresh grace period.
142//!
143//! `task.spawn` works inside `Vm::run`, inside coroutine requests
144//! (`AsyncIsle::coroutine_eval` / `coroutine_call`) and inside tasks
145//! (including host tasks). Sync requests (`eval` / `call` / `exec`)
146//! cannot await, so `task.spawn` raises an error there.
147//!
148//! A cancel reaches Lua code as an error: the cancel hook raises it
149//! while Lua code runs, and an async host function wrapped with
150//! `cancellable` returns it while the coroutine awaits. Its value is
151//! `mlua::Error::external(`[`Cancelled`]`)` (a userdata to Lua);
152//! `task.is_cancelled(err)` is the test, and it is also true for
153//! `task.CANCELLED`, so one predicate covers both:
154//!
155//! ```lua
156//! local ok, err = pcall(sleep, 1000)
157//! if not ok and task.is_cancelled(err) then
158//! -- cancelled: clean up and let the cancel continue
159//! error(err, 0)
160//! end
161//! ```
162//!
163//! The predicate lives in the library: a VM that runs without the `task`
164//! table has no `task.is_cancelled`; Rust code tests an `mlua::Error`
165//! with `e.downcast_ref::<Cancelled>()`.
166//!
167//! A task that runs a CPU loop never yields on its own, so a sibling on
168//! the same thread cannot run to cancel it; enable
169//! [`Config::preempt_every`] for that. Cancelling from another thread
170//! (an `AsyncTask` handle) works without it.
171//!
172//! # Channels, timers and select
173//!
174//! The `task` library passes values between the tasks of one VM with
175//! **local channels**, and waits on several of them (and on timers) at
176//! once with **`select`**:
177//!
178//! ```lua
179//! local requests = task.channel(16)
180//! local worker = task.spawn(function()
181//! while true do
182//! local stop = task.select({
183//! requests:on(function(req, ok)
184//! if not ok then return true end -- closed and drained
185//! handle(req)
186//! return false
187//! end),
188//! task.after(1000):on(function() idle() return false end),
189//! })
190//! if stop then return end
191//! end
192//! end)
193//! requests:send(req)
194//! ```
195//!
196//! **Channels**
197//!
198//! - FIFO, with any number of senders and receivers inside one VM.
199//! Waiting receivers are woken in arrival order.
200//! - Values are Lua values as they are (`nil` included); tables are
201//! shared, not copied.
202//! - After `close`: `send` / `try_send` raise; `recv` returns what is
203//! left, in order, then `nil, false`.
204//! - A channel belongs to no scope: cancelling a task does not close
205//! it. When the channel is garbage-collected, its contents are
206//! dropped. The values are held from Rust, out of the collector's
207//! sight, so a value that refers back to its own channel keeps both
208//! alive.
209//! - Without [`Config::preempt_every`], a sender that never waits (a
210//! `try_send` loop) keeps receivers on the same thread from running;
211//! `send`, which waits when the channel is full, is the form to use.
212//!
213//! **Rendezvous channels** (`task.channel(0)`)
214//!
215//! - A sender posts an *offer* and waits until a receiver takes it:
216//! `send` returns once a receiver has taken the value. Receivers take
217//! offers in the order they were posted (FIFO among senders).
218//! - `try_send` succeeds only when a receiver is waiting right now (a
219//! `recv`, or a select's receive case: the two wait the same way); it
220//! hands the value to the first waiting receiver and posts nothing.
221//! `try_recv` takes the first offer.
222//! - `len()` and `cap()` are `0`. The one exception is a value handed
223//! to a waiting receiver that then did not take it (its select chose
224//! another case, or it was cancelled): the value goes back to the
225//! front of the channel, counts in `len()`, and is received next.
226//! - A select never pairs its own send case with its own receive case
227//! on the same channel; two different selects do pair.
228//! - A select whose send case's offer was taken chooses that case, even
229//! if another case is ready by the time it runs again: the value is
230//! delivered. At most one of a select's offers is taken. When a
231//! select chooses another case (or runs `default`, or is cancelled),
232//! its offers are withdrawn and are never received.
233//! - `close`: waiting senders raise "channel is closed" (a send case is
234//! chosen with `sent = false`); waiting receivers get `nil, false`.
235//! - With `default`, a send case on a rendezvous channel is ready on
236//! the first check when a receiver is waiting (a `recv`, or another
237//! select's receive case): its value goes to the first such receiver,
238//! as with `try_send`, and the case is chosen with `sent = true`.
239//! With no receiver waiting, `default` runs and nothing is posted, so
240//! the value is never received.
241//!
242//! **Timers**: `task.after(ms)` is ready once `ms` milliseconds have
243//! passed since it was created (`ms <= 0`: at once). It may be waited
244//! on, or used as a case, any number of times; once ready it stays
245//! ready.
246//!
247//! **Tickers**: `task.ticker(ms)` is a receive-only channel of capacity
248//! 1 that a host task, spawned into the scope of the request or task
249//! that called it (as `ScopeHandle::spawn_local` does), feeds every `ms`
250//! milliseconds.
251//!
252//! - A tick is the tick's scheduled time in milliseconds since the
253//! ticker started: `ms`, `2 * ms`, ... (the tick count is the value
254//! divided by `ms`).
255//! - Only the newest tick is kept: an unread tick is replaced, not
256//! queued. Ticks that a busy VM missed are skipped
257//! (`tokio::time::MissedTickBehavior::Skip`).
258//! - `tk:stop()` stops the host task and closes the channel; a tick
259//! already in it can still be received. The ticker also stops, and
260//! its channel closes, when the scope that created it ends or is
261//! cancelled (within the grace), when Lua closes the channel, and when
262//! the ticker object is collected.
263//! - Outside a coroutine request or task (a sync request) `task.ticker`
264//! raises.
265//!
266//! **Send cases** (`ch:on_send(v, f)` / `ch:arm_send(v)`, local channels
267//! and channels to the host)
268//!
269//! - Ready when `v` can be pushed (room in a buffered channel; for a
270//! rendezvous channel, once a receiver has taken the offer; for a
271//! channel to the host, once room is reserved) or when the channel is
272//! closed (`sent = false`). The value enters the channel only for the
273//! chosen case.
274//!
275//! **Task cases** (`h:on(f)` / `h:arm()`, a `task.spawn` handle)
276//!
277//! - Ready when the task has finished. The case returns what
278//! `h:join()` would (`true, ...`, `false, err` with the raw error
279//! value, or `false, task.CANCELLED`) and marks the handle joined.
280//! - A case that is not chosen leaves the handle unjoined: it can be
281//! joined, or used in another select, later.
282//! - Building a case from a joined handle raises, and so does a select
283//! given a case whose handle was joined since.
284//! - A handle that is joined elsewhere (`h:join()`, or another select's
285//! case) while a select waits on its case: the join takes the result,
286//! and the waiting select raises "task already joined" once the task
287//! has finished.
288//!
289//! **select**
290//!
291//! - Exactly one ready case is chosen. Cases that are not chosen
292//! consume nothing.
293//! - Order: round robin per VM by default (each select starts one
294//! position after the previous one; deterministic, so tests are
295//! reproducible). `biased = true` checks the cases in the given
296//! order.
297//! - `default`: if no case is ready on the first check, `select` runs
298//! `default` (`select_raw` returns `0`) without waiting.
299//! - A closed, empty channel is ready: its case is chosen with
300//! `ok = false`. It stays ready, so a loop that keeps a closed
301//! channel in its case list keeps selecting it.
302//! - An empty case list without `default` raises.
303//! - A handler runs as Lua code inside the select and may await (and
304//! select again); an error it raises is re-raised by `select` with
305//! its raw value. While it runs, the other cases are not watched:
306//! move long work into `task.spawn`. [`Config::preempt_every`] does
307//! not preempt a handler either: it runs in a coroutine that the
308//! select's host call creates, not in a root or task (#22).
309//!
310//! **Delivery and cancellation**. The cancel hook can raise at any
311//! instruction count check, including the instructions between a host
312//! function returning a value and the Lua code that uses it. The
313//! library defines when a value is *delivered*:
314//!
315//! - A wait (`recv`, `send`, `t:wait()`, `select`, `select_raw`) that is
316//! cancelled before it is ready returns the cancel error and has
317//! consumed nothing (a cancelled `send` sent nothing). The wait is
318//! wrapped in `cancellable`, which checks the token first, so a poll
319//! that returns the cancel never also polled the cases.
320//! - `recv` and `select_raw`: a value is delivered when the call returns
321//! it. A cancel raised after that, in the caller's code, is the
322//! caller's to handle, as for any other value it holds.
323//! - A send (`send`, a send case) is delivered when its value is in the
324//! channel (buffered) or taken by a receiver (rendezvous), and it
325//! cannot be taken back. A rendezvous `send` whose offer was taken
326//! before the cancel was seen returns normally (sent), and a select
327//! whose send case's offer was taken chooses that case, rather than
328//! returning the cancel; a cancel seen before the offer was taken
329//! withdraws it (nothing sent). An error raised after a send case was
330//! delivered and before its handler is entered is re-raised; the value
331//! stays sent.
332//! - A task case is delivered like a received value: if the handler is
333//! never entered, the handle is left unjoined.
334//! - `select`: a value is delivered when the chosen handler is entered
335//! with it. `select` takes the value and calls the handler inside the
336//! same host call, so a cancel arrives either before the take
337//! (nothing consumed) or inside the handler (the handler has the
338//! value). An error raised after the take but before the handler is
339//! entered puts the value back at the front of its channel.
340//! - Between a host function's future becoming ready and the call
341//! returning, mlua runs a few instructions of Lua code of its own (the
342//! loop that polls the future). The cancel hook does not raise there:
343//! it raises at the next check outside that code (or the next
344//! `cancellable` wait returns the cancel), so a value `recv` or
345//! `select_raw` took reaches the caller, and a `send` that pushed its
346//! value returns normally. This holds for every async host function,
347//! not only the library's. A program that keeps landing its checks in
348//! that code (an async host function that is always ready and not
349//! `cancellable`, called in a tight loop) is still cancelled: the hook
350//! defers at most 16 checks before it raises anyway. The code is
351//! recognised by its chunk name, which mlua keeps from 0.12.2 on (the
352//! crate requires it).
353//!
354//! A task waiting in a select (or any of these waits) is cancelled with
355//! its scope and ends within the grace like any other wait.
356//!
357//! # Host channels and requests
358//!
359//! `channel` (`tokio` feature) creates a channel that `Send` host
360//! code feeds into a running Lua loop: a `Sender` (`Send + Clone`)
361//! and its Lua side, a `LuaChannel` (the `task` library's `Channel`
362//! object). A channel of `Request`s carries values that Lua answers:
363//!
364//! ```text
365//! let (tx, events) = channel::<Event>(&lua, 1024)?; // on the VM thread
366//! lua.globals().set("events", events)?;
367//! tx.send(ev).await?; // any thread or task
368//!
369//! let (req_tx, requests) = channel::<Request<Call, Answer>>(&lua, 256)?;
370//! lua.globals().set("requests", requests)?;
371//! let answer = tokio::time::timeout(limit, req_tx.request(call)).await??;
372//! ```
373//!
374//! ```lua
375//! task.select({
376//! events:on(function(ev, ok) ... end),
377//! requests:on(function(req, ok)
378//! if ok then req:reply(answer_for(req.value)) end
379//! end),
380//! })
381//! ```
382//!
383//! Call `channel` on the VM thread, after [`Vm::attach`] and
384//! `Vm::task_lib`; for an `AsyncIsle`, in an
385//! `exec` request that returns the `Sender` (example on `channel`).
386//!
387//! **Channel**
388//!
389//! - `cap >= 1` (a tokio bounded channel; `cap = 0` is an error: host
390//! channels have no rendezvous form). `ch:cap()` is `cap`; `ch:len()` counts the values
391//! queued by the host plus any put back (below).
392//! - On the Lua side it behaves as a local channel: FIFO, any number of
393//! Lua receivers, the same `recv` / `try_recv` / `close` / `closed` /
394//! `len` / `cap` and the same `select` contract. `send` / `try_send`
395//! raise ("channel is receive-only").
396//! - A value is converted to a Lua value (`T: IntoLua`) when Lua takes
397//! it, on the VM thread. A conversion error is raised to the
398//! receiver (`recv`, `try_recv`, `select`, `select_raw`), and that
399//! value is dropped; the next receive takes the next value.
400//! - Closed when every `Sender` is dropped (receivers get the queued
401//! values first, then `nil, false`), or when Lua calls `close`: the
402//! host's sends then fail with the value given back (`SendError`,
403//! `TrySendError::Closed`) and the values already queued can still
404//! be received. When the Lua side is collected (or the VM dropped),
405//! the host's sends fail as closed. `Sender::is_closed` reports
406//! both.
407//! - Ordering between several `Sender`s is the order in which their
408//! sends complete.
409//! - `Sender::send` waits while the channel is full;
410//! `Sender::try_send` returns `TrySendError::Full`. There is no
411//! `send_timeout`: wrap `send` (or `request`) in
412//! `tokio::time::timeout`; a send that times out sent nothing.
413//! - Several Lua receivers: every value is received exactly once, and no
414//! receiver is left asleep while a value is queued, including when a
415//! woken receiver's `select` chooses another case or the receiver is
416//! cancelled. (A tokio `Receiver` wakes only the task that polled it
417//! last; the channel polls it with a waker that wakes every waiting
418//! receiver.)
419//!
420//! **Request**
421//!
422//! - A `Request<Req, Resp>` carries a `Req` and a one-shot
423//! reply. `Sender::request` sends it and waits for the reply:
424//! `RequestError::Closed` (with the `Req`) if the channel is closed,
425//! `RequestError::NoReply` if the request is closed or collected
426//! without a reply (or the `Req` failed to convert to a Lua value).
427//! - On the Lua side it is a userdata: `req.value` is the `Req`
428//! (converted with `IntoLua` when Lua received it); `req:reply(v)`
429//! converts `v` with `Resp: FromLua` and returns `true`, or `false`
430//! when the requester stopped waiting (its future was dropped, e.g. by
431//! a timeout; not an error). A second `reply` raises, and so does a
432//! `reply` after the request was closed. A conversion error raises
433//! and leaves the request unanswered: it can be answered again.
434//! `req:replied()` is whether a `reply` succeeded.
435//! - Closing an unanswered request (`local req <close> = ...`, at scope
436//! exit or on an error) answers `NoReply` at once. A request that is
437//! neither answered nor closed is reported `NoReply` only when Lua
438//! collects it, so a requester should use a timeout, and Lua code that
439//! may fail between receiving and replying should hold the request in
440//! a `<close>` variable.
441//! - `select`'s handler form does not close a request its handler
442//! returns without answering: the handler may hand it to a task that
443//! replies later. Close it in the handler (or let it be collected).
444//!
445//! **Delivery and cancellation** are as for local channels (above): a
446//! wait cancelled before it is ready consumed nothing, and a value
447//! `select` took for a handler that was never entered goes back to the
448//! front of the channel, ahead of the values the host queued (the Lua
449//! side keeps a front buffer for it; the tokio channel itself cannot
450//! take a value back).
451//!
452//! # Channels to the host
453//!
454//! `channel_to_host` (`tokio` feature) creates a channel that a running
455//! Lua loop feeds and `Send` host code drains: its Lua side, a
456//! `LuaChannel` (the `task` library's `Channel` object, send-only), and
457//! a `Receiver` (`Send`, not `Clone`) for the host:
458//!
459//! ```text
460//! let (reports, mut rx) = channel_to_host::<Report>(&lua, 64)?; // on the VM thread
461//! lua.globals().set("reports", reports)?;
462//! while let Some(r) = rx.recv().await { ... } // any thread or task
463//! rx.try_recv(); // Ok(v), Err(TryRecvError::Empty), Err(TryRecvError::Closed)
464//! rx.close(); // Lua's sends raise from now on; queued values can still be received
465//! ```
466//!
467//! ```lua
468//! reports:send(r) -- waits while full
469//! local ok = reports:try_send(r) -- false when full
470//! task.select({ reports:on_send(r, function(sent) ... end) })
471//! reports:close() -- the host receives the queued values, then None
472//! ```
473//!
474//! Call `channel_to_host` on the VM thread, after [`Vm::attach`] and
475//! `Vm::task_lib`; for an `AsyncIsle`, in the init closure of
476//! `AsyncIsleBuilder::spawn_with`, which returns the `Receiver` (example
477//! on `channel_to_host`), or in an `exec` request that returns it.
478//!
479//! - `cap >= 1` (a tokio bounded channel; `cap = 0` is an error). One
480//! host receiver; any number of Lua senders (tasks, selects).
481//! `ch:cap()` is `cap`; `ch:len()` is the number of values queued for
482//! the host (`0` once Lua closed the channel).
483//! - Each Lua send first reserves room in the tokio channel (tokio's
484//! `Sender::reserve_owned`; every waiting Lua sender has its own place
485//! in tokio's queue, in the order they started waiting). Then the
486//! value is converted to `T` (`T: FromLua`) on the VM thread and
487//! queued, in the same step. A value that fails to convert raises in
488//! the sender (`send`, `try_send`, or the select with the chosen
489//! `on_send` case) and is not queued; its room is given back.
490//! - `send` waits while the channel is full; `try_send` returns `false`
491//! when full. Both raise "channel is closed" when the channel is
492//! closed: by `rx.close()`, by dropping `rx`, or by Lua's `close`.
493//! Waiting senders wake and raise at the close.
494//! - A send case (`on_send` / `arm_send`) is ready when room is
495//! reserved, or when the channel is closed (`sent = false`); it
496//! converts and queues the value only when it is chosen. With
497//! `default`, it is ready only when there is room at the first check
498//! (`try_reserve`).
499//! - Lua's `close`: the host receives the values already queued, then
500//! `recv` returns `None` (`try_recv` `Closed`). When the Lua side is
501//! collected (or the VM dropped), the same. `rx.close()` keeps the
502//! queued values receivable.
503//! - Delivery: a send is delivered when its value is in the tokio
504//! queue. A send cancelled before that (a cancelled `send`, a select
505//! that chose another case or was cancelled) consumed nothing: its
506//! reservation, if it had one, is released, and the room goes to the
507//! next waiting sender.
508//! - `recv`, `try_recv`, `on`, `arm_recv` raise ("channel is
509//! send-only"), and so does a select given a receive case built by
510//! hand on such a channel.
511//! - Ordering between several Lua senders is the order in which their
512//! sends complete; each value arrives exactly once.
513//!
514//! # Host tasks
515//!
516//! A host function that starts work of its own takes the scope of the
517//! running request or task with `current_scope()` and spawns into it
518//! with `ScopeHandle::spawn_local`. Such a task is structured like a
519//! Lua task: it is cancelled when the request or task ends or is
520//! cancelled, gets the grace (one deadline for the whole tree), is
521//! dropped when the grace ends, and is waited for. Take the handle in
522//! the synchronous part of the host function (the `create_function`
523//! body, or a `create_async_function` body before its first `.await`)
524//! and move it into the future; `current_scope()` is `Some` only while
525//! a coroutine request or task is being polled, so it is `None` in a
526//! sync request. `spawn_local` returns a `ScopedTask`; there are three
527//! ways to let go of it: await it (wait for the value), keep it for as
528//! long as the task should run (dropping it cancels the task now), or
529//! `detach()` it (fire and forget: the task runs on without a handle and
530//! is still cancelled, given the grace, dropped and waited for when the
531//! scope ends).
532//!
533//! ```text
534//! let bg = lua.create_function(|_, ()| {
535//! let scope = current_scope().expect("inside a coroutine request");
536//! scope.spawn_local(async move { /* host work */ }).detach();
537//! Ok(())
538//! })?;
539//! ```
540
541use crate::hub;
542use mlua::debug::Debug;
543use mlua::{HookTriggers, Lua, VmState};
544use std::cell::RefCell;
545use std::fmt;
546use std::time::Duration;
547
548pub use crate::error::{Cancelled, IsleError, LuaErrorKind, LuaFailure};
549pub use crate::hook::{current_token, CancelToken};
550#[cfg(feature = "tokio")]
551pub use crate::host_chan::{
552 channel, channel_to_host, LuaChannel, Receiver, Request, RequestError, SendError, Sender,
553 TryRecvError, TrySendError,
554};
555#[cfg(feature = "tokio")]
556pub use crate::scope::{cancellable, current_scope, ScopeHandle, ScopedTask};
557
558/// Settings of a VM. One per VM, read and written through [`Vm`]
559/// ([`Vm::attach`], [`Vm::config`], [`Vm::set_config`]).
560#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
561pub struct Config {
562 /// How long a cancelled coroutine request or task may keep running
563 /// to finish its cleanup before it is dropped.
564 ///
565 /// On cancel, the coroutine first receives the cancellation as a Lua
566 /// error (from the cancel hook while it runs, or from an async
567 /// function wrapped with `cancellable` while it awaits). That error
568 /// unwinds normally, so `__close` handlers run and may await. If
569 /// the coroutine has not finished when the grace period ends, it is
570 /// dropped: the awaited Rust future is released, and pending
571 /// `__close` handlers run without being able to yield (a Lua 5.4
572 /// restriction).
573 ///
574 /// The grace period is one deadline for the cancelled request or
575 /// task and every task it spawned, transitively: a task started
576 /// during cleanup (from a `__close` handler, say) gets the time that
577 /// remains, not a fresh grace period.
578 ///
579 /// Default: zero (drop at once).
580 pub grace: Duration,
581 /// Yield the running coroutine request or task every this many
582 /// cancel checks (a check runs every 1000 instructions), so that
583 /// other tasks on the same thread, including one that cancels it,
584 /// get to run while it is in a CPU loop.
585 ///
586 /// Only the coroutine that the crate created for the request or task
587 /// is yielded, never a coroutine the Lua code created itself (that
588 /// yield would reach the Lua code's own `coroutine.resume` as a
589 /// spurious yield). Code in a non-yieldable context (a metamethod,
590 /// a C function boundary) is not yielded.
591 ///
592 /// Yielding lets other tasks interleave at points the Lua code did
593 /// not mark, so Lua code that updates shared state across such a
594 /// point can observe changes made by another task.
595 ///
596 /// Default: `None` (never preempt).
597 pub preempt_every: Option<u32>,
598}
599
600/// Handle of a callback registered with [`Vm::add_hook`].
601#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
602pub struct HookId(pub(crate) u64);
603
604/// Marks a VM as attached; holds the per-VM state that is not in the
605/// hook hub.
606#[derive(Default)]
607struct Attached {
608 /// The `task` table, created on the first [`Vm::task_lib`] call, so
609 /// that a VM that never asks for it (an actor whose init closure
610 /// does not) runs no extra Lua. Kept in the registry, not as a
611 /// global.
612 #[cfg(feature = "tokio")]
613 task: std::cell::OnceCell<TaskLib>,
614}
615
616/// The registry keys of the `task` table and of the library's channel
617/// constructor (used by [`channel`]).
618#[cfg(feature = "tokio")]
619struct TaskLib {
620 table: mlua::RegistryKey,
621 wrap_channel: mlua::RegistryKey,
622}
623
624/// The in-thread handle of a Lua VM run by this crate.
625///
626/// A `Vm` is a clone of the [`Lua`] handle; its state lives in the VM,
627/// so every `Vm` of the same VM (from [`Vm::attach`] or [`Vm::of`]) sees
628/// the same state. It holds the VM strongly: do not store it in
629/// something the VM owns (a Lua function's captured state, app data),
630/// or the VM is never freed.
631#[derive(Clone)]
632pub struct Vm {
633 lua: Lua,
634}
635
636impl fmt::Debug for Vm {
637 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
638 f.debug_struct("Vm")
639 .field("config", &self.config())
640 .finish_non_exhaustive()
641 }
642}
643
644impl Vm {
645 /// Install the hook and store `config`.
646 ///
647 /// Calling it again on the same VM re-installs the hook, replaces
648 /// the config (last wins) and returns a `Vm` for the same state; the
649 /// task table, if `Vm::task_lib` created it, is kept. Runs no Lua
650 /// code.
651 ///
652 /// Hook callbacks registered before (with [`Vm::add_hook`]) are
653 /// kept.
654 ///
655 /// The first `attach` also captures the `xpcall` global, which
656 /// [`Vm::run`] uses to bring a raised Lua value back as a value (see
657 /// [`LuaFailure`]). **Attach before sandboxing the globals**
658 /// (removing `xpcall`, or [`Lua::set_globals`] with a whitelist):
659 /// after that the capture is kept, and later changes to the globals
660 /// or a re-attach do not affect it.
661 ///
662 /// **The coroutine path needs mlua's default
663 /// `LuaOptions::catch_rust_panics = true`.** With `false`, mlua
664 /// replaces the global `xpcall` with a version that is not
665 /// yieldable, so every yield in a root run by [`Vm::run`] (an async
666 /// host function, `task.join`, preemption) fails with "attempt to
667 /// yield across a C-call boundary". [`Lua::new`] uses the default.
668 ///
669 /// # Errors
670 ///
671 /// [`IsleError::Init`] with [`LuaErrorKind::External`] when the VM's
672 /// `xpcall` global is not a function (it was sandboxed away before
673 /// the first attach).
674 pub fn attach(lua: &Lua, config: Config) -> Result<Vm, IsleError> {
675 crate::protect::install(lua)?;
676 hub::install(lua)?;
677 hub::set_config(lua, config);
678 let attached = lua.app_data_ref::<Attached>().is_some();
679 if !attached {
680 lua.set_app_data(Attached::default());
681 }
682 Ok(Vm { lua: lua.clone() })
683 }
684
685 /// The `Vm` of `lua`, if [`Vm::attach`] was called on it.
686 pub fn of(lua: &Lua) -> Option<Vm> {
687 let attached = lua.app_data_ref::<Attached>().is_some();
688 attached.then(|| Vm { lua: lua.clone() })
689 }
690
691 /// The VM's settings.
692 pub fn config(&self) -> Config {
693 hub::config(&self.lua)
694 }
695
696 /// Replace the VM's settings. Takes effect for requests and tasks
697 /// that start afterwards (and, for `preempt_every`, at once).
698 pub fn set_config(&self, config: Config) {
699 hub::set_config(&self.lua, config);
700 }
701
702 /// Register a hook callback, run from the VM's hook after the cancel
703 /// check at `triggers` (see [Hooks](self#hooks)).
704 ///
705 /// Instruction counts are approximated to the hook's step (the
706 /// smallest count among all registrations and the cancel check).
707 /// Returning [`VmState::Yield`] yields the running coroutine,
708 /// including a coroutine the Lua code created itself, where the
709 /// yield reaches the Lua code's `coroutine.resume`.
710 ///
711 /// The callback applies to the main thread and to coroutines created
712 /// afterwards; coroutines that already exist keep the instruction
713 /// count and events they were created with. It is kept across a
714 /// second [`Vm::attach`].
715 ///
716 /// The callback is not re-entered. A callback that runs Lua code
717 /// can be hooked again from inside itself: resuming a coroutine is
718 /// the usual case, because the new thread has hooks enabled while
719 /// the hooked thread does not. That inner call fails with
720 /// [`mlua::Error::RecursiveMutCallback`].
721 ///
722 /// Known limit: a request's Lua error goes through the crate's
723 /// message handler (a C function under `xpcall`). Count and line
724 /// callbacks do not fire inside it, but a callback with `on_calls` /
725 /// `on_returns` fires for the handler's own call and return. If
726 /// that callback returns `Err`, its error replaces the original Lua
727 /// error (the request fails with "error in error handling" or the
728 /// callback's error). Do not fail from call / return callbacks if
729 /// the original error matters.
730 pub fn add_hook<F>(&self, triggers: HookTriggers, f: F) -> Result<HookId, IsleError>
731 where
732 F: FnMut(&Lua, &Debug) -> mlua::Result<VmState> + 'static,
733 {
734 let f = RefCell::new(f);
735 hub::add_hook(&self.lua, triggers, move |lua, debug| {
736 let mut f = f
737 .try_borrow_mut()
738 .map_err(|_| mlua::Error::RecursiveMutCallback)?;
739 f(lua, debug)
740 })
741 }
742
743 /// Remove a callback registered with [`Vm::add_hook`]. Returns
744 /// whether it was registered.
745 pub fn remove_hook(&self, id: HookId) -> Result<bool, IsleError> {
746 hub::remove_hook(&self.lua, id)
747 }
748
749 /// The `task` library table (see [The `task` library](self#the-task-library)).
750 ///
751 /// It is not set as a global: the host decides where it lives,
752 /// e.g. `lua.globals().set("task", vm.task_lib()?)`. The table is
753 /// created on the first call (this runs the library's Lua chunk);
754 /// every later call, through any `Vm` of the same VM, returns the
755 /// same table.
756 ///
757 /// In an actor's init closure the VM is not attached yet: attach it
758 /// there (the actor re-attaches after the closure and keeps the
759 /// config and the table). `?` converts the [`IsleError`] into the
760 /// closure's `mlua::Error`.
761 ///
762 /// ```rust
763 /// # #[tokio::main]
764 /// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
765 /// use mlua_isle::runtime::{Config, Vm};
766 /// use mlua_isle::AsyncIsle;
767 ///
768 /// let (isle, driver) = AsyncIsle::spawn(|lua| {
769 /// let vm = Vm::attach(lua, Config::default())?;
770 /// lua.globals().set("task", vm.task_lib()?)
771 /// })
772 /// .await?;
773 /// let r: i64 = isle
774 /// .coroutine_eval(
775 /// "local h = task.spawn(function(a, b) return a + b end, 1, 2)
776 /// local ok, sum = h:join()
777 /// return sum",
778 /// )
779 /// .await?;
780 /// assert_eq!(r, 3);
781 /// driver.shutdown().await?;
782 /// # Ok(())
783 /// # }
784 /// ```
785 ///
786 /// # Errors
787 ///
788 /// Fails only when creating the table fails (e.g. the VM's memory
789 /// limit is reached).
790 #[cfg(feature = "tokio")]
791 pub fn task_lib(&self) -> Result<mlua::Table, IsleError> {
792 if let Some(t) = self.cached_task_lib()? {
793 return Ok(t);
794 }
795 // Created without holding the app data borrow: the chunk runs
796 // under the hook, whose callbacks may touch app data.
797 let (table, wrap_channel) = crate::task_lib::create(&self.lua)?;
798 let lib = TaskLib {
799 table: self.lua.create_registry_value(table)?,
800 wrap_channel: self.lua.create_registry_value(wrap_channel)?,
801 };
802 {
803 let a = self.attached();
804 // A table stored meanwhile wins; `lib` is then dropped.
805 let _ = a.task.set(lib);
806 }
807 Ok(self
808 .cached_task_lib()?
809 .expect("the task table was just stored"))
810 }
811
812 #[cfg(feature = "tokio")]
813 fn cached_task_lib(&self) -> Result<Option<mlua::Table>, IsleError> {
814 let a = self.attached();
815 match a.task.get() {
816 Some(lib) => Ok(Some(self.lua.registry_value(&lib.table)?)),
817 None => Ok(None),
818 }
819 }
820
821 /// The `task` library's channel constructor, if `Vm::task_lib`
822 /// created the library.
823 #[cfg(feature = "tokio")]
824 pub(crate) fn channel_ctor(&self) -> Result<Option<mlua::Function>, IsleError> {
825 let a = self.attached();
826 match a.task.get() {
827 Some(lib) => Ok(Some(self.lua.registry_value(&lib.wrap_channel)?)),
828 None => Ok(None),
829 }
830 }
831
832 #[cfg(feature = "tokio")]
833 fn attached(&self) -> mlua::AppDataRef<'_, Attached> {
834 self.lua
835 .app_data_ref::<Attached>()
836 .expect("a Vm exists only for an attached VM")
837 }
838
839 /// Run `f(args)` as a root coroutine under `token`.
840 ///
841 /// Resolves only after everything the root started has ended: the
842 /// Lua tasks it spawned and the host tasks spawned through
843 /// [`current_scope`], transitively (contract 1 of the
844 /// [module docs](self)). Resolves to `Err(IsleError::Cancelled)` if
845 /// `token` was cancelled, whatever the coroutine returned; the
846 /// coroutine and its tasks then get the VM's [`Config::grace`], as
847 /// one deadline, before they are dropped. The cancellation error
848 /// raised by some other token (a host function that returned
849 /// `Err(mlua::Error::external(Cancelled))`) also resolves to
850 /// `Err(IsleError::Cancelled)`.
851 ///
852 /// A Lua error resolves to `Err(IsleError::Lua(f))`, where the
853 /// [`LuaFailure`] is built from the raised value itself on this
854 /// thread: `f.message` is `tostring(err)` and, with the `serde`
855 /// feature, `f.value` is the value as JSON (so `error({ code = 42 })`
856 /// gives `f.value["code"] == 42`).
857 ///
858 /// A task in a CPU loop cannot be dropped until it yields; without
859 /// [`Config::preempt_every`] the wait blocks on it.
860 ///
861 /// Await it inside a [`tokio::task::LocalSet`].
862 ///
863 /// # Dropping the future
864 ///
865 /// Dropping the returned future before it resolves (wrapping it in
866 /// [`tokio::time::timeout`], or a losing [`tokio::select!`] arm)
867 /// drops the coroutine at once but only schedules the tasks it
868 /// spawned for abort: tokio drops them on a later poll of the
869 /// `LocalSet`, as with
870 /// [`AbortHandle::abort`](tokio::task::AbortHandle::abort). To have
871 /// the tasks gone before you continue, [cancel](CancelToken::cancel)
872 /// the token and await the future instead of dropping it.
873 ///
874 /// ```rust
875 /// use mlua_isle::runtime::{CancelToken, Config, Vm};
876 /// use std::time::Duration;
877 ///
878 /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
879 /// let rt = tokio::runtime::Builder::new_current_thread().enable_all().build()?;
880 /// let local = tokio::task::LocalSet::new();
881 /// let lua = mlua::Lua::new();
882 ///
883 /// let vm = Vm::attach(&lua, Config { grace: Duration::from_secs(1), ..Default::default() })?;
884 /// lua.globals().set("task", vm.task_lib()?)?;
885 /// let main: mlua::Function = lua
886 /// .load("return function(x) local _, v = task.spawn(function() return x * 2 end):join() return v end")
887 /// .eval()?;
888 ///
889 /// let token = CancelToken::new();
890 /// let out = local.block_on(&rt, vm.run(&token, main, 21))?;
891 /// assert_eq!(out[0].as_i64(), Some(42));
892 /// # Ok(())
893 /// # }
894 /// ```
895 #[cfg(feature = "tokio")]
896 pub async fn run(
897 &self,
898 token: &CancelToken,
899 f: mlua::Function,
900 args: impl mlua::IntoLuaMulti,
901 ) -> Result<mlua::MultiValue, IsleError> {
902 let args = args.into_lua_multi(&self.lua)?;
903 crate::scope::run_root(&self.lua, token.clone(), f, args).await
904 }
905}
906
907/// Attach an actor's VM after its init closure ran.
908///
909/// With `config`, it replaces whatever the init closure configured;
910/// without, the VM keeps the init closure's settings (the default if it
911/// set none). The hook is (re-)installed either way, so a hook the init
912/// closure set with `Lua::set_hook` is replaced, as before.
913pub(crate) fn attach_after_init(lua: &Lua, config: Option<Config>) -> Result<Vm, IsleError> {
914 let config = config.unwrap_or_else(|| hub::config(lua));
915 Vm::attach(lua, config)
916}
917
918/// Make sure the VM is attached and its hook is in place, before a
919/// request runs. Re-installs the hook if `Lua::set_hook` replaced it;
920/// keeps the stored config.
921pub(crate) fn ensure_attached(lua: &Lua) -> Result<(), IsleError> {
922 let attached = lua.app_data_ref::<Attached>().is_some();
923 if attached {
924 hub::ensure_installed(lua)
925 } else {
926 // Unreachable for the actors (they attach before reporting a
927 // successful spawn); kept as a defensive path.
928 attach_after_init(lua, None).map(drop)
929 }
930}
931
932/// The [`Vm`] of `lua`, attaching it with its stored config (the
933/// default if none was set) when it is not attached yet.
934pub(crate) fn of_or_attach(lua: &Lua) -> Result<Vm, IsleError> {
935 match Vm::of(lua) {
936 Some(vm) => Ok(vm),
937 None => attach_after_init(lua, None),
938 }
939}