Expand description
Running Lua on a VM you own: the in-thread layer of the crate.
The crate has two layers. The actors (Isle,
AsyncIsle, the pools) put a VM on a thread of their own and take
requests over channels. This module is the layer underneath: a host
that owns the Lua and drives the executor itself (its own thread
and LocalSet)
uses it directly, and the actors are built on it.
Vm is the entry point: Vm::attach takes over the VM’s debug
hook, stores its Config and creates the task library. The
hook part (attach, of, config, set_config, add_hook,
remove_hook) is always available; Vm::run, Vm::task_lib,
cancellable and current_scope need the tokio feature. With
it, setup is three calls (see Vm::run for the full example):
let vm = Vm::attach(&lua, Config { grace: Duration::from_secs(1), ..Default::default() })?;
lua.globals().set("task", vm.task_lib()?)?;
let out = local.run_until(vm.run(&token, main, ())).await?;§Contracts
- When
runresolves, nothing the root started is alive. This holds for Lua tasks (task.spawn) and for host tasks spawned through the scope (current_scope()thenScopeHandle::spawn_local), transitively and in any mix, whether the root finished or was cancelled. A host task that ignores its token is dropped when the grace ends. Tasks spawned into a scope that is already ending share its remaining time; a spawn after the remaining time is gone starts nothing. The layer does not drain the host’sLocalSet: aspawn_localthat bypasses the scope (for examplecurrent_token().child_token()plus a baretokio::task::spawn_local) is cancelled with the request but is neither waited for nor dropped, and is the host’s responsibility. This holds whenrunis awaited to the end: dropping therunfuture instead only schedules the tasks for abort, and a task in a CPU loop blocksrununtil it yields, which withoutConfig::preempt_everyit never does. - One error type,
IsleError, on this layer and on the actors, with one payload for a Lua error:IsleError::Luacarries aLuaFailure(kind, message as Lua prints it, traceback, and with theserdefeature the raised value as JSON), built on the VM thread from the raised value, the same forrunand for every actor request. A cancel isIsleError::Cancelled, recognised by value: the cancel error ismlua::Error::external(Cancelled), found by downcast, never by message. - The layer owns the VM’s debug hook. Register callbacks with
Vm::add_hook, never withLua::set_hook/Lua::set_global_hook, which replace the hook and stop cancellation (see Hooks). - One
Configper VM, read and written throughVm(Vm::config,Vm::set_config; a secondVm::attachreplaces it). - Cancellation is a token the host creates and passes to
run;runspawns nothing and returns no handle. Ctrl-C, a timeout or a hook callback cancel thatCancelToken.
Two requirements on the VM itself: attach it before sandboxing its
globals (the first Vm::attach captures xpcall), and keep mlua’s
default LuaOptions::catch_rust_panics = true, whose xpcall is
yieldable (with false every yield in a run root fails; see
Vm::attach).
Host functions called from Lua reach the running request or task
through the context functions, which read a thread-local and so take
no receiver: current_token, cancellable and current_scope.
§Hooks
Lua has one hook slot per thread, and mlua’s hook setters replace
whatever was there, so the layer owns the VM’s hook: Vm::attach
installs a single global hook (one callback shared by every
thread of the VM, including coroutines the Lua code creates) that,
in order,
- raises the cancellation error (
Cancelled) when the token of the request or task currently executing is cancelled (checked every 1000 instructions; a check that lands in the code mlua uses to return an async host function’s results is deferred, see Channels, timers and select), - calls the callbacks registered with
Vm::add_hook, each at its ownHookTriggers, - yields the running root coroutine or task every N checks when
preemption is enabled (
Config::preempt_every).
Calling Lua::set_hook, Lua::set_global_hook or
mlua::Thread::set_hook on the VM replaces this hook, and
cancellation stops working. The hook is re-installed when a
set_hook replacement is noticed (at the start of every actor
request and of every Vm::run), but a replacement through
set_global_hook cannot be detected.
§The task library
Vm::task_lib (tokio feature) returns the VM’s task table,
conventionally set as the global task:
| Lua | meaning |
|---|---|
task.spawn(f, ...) | Start f(...) as a concurrent task of the current coroutine request or task. Returns a handle. |
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). |
h:cancel() | Request cancellation. Does not wait. |
h:done() | Whether the task has finished. |
local h <close> = task.spawn(...) | On scope exit, a task that was not joined is cancelled and waited for. |
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. |
task.CANCELLED | What join returns as err for a cancelled task. |
task.channel(cap) | A local channel holding up to cap values (cap >= 0; cap = 0 is a rendezvous channel). See Channels, timers and select. |
ch:send(v) | Push v; waits while the channel is full (rendezvous: until a receiver has taken v). Raises when the channel is closed. |
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. |
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. |
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). |
ch:close() | Close the channel. Idempotent. |
ch:closed(), ch:len(), ch:cap() | Whether it is closed; how many values it holds; its capacity. |
task.after(ms) | A one-shot timer, ready ms milliseconds after this call (ms <= 0: at once) and from then on. |
t:wait() | Wait until the timer is ready. |
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. |
tk:stop() | Stop the ticker and close its channel. Idempotent. |
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. |
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. |
ch:arm_recv(), ch:arm_send(v), t:arm(), h:arm() | A case for task.select_raw. |
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. |
req.value, req:reply(v), req:replied(), local req <close> = ... | A Request received from a host channel. See Host channels and requests. |
A host channel (channel) and a ticker are Channel objects like
task.channel’s, receive-only: send / try_send and send cases
raise. A channel to the host (channel_to_host) is one too,
send-only: recv / try_recv / on / arm_recv and receive cases
raise.
Tasks are structured: when a coroutine request or task finishes,
the tasks it spawned and did not join are cancelled, and it waits
for them before its own result is delivered. Cancelling a request
or task cancels all of its tasks (their tokens are children of its
token, see CancelToken::child_token), and the cancelled request
or task still resolves only after they, and their own tasks, have
finished or been dropped. The grace is one deadline
for the whole tree: a task spawned during cleanup gets the time that
remains, not a fresh grace period.
task.spawn works inside Vm::run, inside coroutine requests
(AsyncIsle::coroutine_eval / coroutine_call) and inside tasks
(including host tasks). Sync requests (eval / call / exec)
cannot await, so task.spawn raises an error there.
A cancel reaches Lua code as an error: the cancel hook raises it
while Lua code runs, and an async host function wrapped with
cancellable returns it while the coroutine awaits. Its value is
mlua::Error::external(Cancelled) (a userdata to Lua);
task.is_cancelled(err) is the test, and it is also true for
task.CANCELLED, so one predicate covers both:
local ok, err = pcall(sleep, 1000)
if not ok and task.is_cancelled(err) then
-- cancelled: clean up and let the cancel continue
error(err, 0)
endThe predicate lives in the library: a VM that runs without the task
table has no task.is_cancelled; Rust code tests an mlua::Error
with e.downcast_ref::<Cancelled>().
A task that runs a CPU loop never yields on its own, so a sibling on
the same thread cannot run to cancel it; enable
Config::preempt_every for that. Cancelling from another thread
(an AsyncTask handle) works without it.
§Channels, timers and select
The task library passes values between the tasks of one VM with
local channels, and waits on several of them (and on timers) at
once with select:
local requests = task.channel(16)
local worker = task.spawn(function()
while true do
local stop = task.select({
requests:on(function(req, ok)
if not ok then return true end -- closed and drained
handle(req)
return false
end),
task.after(1000):on(function() idle() return false end),
})
if stop then return end
end
end)
requests:send(req)Channels
- FIFO, with any number of senders and receivers inside one VM. Waiting receivers are woken in arrival order.
- Values are Lua values as they are (
nilincluded); tables are shared, not copied. - After
close:send/try_sendraise;recvreturns what is left, in order, thennil, false. - A channel belongs to no scope: cancelling a task does not close it. When the channel is garbage-collected, its contents are dropped. The values are held from Rust, out of the collector’s sight, so a value that refers back to its own channel keeps both alive.
- Without
Config::preempt_every, a sender that never waits (atry_sendloop) keeps receivers on the same thread from running;send, which waits when the channel is full, is the form to use.
Rendezvous channels (task.channel(0))
- A sender posts an offer and waits until a receiver takes it:
sendreturns once a receiver has taken the value. Receivers take offers in the order they were posted (FIFO among senders). try_sendsucceeds only when a receiver is waiting right now (arecv, or a select’s receive case: the two wait the same way); it hands the value to the first waiting receiver and posts nothing.try_recvtakes the first offer.len()andcap()are0. The one exception is a value handed to a waiting receiver that then did not take it (its select chose another case, or it was cancelled): the value goes back to the front of the channel, counts inlen(), and is received next.- A select never pairs its own send case with its own receive case on the same channel; two different selects do pair.
- A select whose send case’s offer was taken chooses that case, even
if another case is ready by the time it runs again: the value is
delivered. At most one of a select’s offers is taken. When a
select chooses another case (or runs
default, or is cancelled), its offers are withdrawn and are never received. close: waiting senders raise “channel is closed” (a send case is chosen withsent = false); waiting receivers getnil, false.- With
default, a send case on a rendezvous channel is ready on the first check when a receiver is waiting (arecv, or another select’s receive case): its value goes to the first such receiver, as withtry_send, and the case is chosen withsent = true. With no receiver waiting,defaultruns and nothing is posted, so the value is never received.
Timers: task.after(ms) is ready once ms milliseconds have
passed since it was created (ms <= 0: at once). It may be waited
on, or used as a case, any number of times; once ready it stays
ready.
Tickers: task.ticker(ms) is a receive-only channel of capacity
1 that a host task, spawned into the scope of the request or task
that called it (as ScopeHandle::spawn_local does), feeds every ms
milliseconds.
- A tick is the tick’s scheduled time in milliseconds since the
ticker started:
ms,2 * ms, … (the tick count is the value divided byms). - Only the newest tick is kept: an unread tick is replaced, not
queued. Ticks that a busy VM missed are skipped
(
tokio::time::MissedTickBehavior::Skip). tk:stop()stops the host task and closes the channel; a tick already in it can still be received. The ticker also stops, and its channel closes, when the scope that created it ends or is cancelled (within the grace), when Lua closes the channel, and when the ticker object is collected.- Outside a coroutine request or task (a sync request)
task.tickerraises.
Send cases (ch:on_send(v, f) / ch:arm_send(v), local channels
and channels to the host)
- Ready when
vcan be pushed (room in a buffered channel; for a rendezvous channel, once a receiver has taken the offer; for a channel to the host, once room is reserved) or when the channel is closed (sent = false). The value enters the channel only for the chosen case.
Task cases (h:on(f) / h:arm(), a task.spawn handle)
- Ready when the task has finished. The case returns what
h:join()would (true, ...,false, errwith the raw error value, orfalse, task.CANCELLED) and marks the handle joined. - A case that is not chosen leaves the handle unjoined: it can be joined, or used in another select, later.
- Building a case from a joined handle raises, and so does a select given a case whose handle was joined since.
- A handle that is joined elsewhere (
h:join(), or another select’s case) while a select waits on its case: the join takes the result, and the waiting select raises “task already joined” once the task has finished.
select
- Exactly one ready case is chosen. Cases that are not chosen consume nothing.
- Order: round robin per VM by default (each select starts one
position after the previous one; deterministic, so tests are
reproducible).
biased = truechecks the cases in the given order. default: if no case is ready on the first check,selectrunsdefault(select_rawreturns0) without waiting.- A closed, empty channel is ready: its case is chosen with
ok = false. It stays ready, so a loop that keeps a closed channel in its case list keeps selecting it. - An empty case list without
defaultraises. - A handler runs as Lua code inside the select and may await (and
select again); an error it raises is re-raised by
selectwith its raw value. While it runs, the other cases are not watched: move long work intotask.spawn.Config::preempt_everydoes not preempt a handler either: it runs in a coroutine that the select’s host call creates, not in a root or task (#22).
Delivery and cancellation. The cancel hook can raise at any instruction count check, including the instructions between a host function returning a value and the Lua code that uses it. The library defines when a value is delivered:
- A wait (
recv,send,t:wait(),select,select_raw) that is cancelled before it is ready returns the cancel error and has consumed nothing (a cancelledsendsent nothing). The wait is wrapped incancellable, which checks the token first, so a poll that returns the cancel never also polled the cases. recvandselect_raw: a value is delivered when the call returns it. A cancel raised after that, in the caller’s code, is the caller’s to handle, as for any other value it holds.- A send (
send, a send case) is delivered when its value is in the channel (buffered) or taken by a receiver (rendezvous), and it cannot be taken back. A rendezvoussendwhose offer was taken before the cancel was seen returns normally (sent), and a select whose send case’s offer was taken chooses that case, rather than returning the cancel; a cancel seen before the offer was taken withdraws it (nothing sent). An error raised after a send case was delivered and before its handler is entered is re-raised; the value stays sent. - A task case is delivered like a received value: if the handler is never entered, the handle is left unjoined.
select: a value is delivered when the chosen handler is entered with it.selecttakes the value and calls the handler inside the same host call, so a cancel arrives either before the take (nothing consumed) or inside the handler (the handler has the value). An error raised after the take but before the handler is entered puts the value back at the front of its channel.- Between a host function’s future becoming ready and the call
returning, mlua runs a few instructions of Lua code of its own (the
loop that polls the future). The cancel hook does not raise there:
it raises at the next check outside that code (or the next
cancellablewait returns the cancel), so a valuerecvorselect_rawtook reaches the caller, and asendthat pushed its value returns normally. This holds for every async host function, not only the library’s. A program that keeps landing its checks in that code (an async host function that is always ready and notcancellable, called in a tight loop) is still cancelled: the hook defers at most 16 checks before it raises anyway. The code is recognised by its chunk name, which mlua keeps from 0.12.2 on (the crate requires it).
A task waiting in a select (or any of these waits) is cancelled with its scope and ends within the grace like any other wait.
§Host channels and requests
channel (tokio feature) creates a channel that Send host
code feeds into a running Lua loop: a Sender (Send + Clone)
and its Lua side, a LuaChannel (the task library’s Channel
object). A channel of Requests carries values that Lua answers:
let (tx, events) = channel::<Event>(&lua, 1024)?; // on the VM thread
lua.globals().set("events", events)?;
tx.send(ev).await?; // any thread or task
let (req_tx, requests) = channel::<Request<Call, Answer>>(&lua, 256)?;
lua.globals().set("requests", requests)?;
let answer = tokio::time::timeout(limit, req_tx.request(call)).await??;task.select({
events:on(function(ev, ok) ... end),
requests:on(function(req, ok)
if ok then req:reply(answer_for(req.value)) end
end),
})Call channel on the VM thread, after Vm::attach and
Vm::task_lib; for an AsyncIsle, in an
exec request that returns the Sender (example on channel).
Channel
cap >= 1(a tokio bounded channel;cap = 0is an error: host channels have no rendezvous form).ch:cap()iscap;ch:len()counts the values queued by the host plus any put back (below).- On the Lua side it behaves as a local channel: FIFO, any number of
Lua receivers, the same
recv/try_recv/close/closed/len/capand the sameselectcontract.send/try_sendraise (“channel is receive-only”). - A value is converted to a Lua value (
T: IntoLua) when Lua takes it, on the VM thread. A conversion error is raised to the receiver (recv,try_recv,select,select_raw), and that value is dropped; the next receive takes the next value. - Closed when every
Senderis dropped (receivers get the queued values first, thennil, false), or when Lua callsclose: the host’s sends then fail with the value given back (SendError,TrySendError::Closed) and the values already queued can still be received. When the Lua side is collected (or the VM dropped), the host’s sends fail as closed.Sender::is_closedreports both. - Ordering between several
Senders is the order in which their sends complete. Sender::sendwaits while the channel is full;Sender::try_sendreturnsTrySendError::Full. There is nosend_timeout: wrapsend(orrequest) intokio::time::timeout; a send that times out sent nothing.- Several Lua receivers: every value is received exactly once, and no
receiver is left asleep while a value is queued, including when a
woken receiver’s
selectchooses another case or the receiver is cancelled. (A tokioReceiverwakes only the task that polled it last; the channel polls it with a waker that wakes every waiting receiver.)
Request
- A
Request<Req, Resp>carries aReqand a one-shot reply.Sender::requestsends it and waits for the reply:RequestError::Closed(with theReq) if the channel is closed,RequestError::NoReplyif the request is closed or collected without a reply (or theReqfailed to convert to a Lua value). - On the Lua side it is a userdata:
req.valueis theReq(converted withIntoLuawhen Lua received it);req:reply(v)convertsvwithResp: FromLuaand returnstrue, orfalsewhen the requester stopped waiting (its future was dropped, e.g. by a timeout; not an error). A secondreplyraises, and so does areplyafter the request was closed. A conversion error raises and leaves the request unanswered: it can be answered again.req:replied()is whether areplysucceeded. - Closing an unanswered request (
local req <close> = ..., at scope exit or on an error) answersNoReplyat once. A request that is neither answered nor closed is reportedNoReplyonly when Lua collects it, so a requester should use a timeout, and Lua code that may fail between receiving and replying should hold the request in a<close>variable. select’s handler form does not close a request its handler returns without answering: the handler may hand it to a task that replies later. Close it in the handler (or let it be collected).
Delivery and cancellation are as for local channels (above): a
wait cancelled before it is ready consumed nothing, and a value
select took for a handler that was never entered goes back to the
front of the channel, ahead of the values the host queued (the Lua
side keeps a front buffer for it; the tokio channel itself cannot
take a value back).
§Channels to the host
channel_to_host (tokio feature) creates a channel that a running
Lua loop feeds and Send host code drains: its Lua side, a
LuaChannel (the task library’s Channel object, send-only), and
a Receiver (Send, not Clone) for the host:
let (reports, mut rx) = channel_to_host::<Report>(&lua, 64)?; // on the VM thread
lua.globals().set("reports", reports)?;
while let Some(r) = rx.recv().await { ... } // any thread or task
rx.try_recv(); // Ok(v), Err(TryRecvError::Empty), Err(TryRecvError::Closed)
rx.close(); // Lua's sends raise from now on; queued values can still be receivedreports:send(r) -- waits while full
local ok = reports:try_send(r) -- false when full
task.select({ reports:on_send(r, function(sent) ... end) })
reports:close() -- the host receives the queued values, then NoneCall channel_to_host on the VM thread, after Vm::attach and
Vm::task_lib; for an AsyncIsle, in the init closure of
AsyncIsleBuilder::spawn_with, which returns the Receiver (example
on channel_to_host), or in an exec request that returns it.
cap >= 1(a tokio bounded channel;cap = 0is an error). One host receiver; any number of Lua senders (tasks, selects).ch:cap()iscap;ch:len()is the number of values queued for the host (0once Lua closed the channel).- Each Lua send first reserves room in the tokio channel (tokio’s
Sender::reserve_owned; every waiting Lua sender has its own place in tokio’s queue, in the order they started waiting). Then the value is converted toT(T: FromLua) on the VM thread and queued, in the same step. A value that fails to convert raises in the sender (send,try_send, or the select with the chosenon_sendcase) and is not queued; its room is given back. sendwaits while the channel is full;try_sendreturnsfalsewhen full. Both raise “channel is closed” when the channel is closed: byrx.close(), by droppingrx, or by Lua’sclose. Waiting senders wake and raise at the close.- A send case (
on_send/arm_send) is ready when room is reserved, or when the channel is closed (sent = false); it converts and queues the value only when it is chosen. Withdefault, it is ready only when there is room at the first check (try_reserve). - Lua’s
close: the host receives the values already queued, thenrecvreturnsNone(try_recvClosed). When the Lua side is collected (or the VM dropped), the same.rx.close()keeps the queued values receivable. - Delivery: a send is delivered when its value is in the tokio
queue. A send cancelled before that (a cancelled
send, a select that chose another case or was cancelled) consumed nothing: its reservation, if it had one, is released, and the room goes to the next waiting sender. recv,try_recv,on,arm_recvraise (“channel is send-only”), and so does a select given a receive case built by hand on such a channel.- Ordering between several Lua senders is the order in which their sends complete; each value arrives exactly once.
§Host tasks
A host function that starts work of its own takes the scope of the
running request or task with current_scope() and spawns into it
with ScopeHandle::spawn_local. Such a task is structured like a
Lua task: it is cancelled when the request or task ends or is
cancelled, gets the grace (one deadline for the whole tree), is
dropped when the grace ends, and is waited for. Take the handle in
the synchronous part of the host function (the create_function
body, or a create_async_function body before its first .await)
and move it into the future; current_scope() is Some only while
a coroutine request or task is being polled, so it is None in a
sync request. spawn_local returns a ScopedTask; there are three
ways to let go of it: await it (wait for the value), keep it for as
long as the task should run (dropping it cancels the task now), or
detach() it (fire and forget: the task runs on without a handle and
is still cancelled, given the grace, dropped and waited for when the
scope ends).
let bg = lua.create_function(|_, ()| {
let scope = current_scope().expect("inside a coroutine request");
scope.spawn_local(async move { /* host work */ }).detach();
Ok(())
})?;Structs§
- Cancel
Token - Cancellation signal shared between caller and Lua thread.
- Cancelled
- The error a cancellation raises in Lua.
- Config
- Settings of a VM. One per VM, read and written through
Vm(Vm::attach,Vm::config,Vm::set_config). - HookId
- Handle of a callback registered with
Vm::add_hook. - LuaFailure
- A Lua error, as it crosses from the VM thread to Rust.
- Vm
- The in-thread handle of a Lua VM run by this crate.
Enums§
- Isle
Error - Errors returned by Isle operations.
- LuaError
Kind - What kind of Lua error a
LuaFailureis.
Functions§
- current_
token - Token of the request or task currently executing on this thread.