mlua-isle 0.10.0

Thread-isolated Lua VM with cancellation, async coroutines, and connection pool for mlua
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
//! The Lua `task` library: its Lua part and the host functions under
//! it.  Crate-internal; documented in the [`runtime`](crate::runtime)
//! module docs ("The `task` library").

use crate::chan::{self, Chan, ChanUd, Receiving, Sending};
use crate::scope::{self, cancellable, ScopedTask, Spawned, Wrap};
use crate::select::{self, Cases, DefaultCase, SelectFuture, Timer, TimerUd};
use mlua::{AnyUserData, Function, Lua, MultiValue, Table, Value, Variadic};
use std::cell::{Cell, RefCell};
use std::collections::HashMap;
use std::rc::Rc;
use std::time::Duration;

const LIB: &str = r#"
local spawn_raw, join_raw, cancel_raw, done_raw, release_raw, is_cancel_error, CANCELLED, raw = ...
local rawequal, setmetatable, type, error = rawequal, setmetatable, type, error

local Task = {}
Task.__index = Task

function Task:join()
  if self._joined then error("task already joined", 2) end
  self._joined = true
  return join_raw(self._id)
end

function Task:cancel()
  if not self._joined then cancel_raw(self._id) end
end

function Task:done()
  return self._joined or done_raw(self._id)
end

Task.__close = function(self)
  if not self._joined then
    cancel_raw(self._id)
    self:join()
  end
end

Task.__gc = function(self)
  if not self._joined then release_raw(self._id) end
end

local task = { CANCELLED = CANCELLED }

function task.is_cancelled(err)
  return rawequal(err, CANCELLED) or is_cancel_error(err)
end

function task.spawn(f, ...)
  return setmetatable({ _id = spawn_raw(f, ...) }, Task)
end

-- Channels, timers and select.  The objects hold the host userdata
-- (`_c`, `_t`); `on` / `arm_recv` / `arm` build plain case tables
-- `{ kind, target, handler }` that the select host functions read.
local chan_raw, send_raw, try_send_raw = raw.chan, raw.send, raw.try_send
local recv_raw, try_recv_raw, close_raw = raw.recv, raw.try_recv, raw.close
local closed_raw, len_raw, cap_raw = raw.closed, raw.len, raw.cap
local after_raw, wait_raw = raw.after, raw.wait
local ticker_raw, stop_raw, task_case_raw = raw.ticker, raw.stop, raw.task_case
local select_handlers, select_raw = raw.select, raw.select_raw

local function check_handler(f)
  if type(f) ~= "function" then error("handler must be a function", 3) end
end

-- The case of a task handle: what `join` would return, once the task
-- has finished.  Choosing it marks the handle joined.
local function task_case(self, f)
  if self._joined then error("task already joined", 3) end
  return { kind = "task", target = task_case_raw(self._id), handle = self, handler = f }
end

function Task:on(f)
  check_handler(f)
  return task_case(self, f)
end

function Task:arm()
  return task_case(self)
end

local Channel = {}
Channel.__index = Channel

function Channel:send(v) return send_raw(self._c, v) end
function Channel:try_send(v) return try_send_raw(self._c, v) end
function Channel:recv() return recv_raw(self._c) end
function Channel:try_recv() return try_recv_raw(self._c) end
function Channel:close() close_raw(self._c) end
function Channel:closed() return closed_raw(self._c) end
function Channel:len() return len_raw(self._c) end
function Channel:cap() return cap_raw(self._c) end

function Channel:on(f)
  check_handler(f)
  return { kind = "recv", target = self._c, handler = f }
end

function Channel:arm_recv()
  return { kind = "recv", target = self._c }
end

function Channel:on_send(v, f)
  check_handler(f)
  return { kind = "send", target = self._c, value = v, handler = f }
end

function Channel:arm_send(v)
  return { kind = "send", target = self._c, value = v }
end

-- A ticker is a `Channel` (receive-only) with `stop`.
local Ticker = setmetatable({}, { __index = Channel })
Ticker.__index = Ticker

function Ticker:stop() stop_raw(self._tk) end

local Timer = {}
Timer.__index = Timer

function Timer:wait() return wait_raw(self._t) end

function Timer:on(f)
  check_handler(f)
  return { kind = "timer", target = self._t, handler = f }
end

