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
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
//! Running Lua on a VM you own: the in-thread layer of the crate.
//!
//! The crate has two layers. The actors ([`Isle`](crate::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`](https://docs.rs/tokio/latest/tokio/task/struct.LocalSet.html))
//! 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):
//!
//! ```text
//! 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
//!
//! 1. **When `run` resolves, nothing the root started is alive.** This
//! holds for Lua tasks (`task.spawn`) and for host tasks spawned
//! through the scope (`current_scope()` then
//! `ScopeHandle::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's `LocalSet`: a `spawn_local` that bypasses the
//! scope (for example `current_token().child_token()` plus a bare
//! `tokio::task::spawn_local`) is cancelled with the request but is
//! neither waited for nor dropped, and is the host's
//! responsibility. This holds when `run` is awaited to the end:
//! dropping the `run` future instead only schedules the tasks for
//! abort, and a task in a CPU loop blocks `run` until it yields,
//! which without [`Config::preempt_every`] it never does.
//! 2. **One error type**, [`IsleError`], on this layer and on the
//! actors, with one payload for a Lua error: [`IsleError::Lua`]
//! carries a [`LuaFailure`] (kind, message as Lua prints it,
//! traceback, and with the `serde` feature the raised value as
//! JSON), built on the VM thread from the raised value, the same
//! for `run` and for every actor request. A cancel is
//! [`IsleError::Cancelled`], recognised by value: the cancel error
//! is `mlua::Error::external(`[`Cancelled`]`)`, found by downcast,
//! never by message.
//! 3. **The layer owns the VM's debug hook.** Register callbacks with
//! [`Vm::add_hook`], never with `Lua::set_hook` /
//! `Lua::set_global_hook`, which replace the hook and stop
//! cancellation (see [Hooks](#hooks)).
//! 4. **One [`Config`] per VM**, read and written through [`Vm`]
//! ([`Vm::config`], [`Vm::set_config`]; a second [`Vm::attach`]
//! replaces it).
//! 5. **Cancellation is a token the host creates** and passes to
//! `run`; `run` spawns nothing and returns no handle. Ctrl-C, a
//! timeout or a hook callback cancel that [`CancelToken`].
//!
//! 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,
//!
//! 1. 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](#channels-timers-and-select)),
//! 2. calls the callbacks registered with [`Vm::add_hook`], each at its
//! own [`HookTriggers`],
//! 3. 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](#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:reject(reason)`, `req:replied()`, `local req <close> = ...` | A `Request` received from a host channel. See [Host channels and requests](#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](Config::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:
//!
//! ```lua
//! 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)
//! end
//! ```
//!
//! The 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`**:
//!
//! ```lua
//! 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 (`nil` included); tables are
//! shared, not copied.
//! - After `close`: `send` / `try_send` raise; `recv` returns what is
//! left, in order, then `nil, 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 (a
//! `try_send` loop) 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:
//! `send` returns once a receiver has taken the value. Receivers take
//! offers in the order they were posted (FIFO among senders).
//! - `try_send` succeeds only when a receiver is waiting right now (a
//! `recv`, 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_recv` takes the first offer.
//! - `len()` and `cap()` are `0`. 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 in `len()`, 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 with `sent = false`); waiting receivers get `nil, false`.
//! - With `default`, a send case on a rendezvous channel is ready on
//! the first check when a receiver is waiting (a `recv`, or another
//! select's receive case): its value goes to the first such receiver,
//! as with `try_send`, and the case is chosen with `sent = true`.
//! With no receiver waiting, `default` runs 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 by `ms`).
//! - 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.ticker`
//! raises.
//!
//! **Send cases** (`ch:on_send(v, f)` / `ch:arm_send(v)`, local channels
//! and channels to the host)
//!
//! - Ready when `v` can 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, err` with the raw error
//! value, or `false, 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 = true` checks the cases in the given
//! order.
//! - `default`: if no case is ready on the first check, `select` runs
//! `default` (`select_raw` returns `0`) 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 `default` raises.
//! - A handler runs as Lua code inside the select and may await (and
//! select again); an error it raises is re-raised by `select` with
//! its raw value. While it runs, the other cases are not watched:
//! move long work into `task.spawn`. [`Config::preempt_every`] does
//! 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 cancelled `send` sent nothing). The wait is
//! wrapped in `cancellable`, which checks the token first, so a poll
//! that returns the cancel never also polled the cases.
//! - `recv` and `select_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 rendezvous `send` whose 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. `select` takes 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
//! `cancellable` wait returns the cancel), so a value `recv` or
//! `select_raw` took reaches the caller, and a `send` that 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 not
//! `cancellable`, 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 `Request`s carries values that Lua answers:
//!
//! ```text
//! 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??;
//! ```
//!
//! ```lua
//! 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 = 0` is an error: host
//! channels have no rendezvous form). `ch:cap()` is `cap`; `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` / `cap` and the same `select` contract. `send` / `try_send`
//! raise ("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 `Sender` is dropped (receivers get the queued
//! values first, then `nil, false`), or when Lua calls `close`: 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_closed` reports
//! both.
//! - Ordering between several `Sender`s is the order in which their
//! sends complete.
//! - `Sender::send` waits while the channel is full;
//! `Sender::try_send` returns `TrySendError::Full`. There is no
//! `send_timeout`: wrap `send` (or `request`) in
//! `tokio::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 `select` chooses another case or the receiver is
//! cancelled. (A tokio `Receiver` wakes only the task that polled it
//! last; the channel polls it with a waker that wakes every waiting
//! receiver.)
//!
//! **Request**
//!
//! - A `Request<Req, Resp, E = String>` carries a `Req` and a one-shot
//! answer: a `Resp` or a rejection reason `E`. `Sender::request`
//! sends it and waits for the answer: `RequestError::Closed` (with
//! the `Req`) if the channel is closed, `RequestError::Rejected` (with
//! the reason) if Lua rejected it, `RequestError::NoReply` if the
//! request is closed or collected without an answer (or the `Req`
//! failed to convert to a Lua value).
//! - On the Lua side it is a userdata: `req.value` is the `Req`
//! (converted with `IntoLua` when Lua received it); `req:reply(v)`
//! converts `v` with `Resp: FromLua` and returns `true`, or `false`
//! when the requester stopped waiting (its future was dropped, e.g. by
//! a timeout; not an error). A second `reply` raises, and so does a
//! `reply` after the request was closed. A conversion error raises
//! and leaves the request unanswered: it can be answered again.
//! - `req:reject(reason)` answers with a rejection: the requester gets
//! `RequestError::Rejected(reason)`, `reason` converted with
//! `E: FromLua` (`String` by default). It returns as `reply` does
//! (`false` when the requester stopped waiting). A conversion error
//! raises and leaves the request unanswered; a `reply` or `reject`
//! after the request was answered (replied or rejected) or closed
//! raises.
//! - `req:replied()` is whether a `reply` or `reject` succeeded.
//! - Closing an unanswered request (`local req <close> = ...`, at scope
//! exit or on an error) answers `NoReply` at once. A request that is
//! neither answered nor closed is reported `NoReply` only when Lua
//! collects it, so a requester should use a timeout, and Lua code that
//! may fail between receiving and answering 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
//! answers 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:
//!
//! ```text
//! 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 received
//! ```
//!
//! ```lua
//! reports: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 None
//! ```
//!
//! Call `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 = 0` is an error). One
//! host receiver; any number of Lua senders (tasks, selects).
//! `ch:cap()` is `cap`; `ch:len()` is the number of values queued for
//! the host (`0` once 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 to `T` (`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 chosen
//! `on_send` case) and is not queued; its room is given back.
//! - `send` waits while the channel is full; `try_send` returns `false`
//! when full. Both raise "channel is closed" when the channel is
//! closed: by `rx.close()`, by dropping `rx`, or by Lua's `close`.
//! 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. With
//! `default`, it is ready only when there is room at the first check
//! (`try_reserve`).
//! - Lua's `close`: the host receives the values already queued, then
//! `recv` returns `None` (`try_recv` `Closed`). 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_recv` raise ("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).
//!
//! ```text
//! let bg = lua.create_function(|_, ()| {
//! let scope = current_scope().expect("inside a coroutine request");
//! scope.spawn_local(async move { /* host work */ }).detach();
//! Ok(())
//! })?;
//! ```
use cratehub;
use Debug;
use ;
use RefCell;
use fmt;
use Duration;
pub use crate;
pub use crate;
pub use crate;
pub use crate;
/// Settings of a VM. One per VM, read and written through [`Vm`]
/// ([`Vm::attach`], [`Vm::config`], [`Vm::set_config`]).
/// Handle of a callback registered with [`Vm::add_hook`].
u64);
/// Marks a VM as attached; holds the per-VM state that is not in the
/// hook hub.
/// The registry keys of the `task` table and of the library's channel
/// constructor (used by [`channel`]).
/// The in-thread handle of a Lua VM run by this crate.
///
/// A `Vm` is a clone of the [`Lua`] handle; its state lives in the VM,
/// so every `Vm` of the same VM (from [`Vm::attach`] or [`Vm::of`]) sees
/// the same state. It holds the VM strongly: do not store it in
/// something the VM owns (a Lua function's captured state, app data),
/// or the VM is never freed.
/// Attach an actor's VM after its init closure ran.
///
/// With `config`, it replaces whatever the init closure configured;
/// without, the VM keeps the init closure's settings (the default if it
/// set none). The hook is (re-)installed either way, so a hook the init
/// closure set with `Lua::set_hook` is replaced, as before.
pub
/// Make sure the VM is attached and its hook is in place, before a
/// request runs. Re-installs the hook if `Lua::set_hook` replaced it;
/// keeps the stored config.
pub
/// The [`Vm`] of `lua`, attaching it with its stored config (the
/// default if none was set) when it is not attached yet.
pub