Skip to main content

moonseed/api/
execution.rs

1//! Host execution shares ordinary call windows and VM continuation frames.
2use super::*;
3use crate::api::{
4    ApiError, CallOutcome, Completion, Error, FromLuaMulti, Function, IntoLuaMulti, LuaError,
5    MultiValue, NativeContext, NativeReturn, Result as ApiResult, Resume, ResumeOutcome,
6    Value as Owned, WaitInfo,
7};
8use std::rc::Rc;
9
10impl Runtime {
11    pub(crate) fn take_owned_buffer(&mut self) -> Vec<Owned> {
12        let index = (0..self.native_owned_buffers.len())
13            .max_by_key(|&i| self.native_owned_buffers[i].capacity())
14            .unwrap();
15        std::mem::take(&mut self.native_owned_buffers[index])
16    }
17
18    pub(crate) fn recycle_owned_buffer(&mut self, mut values: Vec<Owned>) {
19        values.clear(); // Drop roots before caching host storage.
20        let index = (0..self.native_owned_buffers.len())
21            .min_by_key(|&i| self.native_owned_buffers[i].capacity())
22            .unwrap();
23        if values.capacity() > self.native_owned_buffers[index].capacity() {
24            self.native_owned_buffers[index] = values;
25        }
26    }
27
28    /// Make a registered host native closure. Captures are snapshot state;
29    /// builtin closure shapes are reserved for the VM.
30    ///
31    /// # Errors
32    ///
33    /// Returns `ApiError::UnknownSymbol` for absent or reserved symbols,
34    /// `ApiError::InvalidCallState` for more than 255 captures, conversion or
35    /// wrong-runtime errors for captures, and resource/VM errors for allocation.
36    ///
37    /// # Panics
38    ///
39    /// Propagates panics from user-supplied conversion implementations.
40    pub fn make_closure(
41        &mut self,
42        symbol: &str,
43        captures: impl IntoLuaMulti,
44    ) -> ApiResult<Function> {
45        let slot = self
46            .registry
47            .native_slot(symbol)
48            .ok_or(ApiError::UnknownSymbol)?;
49        if self
50            .registry
51            .native(slot)
52            .is_none_or(|entry| entry.builtin.is_some())
53        {
54            return Err(ApiError::UnknownSymbol.into());
55        }
56        let captures = captures.into_lua_multi(self)?;
57        if captures.len() > 255 {
58            return Err(ApiError::InvalidCallState.into());
59        }
60        let values = captures
61            .iter()
62            .map(|v| v.raw(self))
63            .collect::<ApiResult<Vec<_>>>()?;
64        let Value::Native(native) = self.native_value(symbol)? else {
65            return Err(VmError::Corrupt.into());
66        };
67        if !self.in_callback {
68            self.make_room(1, crate::heap::native_closure_cost(values.len(), 0));
69        }
70        let handle = self
71            .alloc_native_closure(native, values, Vec::new())
72            .map_err(|e| self.api_error(e))?;
73        let Owned::Function(function) = self.api_owned(Value::NativeClosure(handle))? else {
74            return Err(VmError::Corrupt.into());
75        };
76        Ok(function)
77    }
78
79    /// Create a rooted full userdata holding a registered Rust payload.
80    /// With automatic collection on, host allocations collect before
81    /// refusing for lack of room. Callback borrows defer collection.
82    ///
83    /// # Errors
84    ///
85    /// Returns `ApiError::Unregistered` if the host type was not registered,
86    /// or a resource/VM error if the payload and user-value slots cannot be allocated.
87    ///
88    /// # Panics
89    ///
90    /// Propagates a panic from the host payload's `logical_size` implementation.
91    pub fn create_host_userdata<T: crate::HostUserdata>(
92        &mut self,
93        value: T,
94        user_values: usize,
95    ) -> ApiResult<crate::AnyUserData> {
96        if !self.registry.has_userdata_type::<T>() {
97            return Err(ApiError::Unregistered.into());
98        }
99        let size = value.logical_size();
100        self.settle_atomic();
101        if !self.in_callback {
102            self.make_room(1, crate::heap::userdata_cost(user_values, size));
103        }
104        let handle = self
105            .heap
106            .alloc_userdata(self.max_objects, user_values, size, || {
107                crate::userdata::Payload::Host {
108                    symbol: T::SYMBOL,
109                    value: Box::new(value),
110                }
111            })
112            .map_err(|e| self.api_error(VmError::from(e)))?;
113        let Owned::UserData(value) = self.api_owned(Value::Userdata(handle))? else {
114            return Err(VmError::Corrupt.into());
115        };
116        Ok(value)
117    }
118
119    pub(crate) fn api_value_metatable(&mut self, value: &Owned) -> ApiResult<Option<crate::Table>> {
120        let raw = value.raw(self)?;
121        let Some(meta) = self.heap.metatable_of(raw) else {
122            return Ok(None);
123        };
124        match self.api_owned(Value::Table(meta))? {
125            Owned::Table(table) => Ok(Some(table)),
126            _ => Err(VmError::Corrupt.into()),
127        }
128    }
129
130    pub(crate) fn api_value_set_metatable(
131        &mut self,
132        value: &Owned,
133        meta: Option<&crate::Table>,
134    ) -> ApiResult<()> {
135        let raw = value.raw(self)?;
136        let meta = meta
137            .map(|table| Owned::Table(table.clone()).raw(self))
138            .transpose()?;
139        let meta = match meta {
140            Some(Value::Table(table)) => Some(table),
141            None => None,
142            _ => return Err(ApiError::WrongType.into()),
143        };
144        if self.heap.set_metatable(raw, meta) {
145            Ok(())
146        } else {
147            Err(ApiError::WrongType.into())
148        }
149    }
150
151    pub(crate) fn api_captures(&self, callee: Value) -> &[Value] {
152        match callee {
153            Value::NativeClosure(handle) => self
154                .heap
155                .native_closures
156                .get(handle)
157                .map_or(&[], |c| c.values.as_slice()),
158            _ => &[],
159        }
160    }
161
162    pub(crate) fn api_set_capture(
163        &mut self,
164        callee: Value,
165        index: usize,
166        value: &Owned,
167    ) -> ApiResult<()> {
168        let raw = value.raw(self)?;
169        let Value::NativeClosure(handle) = callee else {
170            return Err(ApiError::InvalidCallState.into());
171        };
172        let slot = self
173            .heap
174            .native_closures
175            .get_mut(handle)
176            .and_then(|c| c.values.get_mut(index))
177            .ok_or(ApiError::InvalidCallState)?;
178        *slot = raw;
179        Ok(())
180    }
181
182    /// Inspect a pending host operation. Returned object values are rooted
183    /// in this runtime. Legacy integer waits have no operation payload.
184    pub fn wait(&self, key: WaitKey) -> Option<WaitInfo> {
185        let thread = *self.wait_index.get(&key.raw())?;
186        let request = self
187            .heap
188            .threads
189            .get(thread)?
190            .frames
191            .last()?
192            .wait_request()?;
193        let payload = request
194            .payload
195            .iter()
196            .map(|v| Owned::wrap(*v, &self.heap, self.owner, self.heap.api_roots.as_ref()))
197            .collect::<ApiResult<Vec<_>>>()
198            .ok()?;
199        Some(WaitInfo {
200            operation: request.operation.clone(),
201            payload: MultiValue(payload),
202        })
203    }
204
205    /// Complete a pending wait once, checking every value's ownership.
206    /// Unknown keys are `NotWaiting`; every completed VM-issued key remains
207    /// `AlreadyCompleted`, including after another wait and after restore.
208    ///
209    /// # Errors
210    ///
211    /// Returns `ApiError::NotWaiting` for unknown keys, `AlreadyCompleted` for
212    /// completed keys, `InvalidCallState` for capability-owned waits, and ownership
213    /// errors for values from another runtime.
214    pub fn complete(&mut self, key: WaitKey, completion: Completion) -> ApiResult<()> {
215        if self.completed_waits.contains(&key.raw()) || self.last_completed_wait == Some(key.raw())
216        {
217            return Err(ApiError::AlreadyCompleted.into());
218        }
219        if !self.wait_index.contains_key(&key.raw()) {
220            return Err(ApiError::NotWaiting.into());
221        }
222        if let Some(thread) = self.wait_index.get(&key.raw())
223            && self
224                .heap
225                .threads
226                .get(*thread)
227                .and_then(|t| t.frames.last())
228                .is_some_and(|f| matches!(f.pending(), Some(Pending::Capability { .. })))
229        {
230            return Err(ApiError::InvalidCallState.into());
231        }
232        let (values, error) = match completion {
233            Completion::Return(values) => (values, false),
234            Completion::Error(value) => (vec![value], true),
235        };
236        let raw = values
237            .iter()
238            .map(|v| v.raw(self))
239            .collect::<ApiResult<Vec<_>>>()?;
240        self.finish_wait_raw(key, &raw, error)
241            .map_err(|e| match e {
242                WaitError::AlreadyCompleted => ApiError::AlreadyCompleted,
243                _ => ApiError::NotWaiting,
244            })?;
245        Ok(())
246    }
247
248    pub(super) fn index_wait(
249        &mut self,
250        key: u64,
251        thread: Handle<ThreadObj>,
252    ) -> Result<(), VmError> {
253        if self.wait_index.contains_key(&key) {
254            return Err(VmError::Api(ApiError::InvalidCallState));
255        }
256        let vm_allocated = self
257            .heap
258            .threads
259            .get(thread)
260            .and_then(|object| object.frames.last())
261            .is_some_and(|frame| frame.wait_request().is_some());
262        let root = self.api_owned(Value::Thread(thread)).map_err(api_vm)?;
263        self.wait_index.insert(key, thread);
264        self.wait_roots.insert(key, (root, vm_allocated));
265        Ok(())
266    }
267
268    pub(super) fn wait_finished(&mut self, key: WaitKey) {
269        self.wait_index.remove(&key.raw());
270        if self
271            .wait_roots
272            .remove(&key.raw())
273            .is_some_and(|(_, vm_allocated)| vm_allocated)
274        {
275            self.completed_waits.insert(key.raw());
276        }
277        self.last_completed_wait = Some(key.raw());
278    }
279
280    pub(super) fn clear_wait_request(&mut self, thread: Handle<ThreadObj>) {
281        if let Some(object) = self.heap.threads.get_mut(thread)
282            && let Some(wait) = object
283                .frames
284                .last_mut()
285                .and_then(|f| f.take_wait_request(&mut self.cold_spare))
286        {
287            let bytes = wait.operation.len() as u64 + cost::STACK_SLOT * wait.payload.len() as u64;
288            object.charged_held = object.charged_held.saturating_sub(bytes);
289            self.heap.give_back(bytes);
290        }
291    }
292
293    pub(crate) fn api_argument_error(&mut self, _callee: Value, error: Error) -> Error {
294        let Error::Api(ApiError::Conversion(error)) = error else {
295            return error;
296        };
297        let Some(active) = self.heap.active else {
298            return VmError::Corrupt.into();
299        };
300        let Ok((func, _, passed, _)) = self.call_site(active) else {
301            return VmError::Corrupt.into();
302        };
303        let ctx = library::Ctx {
304            active,
305            func,
306            passed,
307            framed: false,
308        };
309        let (name, method) = self.argument_name(&ctx);
310        let mut text = self.where_prefix(active);
311        text.extend(library::arg_error_text(
312            &name,
313            method,
314            error.position.unwrap_or(1).saturating_sub(1) as u32,
315            format!(
316                "{} expected, got {}",
317                lua_expected(error.expected),
318                crate::api::error::type_name(error.actual)
319            )
320            .as_bytes(),
321        ));
322        match self
323            .create_string(text)
324            .and_then(|value| LuaError::new(Owned::String(value), LuaFault::Argument, self))
325        {
326            Ok(error) => Error::Lua(error),
327            Err(error) => error,
328        }
329    }
330
331    pub(crate) fn api_bad_argument(
332        &mut self,
333        index: usize,
334        detail: &[u8],
335    ) -> crate::Result<LuaError> {
336        let active = self.heap.active.ok_or(VmError::Corrupt)?;
337        let (func, _, passed, _) = self.call_site(active)?;
338        let ctx = library::Ctx {
339            active,
340            func,
341            passed,
342            framed: false,
343        };
344        let (name, method) = self.argument_name(&ctx);
345        let mut text = self.where_prefix(active);
346        text.extend(library::arg_error_text(&name, method, index as u32, detail));
347        let value = self.create_string(text)?;
348        LuaError::new(Owned::String(value), LuaFault::Argument, self)
349    }
350
351    /// Catch only host code; keep Poison's original unwind and honor an
352    /// accounting failure that revoked recovery while the callback ran.
353    pub(crate) fn catch_native_panic<T>(
354        &mut self,
355        invoke: impl FnOnce(&mut Self) -> T,
356    ) -> Result<T, Box<dyn std::any::Any + Send>> {
357        if self.native_panic_policy == crate::NativePanicPolicy::Poison {
358            return Ok(invoke(self));
359        }
360        match std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| invoke(self))) {
361            Err(payload) if self.native_panic_policy == crate::NativePanicPolicy::Poison => {
362                std::panic::resume_unwind(payload)
363            }
364            result => result,
365        }
366    }
367
368    pub(crate) fn native_panic_message(payload: &(dyn std::any::Any + Send)) -> Vec<u8> {
369        let detail = payload
370            .downcast_ref::<&str>()
371            .copied()
372            .or_else(|| payload.downcast_ref::<String>().map(String::as_str))
373            .unwrap_or("non-string payload");
374        format!("native panic: {detail}").into_bytes()
375    }
376
377    /// Leave the caller's ordinary callback cleanup and Lua delivery in place.
378    pub(super) fn invoke_native<T>(
379        &mut self,
380        invoke: impl FnOnce(&mut Self) -> ApiResult<T>,
381    ) -> ApiResult<T> {
382        match self.catch_native_panic(invoke) {
383            Ok(result) => result,
384            Err(payload) => {
385                let value = self.create_string(Self::native_panic_message(payload.as_ref()))?;
386                Err(LuaError::new(Owned::String(value), LuaFault::Error, self)?.into())
387            }
388        }
389    }
390
391    pub(super) fn callback_error(&mut self, error: Error) -> Result<Poll, VmError> {
392        match error {
393            Error::Lua(error) => {
394                let raw = error.value.raw(self).map_err(api_vm)?;
395                let active = self.heap.active.ok_or(VmError::Corrupt)?;
396                self.throw_on(active, error.class, raw);
397                Ok(Poll::Continue)
398            }
399            other => Err(api_vm(other)),
400        }
401    }
402
403    #[allow(clippy::too_many_arguments)]
404    #[inline]
405    pub(super) fn run_typed(
406        &mut self,
407        active: Handle<ThreadObj>,
408        callee: Value,
409        func: u32,
410        wants: u8,
411        passed: u32,
412        callback: Rc<crate::api::native::TypedCallback>,
413        effect: Option<EffectId>,
414        journal: &mut Journal,
415    ) -> Result<Poll, VmError> {
416        let mut args = std::mem::take(&mut self.native_args);
417        args.clear();
418        let thread = self.heap.threads.get(active).ok_or(VmError::Corrupt)?;
419        args.extend((0..passed).map(|i| {
420            thread
421                .stack
422                .get((func + 1 + i) as usize)
423                .copied()
424                .unwrap_or(Value::Nil)
425        }));
426        self.api_roots();
427        self.native_results.clear();
428        self.in_callback = true;
429        let result = self.invoke_native(|runtime| {
430            callback(&mut NativeContext {
431                runtime,
432                args: &args,
433                callee,
434                effect,
435                journal: effect.map(|_| &mut *journal),
436                resume: None,
437            })
438        });
439        self.in_callback = false;
440        args.clear();
441        self.native_args = args;
442        if let Err(error) = result {
443            self.native_results.clear();
444            return self.callback_error(error);
445        }
446        let mut raw = std::mem::take(&mut self.native_results);
447        let result = self.native_returned(active, func, wants, passed, &raw);
448        raw.clear();
449        self.native_results = raw;
450        result
451    }
452
453    #[allow(clippy::too_many_arguments)]
454    pub(super) fn run_callback(
455        &mut self,
456        active: Handle<ThreadObj>,
457        callee: Value,
458        func: u32,
459        wants: u8,
460        passed: u32,
461        callback: Rc<crate::api::native::Callback>,
462        effect: Option<EffectId>,
463        resume: Option<Resume>,
464        journal: &mut Journal,
465    ) -> Result<Poll, VmError> {
466        let Value::Native(symbol) = self.callable(callee) else {
467            return Err(VmError::Corrupt);
468        };
469        let mut args = std::mem::take(&mut self.native_args);
470        args.clear();
471        let thread = self.heap.threads.get(active).ok_or(VmError::Corrupt)?;
472        args.extend((0..passed).map(|i| {
473            thread
474                .stack
475                .get((func + 1 + i) as usize)
476                .copied()
477                .unwrap_or(Value::Nil)
478        }));
479        // Root support is initialized once, rather than once per argument.
480        self.api_roots();
481        let resuming = resume.is_some();
482        self.in_callback = true;
483        let outcome = self.invoke_native(|runtime| {
484            callback(&mut NativeContext {
485                runtime,
486                args: &args,
487                callee,
488                effect,
489                journal: effect.map(|_| &mut *journal),
490                resume: resume.as_ref(),
491            })
492        });
493        self.in_callback = false;
494        if let Some(resume) = resume {
495            self.recycle_owned_buffer(resume.kept.into_vec());
496            if let ResumeOutcome::Returned(values) = resume.outcome {
497                self.recycle_owned_buffer(values.into_vec());
498            }
499        }
500        args.clear();
501        self.native_args = args;
502        if resuming {
503            let object = self.heap.threads.get_mut(active).ok_or(VmError::Corrupt)?;
504            let mut frame = object.frames.pop().ok_or(VmError::Corrupt)?;
505            frame.recycle_cold(&mut self.cold_spare);
506            object.stack.truncate((func + 1 + passed) as usize);
507            object.top = func + 1 + passed;
508        }
509        let outcome = match outcome {
510            Ok(outcome) => outcome,
511            Err(error) => return self.callback_error(error),
512        };
513        let no_yield = matches!(&outcome, NativeReturn::CallLuaNoYield { .. });
514        match outcome {
515            NativeReturn::Return(values) => {
516                let mut raw = std::mem::take(&mut self.native_results);
517                raw.clear();
518                for value in &values.0 {
519                    raw.push(value.raw(self).map_err(api_vm)?);
520                }
521                let result = self.native_returned(active, func, wants, passed, &raw);
522                raw.clear();
523                self.native_results = raw;
524                self.recycle_owned_buffer(values.into_vec());
525                result
526            }
527            NativeReturn::Error(error) => {
528                let error = error.raw(self).map_err(api_vm)?;
529                self.throw_on(active, LuaFault::Error, error);
530                Ok(Poll::Continue)
531            }
532            NativeReturn::Wait(request) => {
533                if request.operation.len() > 4096
534                    || request.payload.len() as u64 > u64::from(self.max_stack_slots)
535                {
536                    return Err(VmError::Api(ApiError::InvalidCallState));
537                }
538                let payload = request
539                    .payload
540                    .iter()
541                    .map(|v| v.raw(self))
542                    .collect::<ApiResult<Vec<_>>>()
543                    .map_err(api_vm)?;
544                let bytes =
545                    request.operation.len() as u64 + cost::STACK_SLOT * payload.len() as u64;
546                self.ensure_room(bytes)?;
547                let key = loop {
548                    let sequence = self.next_sequence;
549                    if sequence >= (1 << 63) {
550                        return Err(VmError::Api(ApiError::InvalidCallState));
551                    }
552                    self.next_sequence += 1;
553                    let key = sequence | (1 << 63);
554                    if !self.wait_index.contains_key(&key) && !self.completed_waits.contains(&key) {
555                        break key;
556                    }
557                };
558                let object = self.heap.threads.get_mut(active).ok_or(VmError::Corrupt)?;
559                let frame = object.frames.last_mut().ok_or(VmError::Corrupt)?;
560                let sequence = effect.map(|id| id.sequence);
561                if let Some(meta) = frame.meta_mut() {
562                    meta.phase = MetaPhase::NativeWaiting {
563                        sequence,
564                        wait_key: key,
565                    };
566                } else {
567                    frame.set_pending(
568                        Some(Pending::NativeWaiting {
569                            sequence,
570                            wait_key: key,
571                        }),
572                        &mut self.cold_spare,
573                    );
574                }
575                frame.set_wait_request(
576                    Some(crate::heap::HostWait {
577                        operation: request.operation,
578                        payload,
579                    }),
580                    &mut self.cold_spare,
581                );
582                object.charged_held += bytes;
583                self.heap.gc.charge(bytes);
584                count!("host_waits");
585                object.status = Status::Waiting;
586                self.index_wait(key, active)?;
587                self.last_completed_wait = None;
588                Ok(Poll::Continue)
589            }
590            NativeReturn::CallLua {
591                function,
592                args,
593                tag,
594                keep,
595            }
596            | NativeReturn::CallLuaNoYield {
597                function,
598                args,
599                tag,
600                keep,
601            } => {
602                let function = function.raw(self).map_err(api_vm)?;
603                // Validate before mutating the frame. Rooted owned values stay
604                // alive until every raw value has reached the Lua stack.
605                for value in args.iter().chain(keep.iter()) {
606                    value.check(self).map_err(api_vm)?;
607                }
608                let kept = u32::try_from(keep.len()).map_err(|_| VmError::StackLimit)?;
609                let call_slot = func
610                    .checked_add(1)
611                    .and_then(|n| n.checked_add(passed))
612                    .and_then(|n| n.checked_add(kept))
613                    .ok_or(VmError::StackLimit)?;
614                if let Some(fault) = self.depth_fault(active)? {
615                    return Ok(self.fault(fault));
616                }
617                let nargs = u32::try_from(args.len()).map_err(|_| VmError::StackLimit)?;
618                let end = call_slot
619                    .checked_add(1)
620                    .and_then(|n| n.checked_add(nargs))
621                    .ok_or(VmError::StackLimit)?;
622                if let Some(fault) = self.slot_fault(active, end)? {
623                    return Ok(self.fault(fault));
624                }
625                let object = self.heap.threads.get_mut(active).ok_or(VmError::Corrupt)?;
626                let caller = object.frames.last_mut().ok_or(VmError::Corrupt)?;
627                caller.set_pending(None, &mut self.cold_spare);
628                if let Some(meta) = caller.meta_mut() {
629                    meta.phase = MetaPhase::Running;
630                }
631                let advance_caller = caller.boundary().is_none() && caller.meta().is_none();
632                let closure = caller.closure;
633                count!("frame_pushes");
634                object.frames.push(Frame {
635                    closure,
636                    pc: 0,
637                    base: func + 1,
638                    limit: func + 1,
639                    nresults: wants,
640                    vararg_len: 0,
641                    flags: 0,
642                    cold: FrameCold::with_boundary(
643                        Boundary::Native {
644                            func,
645                            passed,
646                            advance_caller,
647                            symbol,
648                            tag,
649                            kept,
650                            sequence: effect.map(|id| id.sequence),
651                            error: None,
652                            resuming: false,
653                            no_yield,
654                        },
655                        &mut self.cold_spare,
656                    ),
657                });
658                for (i, value) in keep.iter().enumerate() {
659                    self.write_abs(
660                        active,
661                        func + 1 + passed + i as u32,
662                        value.raw(self).map_err(api_vm)?,
663                    )?;
664                }
665                self.write_abs(active, call_slot, function)?;
666                for (i, value) in args.iter().enumerate() {
667                    self.write_abs(
668                        active,
669                        call_slot + 1 + i as u32,
670                        value.raw(self).map_err(api_vm)?,
671                    )?;
672                }
673                self.recycle_owned_buffer(args.into_vec());
674                self.recycle_owned_buffer(keep.into_vec());
675                let (function, nargs) = match self.resolve_callable(active, call_slot, nargs)? {
676                    Ok(call) => call,
677                    Err(fault) => return Ok(self.fault(fault)),
678                };
679                self.heap
680                    .threads
681                    .get_mut(active)
682                    .ok_or(VmError::Corrupt)?
683                    .top = call_slot + 1 + nargs;
684                match self.callable(function) {
685                    Value::Closure(closure) => {
686                        self.push_lua_frame(closure, call_slot, nargs, COUNT_OPEN, false)
687                    }
688                    Value::Native(_) => self.defer_call(active),
689                    _ => Err(VmError::Corrupt),
690                }
691            }
692        }
693    }
694
695    pub(super) fn finish_native(
696        &mut self,
697        active: Handle<ThreadObj>,
698        effect: Option<EffectId>,
699        journal: &mut Journal,
700    ) -> Result<Poll, VmError> {
701        let object = self.heap.threads.get(active).ok_or(VmError::Corrupt)?;
702        let frame = object.frames.last().ok_or(VmError::Corrupt)?;
703        let Some(Boundary::Native {
704            func,
705            passed,
706            symbol,
707            tag,
708            kept,
709            error,
710            resuming,
711            sequence,
712            ..
713        }) = frame.boundary()
714        else {
715            return Err(VmError::Corrupt);
716        };
717        let (func, passed, symbol, tag, kept, error, resuming, sequence, wants) = (
718            *func,
719            *passed,
720            *symbol,
721            *tag,
722            *kept,
723            *error,
724            *resuming,
725            *sequence,
726            frame.nresults,
727        );
728        let callee = object
729            .stack
730            .get(func as usize)
731            .copied()
732            .ok_or(VmError::Corrupt)?;
733        let slot = *self
734            .native_slots
735            .get(symbol as usize)
736            .ok_or(VmError::Corrupt)?;
737        let entry = self.registry.native(slot).ok_or(VmError::Corrupt)?;
738        if entry.policy == NativePolicy::External && !resuming {
739            let sequence = sequence.ok_or(VmError::Corrupt)?;
740            let frame = self
741                .heap
742                .threads
743                .get_mut(active)
744                .and_then(|t| t.frames.last_mut())
745                .ok_or(VmError::Corrupt)?;
746            frame.set_pending(
747                Some(Pending::NativePrepared { sequence }),
748                &mut self.cold_spare,
749            );
750            if let Some(Boundary::Native { resuming, .. }) = frame.boundary_mut() {
751                *resuming = true;
752            }
753            return Ok(Poll::Continue);
754        }
755        count!("host_continuations");
756        count!("lua_to_host_calls");
757        let callback = entry.callback.clone().ok_or(VmError::Corrupt)?;
758        let call = func + 1 + passed + kept;
759        let mut kept_values = self.take_owned_buffer();
760        for index in func + 1 + passed..call {
761            let raw = self.heap.threads.get(active).ok_or(VmError::Corrupt)?.stack[index as usize];
762            kept_values.push(self.api_owned(raw).map_err(api_vm)?);
763        }
764        let kept = MultiValue(kept_values);
765        let outcome = match error {
766            Some((class, raw)) => {
767                let value = self.api_owned(raw).map_err(api_vm)?;
768                ResumeOutcome::Errored(LuaError::new(value, class, self).map_err(api_vm)?)
769            }
770            None => {
771                let mut values = self.take_owned_buffer();
772                let object = self.heap.threads.get(active).ok_or(VmError::Corrupt)?;
773                let end = if object.top as usize <= object.stack.len() {
774                    object.top
775                } else {
776                    call
777                };
778                for index in call..end {
779                    let raw = self.heap.threads.get(active).ok_or(VmError::Corrupt)?.stack
780                        [index as usize];
781                    values.push(self.api_owned(raw).map_err(api_vm)?);
782                }
783                ResumeOutcome::Returned(MultiValue(values))
784            }
785        };
786        self.run_callback(
787            active,
788            callee,
789            func,
790            wants,
791            passed,
792            callback,
793            effect,
794            Some(Resume { tag, outcome, kept }),
795            journal,
796        )
797    }
798
799    fn idle_main(&self) -> ApiResult<()> {
800        if self.in_callback {
801            return Err(ApiError::Busy.into());
802        }
803        if self.callback_failed {
804            return Err(ApiError::InvalidCallState.into());
805        }
806        if self.trap.is_some() || self.is_closing() || self.heap.finalizers.exit.is_some() {
807            return Err(ApiError::InvalidCallState.into());
808        }
809        let entry = self.heap.entry.ok_or(VmError::Corrupt)?;
810        let thread = self.heap.threads.get(entry).ok_or(VmError::Corrupt)?;
811        if self.host_call
812            || !matches!(thread.status, Status::Completed | Status::Failed)
813            || thread.closing
814            || self.heap.finalizers.running
815        {
816            return Err(ApiError::Busy.into());
817        }
818        Ok(())
819    }
820
821    /// Install a call on the idle main thread. Drive with `run`, then
822    /// consume its exact results or Lua error through `finish_call`.
823    ///
824    /// # Errors
825    ///
826    /// Returns busy/invalid-state errors unless the main thread is idle,
827    /// wrong-runtime or conversion errors for the function/arguments, and
828    /// resource/VM errors when preparing the call.
829    ///
830    /// # Panics
831    ///
832    /// Propagates panics from user-supplied conversion implementations.
833    pub fn start_call(&mut self, function: &Function, args: impl IntoLuaMulti) -> ApiResult<()> {
834        #[cfg(feature = "counters")]
835        let _scope = self.counter_scope();
836        count!("host_to_lua_calls");
837        self.idle_main()?;
838        let function = Owned::Function(function.clone());
839        function.check(self)?;
840        let args = args.into_lua_multi(self)?;
841        let mut values = args.into_vec();
842        if values.capacity() == 0 {
843            values = self.take_owned_buffer();
844        }
845        values.insert(0, function);
846        self.start_main_ops(
847            &[
848                Op::Call {
849                    func: 0,
850                    nargs: COUNT_OPEN,
851                    nresults: COUNT_OPEN,
852                },
853                Op::Return {
854                    base: 0,
855                    count: COUNT_OPEN,
856                },
857            ],
858            1,
859            values,
860        )
861    }
862
863    fn start_main_ops(&mut self, ops: &[Op], registers: u8, values: Vec<Owned>) -> ApiResult<()> {
864        self.idle_main()?;
865        if values.len() as u64 > u64::from(self.max_stack_slots - self.max_stack_slots / 8) {
866            return Err(self.api_error(VmError::StackLimit));
867        }
868        for value in &values {
869            value.check(self)?;
870        }
871        self.settle_atomic();
872        let is_call = matches!(
873            ops,
874            [
875                Op::Call {
876                    func: 0,
877                    nargs: COUNT_OPEN,
878                    nresults: COUNT_OPEN
879                },
880                Op::Return {
881                    base: 0,
882                    count: COUNT_OPEN
883                }
884            ]
885        );
886        // This is a weak cache, not a root or canonical state. Reject objects
887        // already marked dead, even if the sweep has not freed their slots.
888        let cached = if is_call {
889            self.main_call_closure
890                .filter(|handle| {
891                    self.heap
892                        .closures
893                        .get(*handle)
894                        .is_some_and(|closure| self.heap.closures.find_id(closure.id).is_some())
895                })
896                .or_else(|| {
897                    // A restored heap may already contain the trampoline. Recover
898                    // it without adding snapshot fields or retaining extra roots.
899                    self.heap
900                        .closures
901                        .iter()
902                        .find_map(|(index, generation, closure)| {
903                            let proto = self.heap.protos.get(closure.proto)?;
904                            (closure.upvalues.is_empty()
905                                && proto.ops == ops
906                                && proto.max_reg == registers
907                                && proto.params == 0
908                                && !proto.vararg
909                                && proto.byte_consts.is_empty()
910                                && proto.captures.is_empty()
911                                && proto.children.is_empty()
912                                && proto.debug.is_none()
913                                && proto.source.is_none())
914                            .then_some(Handle::new(index, generation))
915                        })
916                })
917        } else {
918            None
919        };
920        let closure = if let Some(closure) = cached {
921            closure
922        } else {
923            let proto = ProtoSpec {
924                ops: ops.to_vec(),
925                byte_consts: Vec::new(),
926                captures: Vec::new(),
927                children: Vec::new(),
928                max_reg: registers,
929                params: 0,
930                vararg: false,
931                debug: None,
932            };
933            let globals = self.heap.globals.ok_or(VmError::Corrupt)?;
934            self.instantiate(&proto, Value::Table(globals), ChunkName::Unnamed)
935                .map_err(|error| self.api_error(error))?
936        };
937        if is_call {
938            self.main_call_closure = Some(closure);
939        }
940        self.load_main_closure(closure, u32::from(registers))?;
941        let active = self.heap.entry.ok_or(VmError::Corrupt)?;
942        if let Some(fault) = self.slot_fault(active, values.len() as u32)? {
943            let object = self.heap.threads.get_mut(active).ok_or(VmError::Corrupt)?;
944            object.frames.clear();
945            object.status = Status::Completed;
946            object.top = 0;
947            return Err(self.api_error(match fault {
948                LuaFault::Memory => VmError::MemoryLimit,
949                _ => VmError::StackLimit,
950            }));
951        }
952        for (i, value) in values.iter().enumerate() {
953            self.write_abs(active, i as u32, value.raw(self)?)?;
954        }
955        self.heap
956            .threads
957            .get_mut(active)
958            .ok_or(VmError::Corrupt)?
959            .top = values.len() as u32;
960        self.recycle_owned_buffer(values);
961        self.host_call = true;
962        Ok(())
963    }
964
965    /// Consume a completed host call. A Lua failure retains its original
966    /// error object; an unfinished call is `InvalidCallState`.
967    ///
968    /// # Errors
969    ///
970    /// Returns `ApiError::InvalidCallState` without a finished host call,
971    /// `Error::Lua` for an uncaught guest failure, conversion errors for `R`,
972    /// or a VM/root error if the retained call state is invalid.
973    ///
974    /// # Panics
975    ///
976    /// Propagates panics from user-supplied conversion implementations.
977    pub fn finish_call<R: FromLuaMulti>(&mut self) -> ApiResult<R> {
978        if self.callback_failed || !self.host_call || self.heap.finalizers.exit.is_some() {
979            return Err(ApiError::InvalidCallState.into());
980        }
981        let entry = self.heap.entry.ok_or(VmError::Corrupt)?;
982        let object = self.heap.threads.get(entry).ok_or(VmError::Corrupt)?;
983        match object.status {
984            Status::Completed => {
985                let len = object.host_results.len();
986                let mut values = self.take_owned_buffer();
987                for index in 0..len {
988                    let raw = self
989                        .heap
990                        .threads
991                        .get(entry)
992                        .ok_or(VmError::Corrupt)?
993                        .host_results[index];
994                    values.push(self.api_owned(raw)?);
995                }
996                let values = MultiValue(values);
997                self.host_call = false;
998                R::from_lua_multi(values, self)
999            }
1000            Status::Failed => {
1001                let (class, raw) = object.error.ok_or(VmError::Corrupt)?;
1002                let value = self.api_owned(raw)?;
1003                self.host_call = false;
1004                let mut error = LuaError::new(value, class, self)?;
1005                error.traceback = self.lua_traceback().map(<[u8]>::to_vec);
1006                Err(error.into())
1007            }
1008            _ => Err(ApiError::InvalidCallState.into()),
1009        }
1010    }
1011
1012    /// Start and drive a call for at most `fuel` execution units. This
1013    /// never blocks on a host operation and allocates no Lua thread.
1014    ///
1015    /// # Errors
1016    ///
1017    /// Returns the setup errors from [`Self::start_call`], the execution errors
1018    /// from [`Self::run`], or the Lua/conversion errors from [`Self::finish_call`].
1019    /// Termination becomes `Error::Vm`; a main-thread yield is invalid call state.
1020    /// Fuel pauses and host waits are successful incomplete outcomes, not errors.
1021    ///
1022    /// # Panics
1023    ///
1024    /// Propagates panics from host conversions and execution callbacks as
1025    /// described by [`Self::run`].
1026    pub fn call<R: FromLuaMulti>(
1027        &mut self,
1028        function: &Function,
1029        args: impl IntoLuaMulti,
1030        journal: &mut Journal,
1031        fuel: u64,
1032    ) -> ApiResult<CallOutcome<R>> {
1033        self.start_call(function, args)?;
1034        self.drive_call(journal, fuel)
1035    }
1036
1037    pub(crate) fn complete_host_call<R: FromLuaMulti>(
1038        &mut self,
1039        key: WaitKey,
1040        completion: Completion,
1041        journal: &mut Journal,
1042        fuel: u64,
1043    ) -> ApiResult<CallOutcome<R>> {
1044        // Validate the call and its currently active wait before consuming any
1045        // completion. In particular, a main-chunk wait is never a host call.
1046        if self.callback_failed || !self.host_call || self.heap.finalizers.exit.is_some() {
1047            return Err(ApiError::InvalidCallState.into());
1048        }
1049        let active = self.heap.active.ok_or(ApiError::InvalidCallState)?;
1050        if self.wait_index.get(&key.raw()) != Some(&active)
1051            || self
1052                .heap
1053                .threads
1054                .get(active)
1055                .is_none_or(|t| t.status != Status::Waiting)
1056            || self.wait_key(active)? != Some(key.raw())
1057        {
1058            return Err(ApiError::NotWaiting.into());
1059        }
1060        self.complete(key, completion)?;
1061        self.drive_call(journal, fuel)
1062    }
1063
1064    pub(crate) fn drive_call<R: FromLuaMulti>(
1065        &mut self,
1066        journal: &mut Journal,
1067        fuel: u64,
1068    ) -> ApiResult<CallOutcome<R>> {
1069        match self.run(fuel, journal).map_err(Error::from)? {
1070            StepOutcome::Completed | StepOutcome::LuaError(_) => {
1071                self.finish_call().map(CallOutcome::Done)
1072            }
1073            StepOutcome::ExitRequested { status, close } => {
1074                self.host_call = false;
1075                Ok(CallOutcome::ExitRequested { status, close })
1076            }
1077            StepOutcome::Waiting(key) => Ok(CallOutcome::Waiting(key)),
1078            StepOutcome::LuaYielded => Err(ApiError::InvalidCallState.into()),
1079            StepOutcome::Paused(_) => Ok(CallOutcome::OutOfFuel),
1080            StepOutcome::Terminated(reason) => Err(VmError::from(reason).into()),
1081        }
1082    }
1083
1084    pub(crate) fn api_table_get<R: FromLuaMulti>(
1085        &mut self,
1086        table: &crate::Table,
1087        key: Owned,
1088        journal: &mut Journal,
1089        fuel: u64,
1090    ) -> ApiResult<CallOutcome<R>> {
1091        self.start_main_ops(
1092            &[
1093                Op::Index {
1094                    dst: 0,
1095                    obj: 0,
1096                    key: 1,
1097                },
1098                Op::Return { base: 0, count: 1 },
1099            ],
1100            2,
1101            vec![Owned::Table(table.clone()), key],
1102        )?;
1103        self.drive_call(journal, fuel)
1104    }
1105    pub(crate) fn api_table_set(
1106        &mut self,
1107        table: &crate::Table,
1108        key: Owned,
1109        value: Owned,
1110        journal: &mut Journal,
1111        fuel: u64,
1112    ) -> ApiResult<CallOutcome<()>> {
1113        self.start_main_ops(
1114            &[
1115                Op::SetIndex {
1116                    obj: 0,
1117                    key: 1,
1118                    src: 2,
1119                },
1120                Op::Return { base: 0, count: 0 },
1121            ],
1122            3,
1123            vec![Owned::Table(table.clone()), key, value],
1124        )?;
1125        self.drive_call(journal, fuel)
1126    }
1127}
1128
1129pub(super) fn api_vm(error: Error) -> VmError {
1130    match error {
1131        Error::Api(error) => VmError::Api(error),
1132        Error::Vm(error) => error,
1133        Error::Lua(_) => VmError::Corrupt,
1134    }
1135}
1136fn lua_expected(expected: &str) -> &str {
1137    match expected {
1138        "i8" | "i16" | "i32" | "i64" | "u8" | "u16" | "u32" | "u64" | "isize" | "usize" => "number",
1139        "Function" => "function",
1140        "Table" => "table",
1141        "LuaString" => "string",
1142        "Thread" => "thread",
1143        "AnyUserData" => "userdata",
1144        other => other,
1145    }
1146}