function Timer:arm()
  return { kind = "timer", target = self._t }
end

function task.channel(cap)
  return setmetatable({ _c = chan_raw(cap) }, Channel)
end

function task.after(ms)
  return setmetatable({ _t = after_raw(ms) }, Timer)
end

function task.ticker(ms)
  local c, t = ticker_raw(ms)
  return setmetatable({ _c = c, _tk = t }, Ticker)
end

-- The host function calls the handler under `pcall` and returns
-- `ok, ...`; re-raise here so that the raw error value survives.
local function finish(ok, ...)
  if ok then return ... end
  error((...), 0)
end

function task.select(cases, opts)
  return finish(select_handlers(cases, opts))
end

task.select_raw = select_raw

-- A channel to the host (`runtime::channel_to_host`) is a `Channel`
-- (send-only).
local SendChannel = setmetatable({}, { __index = Channel })
SendChannel.__index = SendChannel

local function refuse(method)
  return function()
    error(method .. ": channel is send-only (a channel to the host; the host receives)", 2)
  end
end
SendChannel.recv = refuse("ch:recv")
SendChannel.try_recv = refuse("ch:try_recv")
SendChannel.on = refuse("ch:on")
SendChannel.arm_recv = refuse("ch:arm_recv")

-- The constructor `runtime::channel` wraps a host channel with (the
-- same `Channel` object as `task.channel`), and `runtime::channel_to_host`
-- a channel to the host (`send_only = true`).
local function wrap_channel(c, send_only)
  return setmetatable({ _c = c }, send_only and SendChannel or Channel)
end

return task, wrap_channel
"#;

/// The tasks started with `task.spawn` that were not joined yet, by
/// the id their Lua handle holds.
pub(crate) struct Registry {
    tasks: RefCell<HashMap<u64, Spawned<MultiValue>>>,
    next_id: Cell<u64>,
    /// `task.CANCELLED`.
    cancelled: Table,
}

impl Registry {
    pub(crate) fn get(&self, id: u64) -> mlua::Result<Spawned<MultiValue>> {
        self.tasks
            .borrow()
            .get(&id)
            .cloned()
            .ok_or_else(|| mlua::Error::runtime("unknown task"))
    }

    /// Forget a task that was joined.
    pub(crate) fn forget(&self, id: u64) {
        self.tasks.borrow_mut().remove(&id);
    }

    /// Take back a task whose join was undone.
    pub(crate) fn restore(&self, id: u64, task: Spawned<MultiValue>) {
        self.tasks.borrow_mut().insert(id, task);
    }

    /// What `join` returns for a cancelled task: `false, task.CANCELLED`.
    pub(crate) fn cancelled_values(&self) -> MultiValue {
        MultiValue::from_vec(vec![
            Value::Boolean(false),
            Value::Table(self.cancelled.clone()),
        ])
    }
}

/// The target of a task case (`h:on(f)` / `h:arm()`): the task behind a
/// handle.
pub(crate) struct TaskUd {
    pub(crate) id: u64,
    pub(crate) reg: Rc<Registry>,
}

impl mlua::UserData for TaskUd {}

/// The host side of a ticker (`tk._tk`): the host task that feeds its
/// channel.  Dropping it (`stop`, or when the ticker is collected)
/// cancels the task.
struct TickerUd {
    task: RefCell<Option<ScopedTask<()>>>,
    chan: Chan,
}

impl mlua::UserData for TickerUd {}

/// Closes a ticker's channel when its host task ends, however it ends
/// (stopped, cancelled with its scope, or dropped at the end of the
/// grace).
struct CloseOnDrop(Chan);

impl Drop for CloseOnDrop {
    fn drop(&mut self) {
        chan::close(&self.0);
    }
}

