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:reject(reason)`, `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, E = String>` carries a `Req` and a one-shot
423//! answer: a `Resp` or a rejection reason `E`. `Sender::request`
424//! sends it and waits for the answer: `RequestError::Closed` (with
425//! the `Req`) if the channel is closed, `RequestError::Rejected` (with
426//! the reason) if Lua rejected it, `RequestError::NoReply` if the
427//! request is closed or collected without an answer (or the `Req`
428//! failed to convert to a Lua value).
429//! - On the Lua side it is a userdata: `req.value` is the `Req`
430//! (converted with `IntoLua` when Lua received it); `req:reply(v)`
431//! converts `v` with `Resp: FromLua` and returns `true`, or `false`
432//! when the requester stopped waiting (its future was dropped, e.g. by
433//! a timeout; not an error). A second `reply` raises, and so does a
434//! `reply` after the request was closed. A conversion error raises
435//! and leaves the request unanswered: it can be answered again.
436//! - `req:reject(reason)` answers with a rejection: the requester gets
437//! `RequestError::Rejected(reason)`, `reason` converted with
438//! `E: FromLua` (`String` by default). It returns as `reply` does
439//! (`false` when the requester stopped waiting). A conversion error
440//! raises and leaves the request unanswered; a `reply` or `reject`
441//! after the request was answered (replied or rejected) or closed
442//! raises.
443//! - `req:replied()` is whether a `reply` or `reject` succeeded.
444//! - Closing an unanswered request (`local req <close> = ...`, at scope
445//! exit or on an error) answers `NoReply` at once. A request that is
446//! neither answered nor closed is reported `NoReply` only when Lua
447//! collects it, so a requester should use a timeout, and Lua code that
448//! may fail between receiving and answering should hold the request in
449//! a `<close>` variable.
450//! - `select`'s handler form does not close a request its handler
451//! returns without answering: the handler may hand it to a task that
452//! answers later. Close it in the handler (or let it be collected).
453//!
454//! **Delivery and cancellation** are as for local channels (above): a
455//! wait cancelled before it is ready consumed nothing, and a value
456//! `select` took for a handler that was never entered goes back to the
457//! front of the channel, ahead of the values the host queued (the Lua
458//! side keeps a front buffer for it; the tokio channel itself cannot
459//! take a value back).
460//!
461//! # Channels to the host
462//!
463//! `channel_to_host` (`tokio` feature) creates a channel that a running
464//! Lua loop feeds and `Send` host code drains: its Lua side, a
465//! `LuaChannel` (the `task` library's `Channel` object, send-only), and
466//! a `Receiver` (`Send`, not `Clone`) for the host:
467//!
468//! ```text
469//! let (reports, mut rx) = channel_to_host::<Report>(&lua, 64)?; // on the VM thread
470//! lua.globals().set("reports", reports)?;
471//! while let Some(r) = rx.recv().await { ... } // any thread or task
472//! rx.try_recv(); // Ok(v), Err(TryRecvError::Empty), Err(TryRecvError::Closed)
473//! rx.close(); // Lua's sends raise from now on; queued values can still be received
474//! ```
475//!
476//! ```lua
477//! reports:send(r) -- waits while full
478//! local ok = reports:try_send(r) -- false when full
479//! task.select({ reports:on_send(r, function(sent) ... end) })
480//! reports:close() -- the host receives the queued values, then None
481//! ```
482//!
483//! Call `channel_to_host` on the VM thread, after [`Vm::attach`] and
484//! `Vm::task_lib`; for an `AsyncIsle`, in the init closure of
485//! `AsyncIsleBuilder::spawn_with`, which returns the `Receiver` (example
486//! on `channel_to_host`), or in an `exec` request that returns it.
487//!
488//! - `cap >= 1` (a tokio bounded channel; `cap = 0` is an error). One
489//! host receiver; any number of Lua senders (tasks, selects).
490//! `ch:cap()` is `cap`; `ch:len()` is the number of values queued for
491//! the host (`0` once Lua closed the channel).
492//! - Each Lua send first reserves room in the tokio channel (tokio's
493//! `Sender::reserve_owned`; every waiting Lua sender has its own place
494//! in tokio's queue, in the order they started waiting). Then the
495//! value is converted to `T` (`T: FromLua`) on the VM thread and
496//! queued, in the same step. A value that fails to convert raises in
497//! the sender (`send`, `try_send`, or the select with the chosen
498//! `on_send` case) and is not queued; its room is given back.
499//! - `send` waits while the channel is full; `try_send` returns `false`
500//! when full. Both raise "channel is closed" when the channel is
501//! closed: by `rx.close()`, by dropping `rx`, or by Lua's `close`.
502//! Waiting senders wake and raise at the close.
503//! - A send case (`on_send` / `arm_send`) is ready when room is
504//! reserved, or when the channel is closed (`sent = false`); it
505//! converts and queues the value only when it is chosen. With
506//! `default`, it is ready only when there is room at the first check
507//! (`try_reserve`).
508//! - Lua's `close`: the host receives the values already queued, then
509//! `recv` returns `None` (`try_recv` `Closed`). When the Lua side is
510//! collected (or the VM dropped), the same. `rx.close()` keeps the
511//! queued values receivable.
512//! - Delivery: a send is delivered when its value is in the tokio
513//! queue. A send cancelled before that (a cancelled `send`, a select
514//! that chose another case or was cancelled) consumed nothing: its
515//! reservation, if it had one, is released, and the room goes to the
516//! next waiting sender.
517//! - `recv`, `try_recv`, `on`, `arm_recv` raise ("channel is
518//! send-only"), and so does a select given a receive case built by
519//! hand on such a channel.
520//! - Ordering between several Lua senders is the order in which their
521//! sends complete; each value arrives exactly once.
522//!
523//! # Host tasks
524//!
525//! A host function that starts work of its own takes the scope of the
526//! running request or task with `current_scope()` and spawns into it
527//! with `ScopeHandle::spawn_local`. Such a task is structured like a
528//! Lua task: it is cancelled when the request or task ends or is
529//! cancelled, gets the grace (one deadline for the whole tree), is
530//! dropped when the grace ends, and is waited for. Take the handle in
531//! the synchronous part of the host function (the `create_function`
532//! body, or a `create_async_function` body before its first `.await`)
533//! and move it into the future; `current_scope()` is `Some` only while
534//! a coroutine request or task is being polled, so it is `None` in a
535//! sync request. `spawn_local` returns a `ScopedTask`; there are three
536//! ways to let go of it: await it (wait for the value), keep it for as
537//! long as the task should run (dropping it cancels the task now), or
538//! `detach()` it (fire and forget: the task runs on without a handle and
539//! is still cancelled, given the grace, dropped and waited for when the
540//! scope ends).
541//!
542//! ```text
543//! let bg = lua.create_function(|_, ()| {
544//! let scope = current_scope().expect("inside a coroutine request");
545//! scope.spawn_local(async move { /* host work */ }).detach();
546//! Ok(())
547//! })?;
548//! ```
549
550use crate::hub;
551use mlua::debug::Debug;
552use mlua::{HookTriggers, Lua, VmState};
553use std::cell::RefCell;
554use std::fmt;
555use std::time::Duration;
556
557pub use crate::error::{Cancelled, IsleError, LuaErrorKind, LuaFailure};
558pub use crate::hook::{current_token, CancelToken};
559#[cfg(feature = "tokio")]
560pub use crate::host_chan::{
561 channel, channel_to_host, LuaChannel, Receiver, Request, RequestError, SendError, Sender,
562 TryRecvError, TrySendError,
563};
564#[cfg(feature = "tokio")]
565pub use crate::scope::{cancellable, current_scope, ScopeHandle, ScopedTask};
566
567/// Settings of a VM. One per VM, read and written through [`Vm`]
568/// ([`Vm::attach`], [`Vm::config`], [`Vm::set_config`]).
569#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
570pub struct Config {
571 /// How long a cancelled coroutine request or task may keep running
572 /// to finish its cleanup before it is dropped.
573 ///
574 /// On cancel, the coroutine first receives the cancellation as a Lua
575 /// error (from the cancel hook while it runs, or from an async
576 /// function wrapped with `cancellable` while it awaits). That error
577 /// unwinds normally, so `__close` handlers run and may await. If
578 /// the coroutine has not finished when the grace period ends, it is
579 /// dropped: the awaited Rust future is released, and pending
580 /// `__close` handlers run without being able to yield (a Lua 5.4
581 /// restriction).
582 ///
583 /// The grace period is one deadline for the cancelled request or
584 /// task and every task it spawned, transitively: a task started
585 /// during cleanup (from a `__close` handler, say) gets the time that
586 /// remains, not a fresh grace period.
587 ///
588 /// Default: zero (drop at once).
589 pub grace: Duration,
590 /// Yield the running coroutine request or task every this many
591 /// cancel checks (a check runs every 1000 instructions), so that
592 /// other tasks on the same thread, including one that cancels it,
593 /// get to run while it is in a CPU loop.
594 ///
595 /// Only the coroutine that the crate created for the request or task
596 /// is yielded, never a coroutine the Lua code created itself (that
597 /// yield would reach the Lua code's own `coroutine.resume` as a
598 /// spurious yield). Code in a non-yieldable context (a metamethod,
599 /// a C function boundary) is not yielded.
600 ///
601 /// Yielding lets other tasks interleave at points the Lua code did
602 /// not mark, so Lua code that updates shared state across such a
603 /// point can observe changes made by another task.
604 ///
605 /// Default: `None` (never preempt).
606 pub preempt_every: Option<u32>,
607}
608
609/// Handle of a callback registered with [`Vm::add_hook`].
610#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
611pub struct HookId(pub(crate) u64);
612
613/// Marks a VM as attached; holds the per-VM state that is not in the
614/// hook hub.
615#[derive(Default)]
616struct Attached {
617 /// The `task` table, created on the first [`Vm::task_lib`] call, so
618 /// that a VM that never asks for it (an actor whose init closure
619 /// does not) runs no extra Lua. Kept in the registry, not as a
620 /// global.
621 #[cfg(feature = "tokio")]
622 task: std::cell::OnceCell<TaskLib>,
623}
624
625/// The registry keys of the `task` table and of the library's channel
626/// constructor (used by [`channel`]).
627#[cfg(feature = "tokio")]
628struct TaskLib {
629 table: mlua::RegistryKey,
630 wrap_channel: mlua::RegistryKey,
631}
632
633/// The in-thread handle of a Lua VM run by this crate.
634///
635/// A `Vm` is a clone of the [`Lua`] handle; its state lives in the VM,
636/// so every `Vm` of the same VM (from [`Vm::attach`] or [`Vm::of`]) sees
637/// the same state. It holds the VM strongly: do not store it in
638/// something the VM owns (a Lua function's captured state, app data),
639/// or the VM is never freed.
640#[derive(Clone)]
641pub struct Vm {
642 lua: Lua,
643}
644
645impl fmt::Debug for Vm {
646 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
647 f.debug_struct("Vm")
648 .field("config", &self.config())
649 .finish_non_exhaustive()
650 }
651}
652
653impl Vm {
654 /// Install the hook and store `config`.
655 ///
656 /// Calling it again on the same VM re-installs the hook, replaces
657 /// the config (last wins) and returns a `Vm` for the same state; the
658 /// task table, if `Vm::task_lib` created it, is kept. Runs no Lua
659 /// code.
660 ///
661 /// Hook callbacks registered before (with [`Vm::add_hook`]) are
662 /// kept.
663 ///
664 /// The first `attach` also captures the `xpcall` global, which
665 /// [`Vm::run`] uses to bring a raised Lua value back as a value (see
666 /// [`LuaFailure`]). **Attach before sandboxing the globals**
667 /// (removing `xpcall`, or [`Lua::set_globals`] with a whitelist):
668 /// after that the capture is kept, and later changes to the globals
669 /// or a re-attach do not affect it.
670 ///
671 /// **The coroutine path needs mlua's default
672 /// `LuaOptions::catch_rust_panics = true`.** With `false`, mlua
673 /// replaces the global `xpcall` with a version that is not
674 /// yieldable, so every yield in a root run by [`Vm::run`] (an async
675 /// host function, `task.join`, preemption) fails with "attempt to
676 /// yield across a C-call boundary". [`Lua::new`] uses the default.
677 ///
678 /// # Errors
679 ///
680 /// [`IsleError::Init`] with [`LuaErrorKind::External`] when the VM's
681 /// `xpcall` global is not a function (it was sandboxed away before
682 /// the first attach).
683 pub fn attach(lua: &Lua, config: Config) -> Result<Vm, IsleError> {
684 crate::protect::install(lua)?;
685 hub::install(lua)?;
686 hub::set_config(lua, config);
687 let attached = lua.app_data_ref::<Attached>().is_some();
688 if !attached {
689 lua.set_app_data(Attached::default());
690 }
691 Ok(Vm { lua: lua.clone() })
692 }
693
694 /// The `Vm` of `lua`, if [`Vm::attach`] was called on it.
695 pub fn of(lua: &Lua) -> Option<Vm> {
696 let attached = lua.app_data_ref::<Attached>().is_some();
697 attached.then(|| Vm { lua: lua.clone() })
698 }
699
700 /// The VM's settings.
701 pub fn config(&self) -> Config {
702 hub::config(&self.lua)
703 }
704
705 /// Replace the VM's settings. Takes effect for requests and tasks
706 /// that start afterwards (and, for `preempt_every`, at once).
707 pub fn set_config(&self, config: Config) {
708 hub::set_config(&self.lua, config);
709 }
710
711 /// Register a hook callback, run from the VM's hook after the cancel
712 /// check at `triggers` (see [Hooks](self#hooks)).
713 ///
714 /// Instruction counts are approximated to the hook's step (the
715 /// smallest count among all registrations and the cancel check).
716 /// Returning [`VmState::Yield`] yields the running coroutine,
717 /// including a coroutine the Lua code created itself, where the
718 /// yield reaches the Lua code's `coroutine.resume`.
719 ///
720 /// The callback applies to the main thread and to coroutines created
721 /// afterwards; coroutines that already exist keep the instruction
722 /// count and events they were created with. It is kept across a
723 /// second [`Vm::attach`].
724 ///
725 /// The callback is not re-entered. A callback that runs Lua code
726 /// can be hooked again from inside itself: resuming a coroutine is
727 /// the usual case, because the new thread has hooks enabled while
728 /// the hooked thread does not. That inner call fails with
729 /// [`mlua::Error::RecursiveMutCallback`].
730 ///
731 /// Known limit: a request's Lua error goes through the crate's
732 /// message handler (a C function under `xpcall`). Count and line
733 /// callbacks do not fire inside it, but a callback with `on_calls` /
734 /// `on_returns` fires for the handler's own call and return. If
735 /// that callback returns `Err`, its error replaces the original Lua
736 /// error (the request fails with "error in error handling" or the
737 /// callback's error). Do not fail from call / return callbacks if
738 /// the original error matters.
739 pub fn add_hook<F>(&self, triggers: HookTriggers, f: F) -> Result<HookId, IsleError>
740 where
741 F: FnMut(&Lua, &Debug) -> mlua::Result<VmState> + 'static,
742 {
743 let f = RefCell::new(f);
744 hub::add_hook(&self.lua, triggers, move |lua, debug| {
745 let mut f = f
746 .try_borrow_mut()
747 .map_err(|_| mlua::Error::RecursiveMutCallback)?;
748 f(lua, debug)
749 })
750 }
751
752 /// Remove a callback registered with [`Vm::add_hook`]. Returns
753 /// whether it was registered.
754 pub fn remove_hook(&self, id: HookId) -> Result<bool, IsleError> {
755 hub::remove_hook(&self.lua, id)
756 }
757
758 /// The `task` library table (see [The `task` library](self#the-task-library)).
759 ///
760 /// It is not set as a global: the host decides where it lives,
761 /// e.g. `lua.globals().set("task", vm.task_lib()?)`. The table is
762 /// created on the first call (this runs the library's Lua chunk);
763 /// every later call, through any `Vm` of the same VM, returns the
764 /// same table.
765 ///
766 /// In an actor's init closure the VM is not attached yet: attach it
767 /// there (the actor re-attaches after the closure and keeps the
768 /// config and the table). `?` converts the [`IsleError`] into the
769 /// closure's `mlua::Error`.
770 ///
771 /// ```rust
772 /// # #[tokio::main]
773 /// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
774 /// use mlua_isle::runtime::{Config, Vm};
775 /// use mlua_isle::AsyncIsle;
776 ///
777 /// let (isle, driver) = AsyncIsle::spawn(|lua| {
778 /// let vm = Vm::attach(lua, Config::default())?;
779 /// lua.globals().set("task", vm.task_lib()?)
780 /// })
781 /// .await?;
782 /// let r: i64 = isle
783 /// .coroutine_eval(
784 /// "local h = task.spawn(function(a, b) return a + b end, 1, 2)
785 /// local ok, sum = h:join()
786 /// return sum",
787 /// )
788 /// .await?;
789 /// assert_eq!(r, 3);
790 /// driver.shutdown().await?;
791 /// # Ok(())
792 /// # }
793 /// ```
794 ///
795 /// # Errors
796 ///
797 /// Fails only when creating the table fails (e.g. the VM's memory
798 /// limit is reached).
799 #[cfg(feature = "tokio")]
800 pub fn task_lib(&self) -> Result<mlua::Table, IsleError> {
801 if let Some(t) = self.cached_task_lib()? {
802 return Ok(t);
803 }
804 // Created without holding the app data borrow: the chunk runs
805 // under the hook, whose callbacks may touch app data.
806 let (table, wrap_channel) = crate::task_lib::create(&self.lua)?;
807 let lib = TaskLib {
808 table: self.lua.create_registry_value(table)?,
809 wrap_channel: self.lua.create_registry_value(wrap_channel)?,
810 };
811 {
812 let a = self.attached();
813 // A table stored meanwhile wins; `lib` is then dropped.
814 let _ = a.task.set(lib);
815 }
816 Ok(self
817 .cached_task_lib()?
818 .expect("the task table was just stored"))
819 }
820
821 #[cfg(feature = "tokio")]
822 fn cached_task_lib(&self) -> Result<Option<mlua::Table>, IsleError> {
823 let a = self.attached();
824 match a.task.get() {
825 Some(lib) => Ok(Some(self.lua.registry_value(&lib.table)?)),
826 None => Ok(None),
827 }
828 }
829
830 /// The `task` library's channel constructor, if `Vm::task_lib`
831 /// created the library.
832 #[cfg(feature = "tokio")]
833 pub(crate) fn channel_ctor(&self) -> Result<Option<mlua::Function>, IsleError> {
834 let a = self.attached();
835 match a.task.get() {
836 Some(lib) => Ok(Some(self.lua.registry_value(&lib.wrap_channel)?)),
837 None => Ok(None),
838 }
839 }
840
841 #[cfg(feature = "tokio")]
842 fn attached(&self) -> mlua::AppDataRef<'_, Attached> {
843 self.lua
844 .app_data_ref::<Attached>()
845 .expect("a Vm exists only for an attached VM")
846 }
847
848 /// Run `f(args)` as a root coroutine under `token`.
849 ///
850 /// Resolves only after everything the root started has ended: the
851 /// Lua tasks it spawned and the host tasks spawned through
852 /// [`current_scope`], transitively (contract 1 of the
853 /// [module docs](self)). Resolves to `Err(IsleError::Cancelled)` if
854 /// `token` was cancelled, whatever the coroutine returned; the
855 /// coroutine and its tasks then get the VM's [`Config::grace`], as
856 /// one deadline, before they are dropped. The cancellation error
857 /// raised by some other token (a host function that returned
858 /// `Err(mlua::Error::external(Cancelled))`) also resolves to
859 /// `Err(IsleError::Cancelled)`.
860 ///
861 /// A Lua error resolves to `Err(IsleError::Lua(f))`, where the
862 /// [`LuaFailure`] is built from the raised value itself on this
863 /// thread: `f.message` is `tostring(err)` and, with the `serde`
864 /// feature, `f.value` is the value as JSON (so `error({ code = 42 })`
865 /// gives `f.value["code"] == 42`).
866 ///
867 /// A task in a CPU loop cannot be dropped until it yields; without
868 /// [`Config::preempt_every`] the wait blocks on it.
869 ///
870 /// Await it inside a [`tokio::task::LocalSet`].
871 ///
872 /// # Dropping the future
873 ///
874 /// Dropping the returned future before it resolves (wrapping it in
875 /// [`tokio::time::timeout`], or a losing [`tokio::select!`] arm)
876 /// drops the coroutine at once but only schedules the tasks it
877 /// spawned for abort: tokio drops them on a later poll of the
878 /// `LocalSet`, as with
879 /// [`AbortHandle::abort`](tokio::task::AbortHandle::abort). To have
880 /// the tasks gone before you continue, [cancel](CancelToken::cancel)
881 /// the token and await the future instead of dropping it.
882 ///
883 /// ```rust
884 /// use mlua_isle::runtime::{CancelToken, Config, Vm};
885 /// use std::time::Duration;
886 ///
887 /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
888 /// let rt = tokio::runtime::Builder::new_current_thread().enable_all().build()?;
889 /// let local = tokio::task::LocalSet::new();
890 /// let lua = mlua::Lua::new();
891 ///
892 /// let vm = Vm::attach(&lua, Config { grace: Duration::from_secs(1), ..Default::default() })?;
893 /// lua.globals().set("task", vm.task_lib()?)?;
894 /// let main: mlua::Function = lua
895 /// .load("return function(x) local _, v = task.spawn(function() return x * 2 end):join() return v end")
896 /// .eval()?;
897 ///
898 /// let token = CancelToken::new();
899 /// let out = local.block_on(&rt, vm.run(&token, main, 21))?;
900 /// assert_eq!(out[0].as_i64(), Some(42));
901 /// # Ok(())
902 /// # }
903 /// ```
904 #[cfg(feature = "tokio")]
905 pub async fn run(
906 &self,
907 token: &CancelToken,
908 f: mlua::Function,
909 args: impl mlua::IntoLuaMulti,
910 ) -> Result<mlua::MultiValue, IsleError> {
911 let args = args.into_lua_multi(&self.lua)?;
912 crate::scope::run_root(&self.lua, token.clone(), f, args).await
913 }
914}
915
916/// Attach an actor's VM after its init closure ran.
917///
918/// With `config`, it replaces whatever the init closure configured;
919/// without, the VM keeps the init closure's settings (the default if it
920/// set none). The hook is (re-)installed either way, so a hook the init
921/// closure set with `Lua::set_hook` is replaced, as before.
922pub(crate) fn attach_after_init(lua: &Lua, config: Option<Config>) -> Result<Vm, IsleError> {
923 let config = config.unwrap_or_else(|| hub::config(lua));
924 Vm::attach(lua, config)
925}
926
927/// Make sure the VM is attached and its hook is in place, before a
928/// request runs. Re-installs the hook if `Lua::set_hook` replaced it;
929/// keeps the stored config.
930pub(crate) fn ensure_attached(lua: &Lua) -> Result<(), IsleError> {
931 let attached = lua.app_data_ref::<Attached>().is_some();
932 if attached {
933 hub::ensure_installed(lua)
934 } else {
935 // Unreachable for the actors (they attach before reporting a
936 // successful spawn); kept as a defensive path.
937 attach_after_init(lua, None).map(drop)
938 }
939}
940
941/// The [`Vm`] of `lua`, attaching it with its stored config (the
942/// default if none was set) when it is not attached yet.
943#[cfg(feature = "tokio")]
944pub(crate) fn of_or_attach(lua: &Lua) -> Result<Vm, IsleError> {
945 match Vm::of(lua) {
946 Some(vm) => Ok(vm),
947 None => attach_after_init(lua, None),
948 }
949}