Skip to main content

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}