/// Create the `task` library table for `lua`, and the function that
/// wraps a channel userdata (`ChanUd`) in the library's `Channel`
/// object (for `runtime::channel`).  Called once per VM by
/// [`Vm::task_lib`](crate::runtime::Vm::task_lib), which documents the
/// library.
pub(crate) fn create(lua: &Lua) -> mlua::Result<(Table, Function)> {
    let cancelled_marker = lua.create_table()?;
    cancelled_marker.set_metatable(Some(lua.create_table_from([(
        "__tostring",
        lua.create_function(|_, _: Value| Ok("task.CANCELLED"))?,
    )])?))?;
    let reg = Rc::new(Registry {
        tasks: RefCell::new(HashMap::new()),
        next_id: Cell::new(0),
        cancelled: cancelled_marker.clone(),
    });

    let r = reg.clone();
    let spawn_raw = lua.create_function(move |lua, (f, args): (Function, Variadic<Value>)| {
        let scope = scope::current().ok_or_else(|| {
            mlua::Error::runtime(
                "task.spawn: not inside a coroutine request or task (sync requests cannot spawn)",
            )
        })?;
        let grace = crate::hub::config(lua).grace;
        let (root, body) = scope::lua_body(lua, Wrap::PCall, f, MultiValue::from_iter(args))?;
        // `None` in the result slot means cancelled.
        let task = scope.spawn(grace, Some(root), body, |out, token| match out {
            None => None,
            Some(Ok(values)) => {
                let failed = matches!(values.front(), Some(Value::Boolean(false)));
                if failed && token.is_cancelled() {
                    None
                } else {
                    Some(values)
                }
            }
            Some(Err(e)) if token.is_cancelled() => {
                drop(e);
                None
            }
            Some(Err(e)) => Some(MultiValue::from_vec(vec![
                Value::Boolean(false),
                scope::error_value(e),
            ])),
        });

        let id = r.next_id.get();
        r.next_id.set(id + 1);
        r.tasks.borrow_mut().insert(id, task);
        Ok(id)
    })?;

    let r = reg.clone();
    let join_raw = lua.create_async_function(move |_, id: u64| {
        let r = r.clone();
        async move {
            let task = r.get(id)?;
            task.state.wait_done().await;
            r.forget(id);
            let out = task.result.borrow_mut().take();
            Ok(match out {
                Some(values) => values,
                None => r.cancelled_values(),
            })
        }
    })?;

    let r = reg.clone();
    let cancel_raw = lua.create_function(move |_, id: u64| {
        r.get(id)?.state.token.cancel();
        Ok(())
    })?;

    let r = reg.clone();
    let done_raw = lua.create_function(move |_, id: u64| Ok(r.get(id)?.state.is_done()))?;

    let r = reg.clone();
    let release_raw = lua.create_function(move |_, id: u64| {
        if let Some(task) = r.tasks.borrow_mut().remove(&id) {
            task.state.token.cancel();
        }
        Ok(())
    })?;

    // True for the error a cancel raises: mlua hands a Rust error
    // (`WrappedFailure` userdata) to Rust as `Value::Error`.
    let is_cancel_error = lua.create_function(|_, v: Value| {
        Ok(matches!(&v, Value::Error(e) if crate::error::is_cancel(e)))
    })?;

    lua.load(LIB).set_name("=mlua_isle.tasks").call((
        spawn_raw,
        join_raw,
        cancel_raw,
        done_raw,
        release_raw,
        is_cancel_error,
        cancelled_marker,
        channel_parts(lua, reg)?,
    ))
}

/// Calls a select handler as `pcall(f, ...)`.  A tail call: once
/// `pcall` returns, no instruction of this function runs, so an error
/// that escapes it was raised before the handler was entered.
const CALL_HANDLER: &str = "local pcall = pcall return function(f, ...) return pcall(f, ...) end";

fn closed_error(method: &str) -> mlua::Error {
    mlua::Error::runtime(format!("{method}: channel is closed"))
}

/// The error of a send into a receive-only channel (a host channel or
/// a ticker), `Ok` for a local channel.
fn check_sendable(method: &str, chan: &Chan) -> mlua::Result<()> {
    match chan::receive_only(chan) {
        None => Ok(()),
        Some(why) => Err(mlua::Error::runtime(format!(
            "{method}: channel is receive-only ({why})"
        ))),
    }
}

/// The error of a receive from a send-only channel (a channel to the
/// host), `Ok` otherwise.
fn check_receivable(method: &str, chan: &Chan) -> mlua::Result<()> {
    match chan::send_only(chan) {
        None => Ok(()),
        Some(why) => Err(mlua::Error::runtime(format!(
            "{method}: channel is send-only ({why})"
        ))),
    }
}

/// The period of `task.ticker(ms)`.
fn ticker_period(ms: f64) -> mlua::Result<Duration> {
    if ms.is_nan() || ms <= 0.0 {
        return Err(mlua::Error::runtime("task.ticker: ms must be > 0"));
    }
    Duration::try_from_secs_f64(ms / 1000.0)
        .ok()
        .filter(|d| !d.is_zero())
        .ok_or_else(|| mlua::Error::runtime("task.ticker: ms is out of range"))
}

/// The host task of a ticker: push the time of each tick (milliseconds
/// since `start`, the tick's scheduled time) into `chan`, keeping only
/// the newest unread one, until the task's token is cancelled or the
/// channel is closed.  Closes the channel when it ends.
async fn run_ticker(chan: Chan, start: tokio::time::Instant, period: Duration) {
    let _close = CloseOnDrop(chan.clone());
    let token = crate::hook::current_token();
    let mut ticks = tokio::time::interval_at(start + period, period);
    ticks.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
    loop {
        let at = match &token {
            Some(token) => tokio::select! {
                biased;
                _ = token.cancelled() => return,
                at = ticks.tick() => at,
            },
            None => ticks.tick().await,
        };
        let ms = (at - start).as_nanos() as f64 / 1e6;
        if !chan::push_newest(&chan, Value::Number(ms)) {
            return;
        }
    }
}

/// The host functions under channels, timers and select, as the table
/// `raw` that the library's Lua part reads.
fn channel_parts(lua: &Lua, reg: Rc<Registry>) -> mlua::Result<Table> {
    let raw = lua.create_table()?;

    raw.set(
        "chan",
        lua.create_function(|_, cap: Value| {
            let cap = match cap {
                Value::Integer(n) => Some(n),
                Value::Number(n) if n.fract() == 0.0 => Some(n as i64),
                _ => None,
            };
            match cap {
                Some(n) if n >= 0 => Ok(ChanUd(chan::new(n as usize))),
                _ => Err(mlua::Error::runtime(
                    "task.channel: cap must be an integer >= 0",
                )),
            }
        })?,
    )?;

    raw.set(
        "send",
        lua.create_async_function(|lua, (ud, v): (AnyUserData, Value)| {
            let chan = select::chan_of(&ud);
            async move {
                let chan = chan?;
                check_sendable("ch:send", &chan)?;
                let mut send = Sending::new(chan, v, None);
                select::wait_send(&mut send, &lua)
                    .await?
                    .map_err(|_| closed_error("ch:send"))
            }
        })?,
    )?;

    raw.set(
        "try_send",
        lua.create_function(|lua, (ud, v): (AnyUserData, Value)| {
            let chan = select::chan_of(&ud)?;
            check_sendable("ch:try_send", &chan)?;
            chan::try_send(&chan, lua, v)?.map_err(|_| closed_error("ch:try_send"))
        })?,
    )?;

    raw.set(
        "recv",
        lua.create_async_function(|lua, ud: AnyUserData| {
            let chan = select::chan_of(&ud);
            async move {
                let chan = chan?;
                check_receivable("ch:recv", &chan)?;
                let mut recv = Receiving::new(chan, None);
                let got = cancellable(std::future::poll_fn(|cx| recv.poll(cx, &lua))).await?;
                Ok(select::recv_values(got))
            }
        })?,
    )?;

    raw.set(
        "try_recv",
        lua.create_function(|lua, ud: AnyUserData| {
            let chan = select::chan_of(&ud)?;
            check_receivable("ch:try_recv", &chan)?;
            Ok(match chan::try_recv(&chan, lua)? {
                chan::TryRecv::Value(v) => (v, true, true),
                chan::TryRecv::Closed => (Value::Nil, false, true),
                chan::TryRecv::Empty => (Value::Nil, false, false),
            })
        })?,
    )?;

    raw.set(
        "close",
        lua.create_function(|_, ud: AnyUserData| {
            chan::close(&select::chan_of(&ud)?);
            Ok(())
        })?,
    )?;
    raw.set(
        "closed",
        lua.create_function(|_, ud: AnyUserData| Ok(chan::is_closed(&select::chan_of(&ud)?)))?,
    )?;
    raw.set(
        "len",
        lua.create_function(|_, ud: AnyUserData| Ok(chan::len(&select::chan_of(&ud)?)))?,
    )?;
    raw.set(
        "cap",
        lua.create_function(|_, ud: AnyUserData| Ok(chan::cap(&select::chan_of(&ud)?)))?,
    )?;

    raw.set(
        "after",
        lua.create_function(|_, ms: f64| Ok(TimerUd(Timer::after(ms)?)))?,
    )?;

    raw.set(
        "wait",
        lua.create_async_function(|_, ud: AnyUserData| {
            let timer = ud.borrow::<TimerUd>().map(|t| t.0);
            async move {
                let timer = timer?;
                cancellable(async move {
                    tokio::time::sleep_until(timer.deadline).await;
                    Ok(())
                })
                .await
            }
        })?,
    )?;

    raw.set(
        "ticker",
        lua.create_function(|_, ms: f64| {
            let period = ticker_period(ms)?;
            let scope = scope::current_scope().ok_or_else(|| {
                mlua::Error::runtime(
                    "task.ticker: not inside a coroutine request or task (sync requests cannot tick)",
                )
            })?;
            let chan = chan::new_ticker();
            let start = tokio::time::Instant::now();
            let task = scope.spawn_local(run_ticker(chan.clone(), start, period));
            let ticker = TickerUd {
                task: RefCell::new(Some(task)),
                chan: chan.clone(),
            };
            Ok((ChanUd(chan), ticker))
        })?,
    )?;

    raw.set(
        "stop",
        lua.create_function(|_, ud: AnyUserData| {
            let t = ud.borrow::<TickerUd>()?;
            // Dropping the `ScopedTask` cancels the host task.
            let task = t.task.borrow_mut().take();
            drop(task);
            chan::close(&t.chan);
            Ok(())
        })?,
    )?;

    raw.set(
        "task_case",
        lua.create_function(move |_, id: u64| {
            reg.get(id)?;
            Ok(TaskUd {
                id,
                reg: reg.clone(),
            })
        })?,
    )?;

    raw.set(
        "select_raw",
        lua.create_async_function(|lua, (cases, opts): (Table, Option<Table>)| {
            let cases = select::read_cases(&lua, "task.select_raw", cases, opts, false);
            async move {
                let Cases {
                    arms,
                    mark,
                    default,
                    start,
                    ..
                } = cases?;
                let mut sel = SelectFuture {
                    arms,
                    start,
                    mark,
                    lua: lua.clone(),
                };
                let (i, mut values) = match default {
                    DefaultCase::None => select::wait_select(&mut sel).await?,
                    _ => match sel.poll_now() {
                        Some(out) => out?,
                        None => return Ok(MultiValue::from_vec(vec![Value::Integer(0)])),
                    },
                };
                values.push_front(Value::Integer(i as i64 + 1));
                Ok(values)
            }
        })?,
    )?;

    let call_handler: Function = lua
        .load(CALL_HANDLER)
        .set_name("=mlua_isle.select")
        .eval()?;
    raw.set(
        "select",
        lua.create_async_function(move |lua, (cases, opts): (Table, Option<Table>)| {
            let cases = select::read_cases(&lua, "task.select", cases, opts, true);
            let call = call_handler.clone();
            async move {
                let Cases {
                    arms,
                    mark,
                    handlers,
                    default,
                    start,
                } = cases?;
                let mut sel = SelectFuture {
                    arms,
                    start,
                    mark,
                    lua: lua.clone(),
                };
                let (i, values) = match default {
                    DefaultCase::Handler(f) => match sel.poll_now() {
                        Some(out) => out?,
                        // `poll_now` withdrew every case: no offer of
                        // this select stays open while `default` runs.
                        None => return call.call_async::<MultiValue>(f).await,
                    },
                    _ => select::wait_select(&mut sel).await?,
                };
                // Call the handler in this same poll: no Lua code runs
                // between the take and the handler, so a cancel arrives
                // either before the take (the wait above returned it)
                // or inside the handler.
                let mut args = values.clone();
                args.push_front(Value::Function(handlers[i].clone()));
                match call.call_async::<MultiValue>(args).await {
                    Ok(out) => Ok(out),
                    Err(e) => {
                        // Raised before `pcall` entered the handler (the
                        // cancel hook, say): the handler never had the
                        // value, so give it back (a sent value stays
                        // sent).
                        sel.arms[i].untake(values);
                        Err(e)
                    }
                }
            }
        })?,
    )?;

    Ok(raw)
}