Skip to main content

candela/
engine.rs

1//! Embedding / library API for candela.
2//!
3//! This is the persistent, in-process entry point a Rust host (such as Lumen)
4//! uses to embed candela the way it embeds `rhai`/`mlua`: register typed host
5//! functions, compile a script to a reusable [`Program`], and invoke
6//! script-defined functions by name with marshalled arguments, all while
7//! keeping interpreter state (registers + heap pools) alive between calls.
8//!
9//! ```
10//! let mut engine = candela::Engine::new();
11//! engine.register_host_fn("app", "rows", |id: &str| id.len() as i64);
12//! let mut program = engine.compile("host \"app\" { int rows(string); }\nfn count(id: string) { return app::rows(id); }\nfn main() {}", "main.cdl")?;
13//! let rows = program.call("count", &["board".into()])?;
14//! assert_eq!(rows, candela::Value::Int(5));
15//! # Ok::<(), candela::Diagnostic>(())
16//! ```
17//!
18//! Unlike the one-shot [`crate::candela_run`] C-ABI entry point (which compiles a
19//! script, runs `main`, and returns captured stdout), the [`Engine`]/[`Program`]
20//! pair keeps the compiler and VM state resident so the host can drive the
21//! script incrementally. Errors are returned as structured [`Diagnostic`]
22//! values (reusing the `structured-errors` funnel) instead of printing and
23//! aborting the process. The value-marshalling types it uses ([`Value`],
24//! [`HostType`], ...) live in the VM-only `candela-vm` crate.
25
26use crate::Cfg;
27use crate::compiler::CompileOutput;
28use crate::compiler::FileNamespaces;
29use crate::compiler::compiler_data::Dynamiclib;
30use crate::compiler::compiler_data::Function;
31use crate::compiler::compiler_data::IndirectRegisters;
32use crate::compiler::compiler_data::PROGRAM_LIMIT;
33use crate::compiler::compiler_data::ProgramLimit;
34use crate::compiler::compiler_data::State;
35use crate::compiler::compiler_data::StringSlots;
36use crate::compiler::compiler_data::Variable;
37use crate::compiler::compiler_data::program_too_large;
38use crate::compiler::expr::Expr;
39use crate::compiler::imports::DEFAULT_PACKAGE_ENTRY;
40use crate::compiler::imports::ImportResolver;
41use crate::compiler::type_system::Generics;
42use crate::compiler::use_immediates;
43use crate::macros::MacroEnv;
44use crate::macros::MacroError;
45#[cfg(not(target_arch = "wasm32"))]
46use crate::manifest::MANIFEST_NAME;
47#[cfg(not(target_arch = "wasm32"))]
48use crate::manifest::Manifest;
49use crate::trampoline::check_only;
50use crate::trampoline::compile_checked;
51use crate::trampoline::compile_trampoline;
52use crate::warnings::collect_warnings;
53use candela_vm::artifact::passed_by_reference;
54use candela_vm::attributes::Attribute;
55use candela_vm::attributes::AttributeTable;
56use candela_vm::data::Data;
57use candela_vm::data::NULL;
58use candela_vm::embed::HostDispatch;
59use candela_vm::embed::HostError;
60use candela_vm::embed::HostRegistry;
61use candela_vm::embed::HostType;
62use candela_vm::embed::IntoHostFn;
63use candela_vm::embed::Value;
64use candela_vm::embed::describe_value;
65use candela_vm::embed::holds_enum;
66use candela_vm::embed::marshal_args;
67use candela_vm::embed::struct_id;
68use candela_vm::embed::unmarshal_value;
69use candela_vm::embed::value_matches_type;
70use candela_vm::errors::Diagnostic;
71use candela_vm::errors::ErrorCtx;
72use candela_vm::errors::collect_diagnostic;
73use candela_vm::instr::Instr;
74use candela_vm::rt::DataType;
75use candela_vm::rt::DynamicLibFn;
76use candela_vm::rt::EnumType;
77use candela_vm::rt::GcStats;
78use candela_vm::rt::HostFnSig;
79use candela_vm::rt::InstrSrc;
80use candela_vm::rt::Pools;
81use candela_vm::rt::Source;
82use candela_vm::rt::Span;
83use candela_vm::rt::Struct;
84use candela_vm::vm;
85use candela_vm::vm::RegisterFile;
86use rustc_hash::FxHashMap;
87use smol_strc::SmolStr;
88use std::path::Path;
89use std::path::PathBuf;
90
91// `Engine::compile` and `Program::call` recover from a compile error by
92// catching the unwind the error funnel raises, so this API exists only under an
93// unwinding panic strategy. Built with `panic = "abort"` the first error in a
94// script would abort the process instead of coming back as a `Diagnostic`,
95// which is what the LSP and every embedding host read.
96//
97// wasm32 aborts on panic whatever the profile says, so the check is for the
98// profiles that build the toolchain.
99#[cfg(not(target_arch = "wasm32"))]
100const _: () = assert!(
101    cfg!(panic = "unwind"),
102    "the candela embedding API needs an unwinding panic strategy; see [profile.release]"
103);
104
105/// The persistent embedding entry point. Holds the table of registered host
106/// functions and compiles scripts into reusable [`Program`]s.
107///
108/// This is the library analogue of the one-shot [`crate::candela_run`]: it does
109/// not run a script and hand back stdout, it keeps compiler + VM state resident
110/// so the host can call into the script repeatedly.
111#[derive(Default)]
112pub struct Engine {
113    registry: HostRegistry,
114    macros: MacroEnv,
115    resolver: ImportResolver,
116    cfg: Cfg,
117}
118
119impl Engine {
120    #[must_use]
121    pub fn new() -> Self {
122        Self::default()
123    }
124
125    /// Points library imports at `dir` instead of the directory the toolchain
126    /// installed.
127    ///
128    /// `dir` is the one that holds `std/`, so `import "std/string";` reads
129    /// `dir/std/string.cdl`. A host that ships the standard library inside its
130    /// own application directory names it here, and the scripts it compiles
131    /// find it wherever the application was installed.
132    ///
133    /// ```no_run
134    /// let engine = candela::Engine::new().with_lib_dir("/opt/myapp/libs");
135    /// ```
136    #[must_use]
137    pub fn with_lib_dir(mut self, dir: impl Into<PathBuf>) -> Self {
138        self.resolver.set_lib_dir(dir.into());
139        self
140    }
141
142    /// Sets the flags `@cfg(...)` attributes test in the scripts this engine
143    /// compiles.
144    ///
145    /// Code under a `@cfg` whose condition is false is dropped before names
146    /// resolve, so it may import a module or call a function that does not
147    /// exist here. A flag the configuration does not enable is false.
148    ///
149    /// ```no_run
150    /// let engine = candela::Engine::new().with_cfg(candela::Cfg::from_iter(["web"]));
151    /// ```
152    #[must_use]
153    pub fn with_cfg(mut self, cfg: Cfg) -> Self {
154        self.cfg = cfg;
155        self
156    }
157
158    /// Makes `dir` the root of the package a script imports as `name`.
159    ///
160    /// The package is entered through the file its `candela.toml` names as
161    /// `entry`, or `src/main.cdl` when the manifest names none or there is no
162    /// manifest. `import "shapes";` then reads that file, and
163    /// `import "shapes/circle";` reads `circle.cdl` from the entry's
164    /// directory. `dir` is searched for native libraries too, so a package
165    /// that ships a shared library under its root binds a `dylib` import with
166    /// no further setup.
167    ///
168    /// ```no_run
169    /// let engine = candela::Engine::new().with_import_root("shapes", "/cache/shapes/1.2.3");
170    /// ```
171    #[must_use]
172    pub fn with_import_root(mut self, name: &str, dir: impl Into<PathBuf>) -> Self {
173        let dir = dir.into();
174        let entry = package_entry(&dir);
175        self.resolver.add_root(name, dir, entry);
176        self
177    }
178
179    /// Registers a typed host function under `namespace::name`.
180    ///
181    /// The closure may take any combination of `i64`/`i32`, `f64`, `bool`,
182    /// `String` (or a single `&str`) arguments and return one of those or `()`.
183    /// The declared types are checked against the script's `host` block when
184    /// [`Engine::compile`] runs; a mismatch is a clean [`Diagnostic`], never a
185    /// panic.
186    ///
187    /// A closure that can fail returns `Result<T, HostError>` instead of `T`,
188    /// and the error is raised at the call site in the script:
189    ///
190    /// ```no_run
191    /// use candela::HostError;
192    ///
193    /// let mut engine = candela::Engine::new();
194    /// engine.register_host_fn("fs", "read", |path: &str| {
195    ///     std::fs::read_to_string(path).map_err(HostError::new)
196    /// });
197    /// ```
198    ///
199    /// The type checked against the declaration is the `T` inside the `Result`,
200    /// so both spellings bind to the same `host` signature.
201    pub fn register_host_fn<Marker, F>(&mut self, namespace: &str, name: &str, f: F)
202    where
203        F: IntoHostFn<Marker>,
204    {
205        self.registry.register_host_fn(namespace, name, f);
206    }
207
208    /// Registers a host function whose signature is given as data rather than
209    /// derived from a Rust closure's types.
210    ///
211    /// The closure takes the arguments as a `&[Value]` slice, and `arg_types` /
212    /// `ret_type` say what the script may pass and expect. The binding is
213    /// checked against the `host` block exactly as [`Engine::register_host_fn`]
214    /// is, so a declaration that disagrees is a [`Diagnostic`] at
215    /// [`Engine::compile`] time, and the declaration must not use `...`.
216    ///
217    /// ```no_run
218    /// use candela::{HostType, Value};
219    ///
220    /// let mut engine = candela::Engine::new();
221    /// engine.register_host_fn_typed(
222    ///     "gpio",
223    ///     "read",
224    ///     vec![HostType::Int],
225    ///     HostType::Int,
226    ///     |args: &[Value]| Ok(Value::Int(args[0].as_i64().unwrap_or(0))),
227    /// );
228    /// ```
229    ///
230    /// Use it when the signature is only known at run time: a plugin table, a
231    /// generated binding, anything with no Rust signature to read the types
232    /// from.
233    pub fn register_host_fn_typed<F>(
234        &mut self,
235        namespace: &str,
236        name: &str,
237        arg_types: Vec<HostType>,
238        ret_type: HostType,
239        f: F,
240    ) where
241        F: Fn(&[Value]) -> Result<Value, HostError> + 'static,
242    {
243        self.registry
244            .register_host_fn_typed(namespace, name, arg_types, ret_type, f);
245    }
246
247    /// Registers a variadic host function under `namespace::name`.
248    ///
249    /// Unlike [`Engine::register_host_fn`], the closure receives every argument
250    /// as a `&[Value]` slice of any length and returns a single [`Value`] (or a
251    /// [`HostError`] to raise in the script), so arguments of mixed /
252    /// dynamically-typed shape can cross the boundary without a fixed Rust
253    /// signature. The `host` block must declare the function with a `...`
254    /// argument list:
255    ///
256    /// ```candela
257    /// host "app" {
258    ///     log(...);
259    /// }
260    /// ```
261    ///
262    /// No arity or per-argument type checking is performed at the call site;
263    /// the closure interprets the slice it is handed. A non-variadic
264    /// declaration bound to a variadic closure (or vice versa) is a clean
265    /// [`Diagnostic`] at [`Engine::compile`] time.
266    pub fn register_host_fn_variadic<F>(&mut self, namespace: &str, name: &str, f: F)
267    where
268        F: Fn(&[Value]) -> Result<Value, HostError> + 'static,
269    {
270        self.registry.register_host_fn_variadic(namespace, name, f);
271    }
272
273    /// Registers the expander for `name!( ... )` invocations in the scripts this
274    /// engine compiles.
275    ///
276    /// The expander receives the raw text between the parentheses, which
277    /// candela does not interpret, and returns candela source for one
278    /// expression that is parsed in its place. A [`MacroError`] it returns
279    /// instead becomes a compile error at the macro, at the byte offset into
280    /// the region the error names.
281    ///
282    /// ```no_run
283    /// use candela::macros::MacroError;
284    ///
285    /// let mut engine = candela::Engine::new();
286    /// engine.register_macro("rows", |body: &str| {
287    ///     Ok::<String, MacroError>(body.lines().count().to_string())
288    /// });
289    /// ```
290    pub fn register_macro<F>(&mut self, name: &str, expander: F)
291    where
292        F: Fn(&str) -> Result<String, MacroError> + 'static,
293    {
294        self.macros.register(name, expander);
295    }
296
297    /// Sets what a macro with no registered expander does: fail the compile
298    /// naming it (the default), or, when `allow` is true, compile as `null`.
299    ///
300    /// Tooling that reads scripts written for a host it is not part of turns
301    /// this on, so the host's macros do not read as errors.
302    pub const fn allow_unknown_macros(&mut self, allow: bool) {
303        self.macros.allow_unknown(allow);
304    }
305
306    /// Type-checks `src` the way [`Engine::compile`] does, without producing a
307    /// program, and returns the warnings the compile raised.
308    ///
309    /// Every function whose parameters are all annotated is checked at those
310    /// types, and a function a host would call with a bare parameter is
311    /// checked with it typed `any`, as `compile` does. What this leaves out is
312    /// everything a check does not need: a `dylib` block binds the signatures
313    /// it declares without opening its library, so a script whose C library a
314    /// build step has not produced yet still checks; `host` blocks are not
315    /// matched against registered closures; `main` is not required and
316    /// nothing runs.
317    ///
318    /// # Errors
319    ///
320    /// Returns the [`Diagnostic`] of the first error: a parse or type error, a
321    /// body that does not compile at its declared parameter types, or a `dylib`
322    /// signature naming a type C cannot represent.
323    pub fn check(&self, src: &str, filename: &str) -> Result<Vec<Diagnostic>, Diagnostic> {
324        let resolver = &self.resolver;
325        self.cfg.scope(|| {
326            self.macros.scope(|| {
327                collect_diagnostic(|| {
328                    collect_warnings(|| {
329                        let _ = check_only(src.to_owned(), filename, resolver);
330                    })
331                    .1
332                })
333            })
334        })
335    }
336
337    /// Compiles `src` into a reusable [`Program`], binding every `host` function
338    /// it declares to the matching registered closure.
339    ///
340    /// Every function in `src` whose parameters are all annotated is compiled at
341    /// those declared types, whether or not anything calls it, so an error in
342    /// the body of a function `main` never calls comes back from here rather
343    /// than from the first [`Program::call`]. A function with a bare parameter
344    /// that nothing in the script calls is checked with that parameter typed
345    /// `any`, and warned about; the warnings come back on
346    /// [`Program::warnings`]. A function an import brought in stays lazy.
347    ///
348    /// `main` is executed once here (module instantiation), so any top-level
349    /// setup runs before the host makes its first [`Program::call`]. The
350    /// entry-point check runs first, so a broken body is reported before any
351    /// top-level side effect.
352    ///
353    /// # Errors
354    ///
355    /// Returns a [`Diagnostic`] if the script fails to parse/type-check, if the
356    /// body of an annotated function does not compile at its declared parameter
357    /// types, if the script declares no `main`, if a declared `host` function
358    /// has no registered closure, if a registered closure's arity/types
359    /// disagree with the `host` block, or if running `main` raises a runtime
360    /// error.
361    pub fn compile(&self, src: &str, filename: &str) -> Result<Program, Diagnostic> {
362        let filename_owned = filename.to_owned();
363        let resolver = &self.resolver;
364        let (out, warnings): (CompileOutput, Vec<Diagnostic>) = self.cfg.scope(|| {
365            self.macros.scope(|| {
366                collect_diagnostic(|| {
367                    collect_warnings(|| {
368                        // `compile_checked` compiles an entry point for every
369                        // annotated function, which is what makes this a check
370                        // step: a body error in a function `main` never calls
371                        // is reported now, not on the first `Program::call`
372                        // that reaches it. It also leaves those
373                        // specialisations warm for that call.
374                        let (out, _) = compile_checked(src.to_owned(), &filename_owned, resolver);
375                        // A `Program` runs `main` as soon as it is built, so an
376                        // embedded program needs one the way a run from the CLI
377                        // does.
378                        out.require_main();
379                        out
380                    })
381                })
382            })
383        })?;
384
385        // Bind each declared host function to a registered closure, validating
386        // arity + types against the closure's derived signature.
387        let host_dispatch: Vec<HostDispatch> = self
388            .registry
389            .bind(&out.host_fns, &out.structs)
390            .map_err(|e| Diagnostic {
391                filename: filename.to_owned(),
392                span: 0..0,
393                message: e.to_string(),
394                code: e.code().to_owned(),
395            })?;
396
397        let mut program = Program {
398            instructions: out.instructions,
399            registers: out.registers,
400            pools: out.pools,
401            instr_src: out.instr_src,
402            callsite_registers: out.callsite_registers,
403            dyn_lib_fns: out.dyn_lib_fns,
404            host_sigs: out.host_fns,
405            host_dispatch,
406            allocated_arg_count: out.allocated_arg_count,
407            allocated_call_depth: out.allocated_call_depth,
408            sources: out.sources,
409            structs: out.structs,
410            enums: out.enums,
411            functions: out.functions,
412            dyn_libs: out.dyn_libs,
413            namespaces: out.namespaces,
414            const_registers: out.const_registers,
415            free_registers: out.free_registers,
416            indirect_registers: out.indirect_registers,
417            generics: out.generics,
418            warnings,
419            calls: FxHashMap::default(),
420            event_entry: out.event_entry.map(|entry| CompiledCall {
421                start: entry.entry as usize,
422                arg_registers: entry.arg_registers.into_boxed_slice(),
423                ret_register: entry.ret_register,
424            }),
425            attributes: out.attributes,
426        };
427
428        // Instantiate: run `main` once so top-level state is established before
429        // the first host-driven call.
430        program.execute_from(0)?;
431        Ok(program)
432    }
433}
434
435/// A compiled candela program with resident interpreter state.
436///
437/// Registers and heap pools persist between [`Program::call`] invocations, so
438/// state established by one call (including anything a host function mutates on
439/// the Rust side) is visible to the next.
440///
441/// `Program` is single-threaded (`!Send`/`!Sync`): it holds `Rc` dispatchers
442/// and reflects candela's single-threaded VM.
443pub struct Program {
444    // ---- VM state (persists across calls) ----
445    instructions: Vec<Instr>,
446    registers: Vec<Data>,
447    pools: Pools,
448    instr_src: Vec<InstrSrc>,
449    callsite_registers: Vec<Vec<u16>>,
450    dyn_lib_fns: Vec<DynamicLibFn>,
451    host_sigs: Vec<HostFnSig>,
452    host_dispatch: Vec<HostDispatch>,
453    allocated_arg_count: usize,
454    allocated_call_depth: usize,
455    sources: Vec<Source>,
456    structs: Vec<Struct>,
457    enums: Vec<EnumType>,
458    // ---- compiler state (drives on-demand call trampolines) ----
459    functions: Vec<Function>,
460    dyn_libs: Vec<Dynamiclib>,
461    namespaces: FileNamespaces,
462    const_registers: FxHashMap<Data, u16>,
463    free_registers: Vec<u16>,
464    generics: Generics,
465    indirect_registers: IndirectRegisters,
466    /// The warnings the compile raised, in the order it raised them.
467    warnings: Vec<Diagnostic>,
468    /// The trampoline compiled for each function and argument types a host
469    /// has called with.
470    calls: FxHashMap<(String, String), CompiledCall>,
471    /// The trampoline event handlers run through, when the program imports
472    /// `std/event`.
473    event_entry: Option<CompiledCall>,
474    /// The attributes the program's scripts wrote.
475    attributes: Vec<Attribute>,
476}
477
478/// A host call compiled onto the resident instruction stream.
479#[derive(Clone)]
480struct CompiledCall {
481    /// Where the trampoline starts.
482    start: usize,
483    /// The registers it reads its arguments from, in order.
484    arg_registers: Box<[u16]>,
485    /// The register the call's value lands in.
486    ret_register: u16,
487}
488
489impl Program {
490    /// The warnings compiling this program raised, in the order they were
491    /// raised. A warning does not stop the compile; see the warnings section
492    /// of the error reference for what each one means.
493    #[must_use]
494    pub fn warnings(&self) -> &[Diagnostic] {
495        &self.warnings
496    }
497
498    /// Invokes the script-defined function `fn_name` with `args`, returning its
499    /// value (or [`Value::Null`] for a void function).
500    ///
501    /// The first call with a given set of argument types compiles a small
502    /// trampoline (which specializes `fn_name` for those types if it hasn't
503    /// been already) onto the resident instruction stream; later calls with
504    /// the same types run it again. It runs against the persistent
505    /// register/heap state, so globals mutated by a previous call remain
506    /// visible.
507    ///
508    /// A diagnostic raised while compiling the trampoline leaves the resident
509    /// tables exactly as they stood before this call began, and the `Program`
510    /// stays callable afterward.
511    ///
512    /// # Errors
513    ///
514    /// Returns a [`Diagnostic`] if `fn_name` is unknown, if the arguments don't
515    /// type-check against its signature, or if the call raises a runtime error.
516    pub fn call(&mut self, fn_name: &str, args: &[Value]) -> Result<Value, Diagnostic> {
517        let call = self.run_call(fn_name, args)?;
518        Ok(self.read_register(call.ret_register))
519    }
520
521    /// [`Self::call`], handing back what the function left in each argument it
522    /// was passed by reference.
523    ///
524    /// A list, a map and a struct reach a script function by reference, so
525    /// what the function writes into one is written into the value the call
526    /// passed. Once the call returns, every argument that is one of those is
527    /// replaced with its final value; every other argument is left as it was.
528    ///
529    /// # Errors
530    ///
531    /// As [`Self::call`]. An argument is only replaced once the call has run
532    /// without an error.
533    pub fn call_in_out(&mut self, fn_name: &str, args: &mut [Value]) -> Result<Value, Diagnostic> {
534        let call = self.run_call(fn_name, args)?;
535        for (arg, &register) in args.iter_mut().zip(call.arg_registers.iter()) {
536            if passed_by_reference(arg) {
537                *arg = self.read_register(register);
538            }
539        }
540        Ok(self.read_register(call.ret_register))
541    }
542
543    /// Every attribute the program's scripts wrote, with the struct and enum
544    /// tables the types in it refer to.
545    #[must_use]
546    pub fn attributes(&self) -> AttributeTable {
547        AttributeTable::new(self.attributes.clone(), &self.structs, &self.enums)
548    }
549
550    /// The value register `register` holds, read back into a host [`Value`].
551    fn read_register(&self, register: u16) -> Value {
552        unmarshal_value(
553            self.registers[register as usize],
554            &self.pools.objs,
555            &self.pools.maps,
556            &self.pools.strings,
557            &self.structs,
558            &self.enums,
559        )
560    }
561
562    /// An argument-type diagnostic for argument `index` of `fn_name`.
563    fn argument_error(&self, fn_name: &str, index: usize, why: &str) -> Diagnostic {
564        Diagnostic {
565            filename: self
566                .sources
567                .first()
568                .map(|source| source.filename.to_string())
569                .unwrap_or_default(),
570            span: 0..0,
571            message: format!("argument {} of '{fn_name}' {why}", index + 1),
572            code: String::from("argument_type_mismatch"),
573        }
574    }
575
576    /// Checks `args`, compiles or reuses the trampoline for their types, writes
577    /// them into it and runs it, answering the trampoline.
578    fn run_call(&mut self, fn_name: &str, args: &[Value]) -> Result<CompiledCall, Diagnostic> {
579        // An enum travels outward only, and no parameter accepts one, not even
580        // an `any` one that accepts everything else. Refusing it here, before
581        // anything is marshalled, is what keeps the script from reading a null
582        // the host never passed.
583        if let Some((index, value)) = args.iter().enumerate().find(|(_, v)| holds_enum(v)) {
584            return Err(self.argument_error(
585                fn_name,
586                index,
587                &format!(
588                    "cannot be a {}: an enum value crosses the boundary outward only",
589                    describe_value(value)
590                ),
591            ));
592        }
593
594        // A call is compiled once per function and argument types, into a
595        // trampoline that reads its arguments from registers of its own, and
596        // every later call with the same types writes them and runs it again.
597        // The key renders the types, since `DataType` equality lets an empty
598        // list stand for a list of anything.
599        let mut types: Vec<DataType> = Vec::with_capacity(args.len());
600        for (index, arg) in args.iter().enumerate() {
601            let ty = value_datatype(arg, &self.structs);
602            // A struct is built field by field from the declaration it names,
603            // so it has to match that declaration before anything is built.
604            if holds_struct(arg) && !value_matches_type(arg, &ty, &self.structs) {
605                return Err(self.argument_error(
606                    fn_name,
607                    index,
608                    &format!(
609                        "is a {} that does not match the struct it names: every field the struct declares, with a value of its type, and no other",
610                        describe_value(arg)
611                    ),
612                ));
613            }
614            types.push(ty);
615        }
616        let key = (fn_name.to_owned(), format!("{types:?}"));
617        let call = if let Some(call) = self.calls.get(&key) {
618            marshal_args(
619                args,
620                &call.arg_registers,
621                &mut self.registers,
622                &mut self.pools,
623                &self.structs,
624            );
625            call.clone()
626        } else {
627            let call = self.compile_call(fn_name, args, types)?;
628            self.calls.insert(key, call.clone());
629            call
630        };
631
632        self.execute_from(call.start)?;
633        Ok(call)
634    }
635
636    /// Compiles the trampoline for a call of `fn_name` with arguments of
637    /// `types`, and leaves `args` in the registers it reads them from.
638    ///
639    /// A diagnostic raised while compiling it (an undeclared name at the call
640    /// site, a type mismatch, a nested call that needed its own
641    /// specialization first) leaves the resident tables exactly as they stood
642    /// before; see [`State::rollback_to`].
643    fn compile_call(
644        &mut self,
645        fn_name: &str,
646        args: &[Value],
647        types: Vec<DataType>,
648    ) -> Result<CompiledCall, Diagnostic> {
649        // Every table a trampoline compile can grow is snapshotted up front, so
650        // a diagnostic raised while compiling it can be undone rather than
651        // leaving a half-compiled specialization for a later call to trip on.
652        let checkpoint = self.compiler_state().checkpoint();
653
654        // Each argument is a variable seeded into a register of its own, which
655        // holds this call's value while the trampoline compiles.
656        if self.registers.len() + args.len() > PROGRAM_LIMIT {
657            return Err(collect_diagnostic(|| {
658                program_too_large(ProgramLimit::Registers, &self.functions, &self.sources)
659            })
660            .unwrap_err());
661        }
662        let arg_registers: Box<[u16]> = args
663            .iter()
664            .map(|_| {
665                self.registers.push(NULL);
666                (self.registers.len() - 1) as u16
667            })
668            .collect();
669        marshal_args(
670            args,
671            &arg_registers,
672            &mut self.registers,
673            &mut self.pools,
674            &self.structs,
675        );
676
677        let dummy = Span { start: 0, end: 0 };
678        let mut arg_exprs: Vec<Expr> = Vec::with_capacity(args.len());
679        let mut seed_vars: Vec<Variable> = Vec::with_capacity(args.len());
680        for (i, (&register_id, var_type)) in arg_registers.iter().zip(types).enumerate() {
681            let name = SmolStr::from(format!("__host_arg{i}"));
682            seed_vars.push(Variable {
683                declared: None,
684                name: name.clone(),
685                register_id,
686                cell: false,
687                var_type,
688            });
689            arg_exprs.push(Expr::Var(name, dummy));
690        }
691
692        let arg_spans: Box<[Span]> = args.iter().map(|_| dummy).collect();
693        let call_expr = Expr::FunctionCall(
694            arg_exprs.into_boxed_slice(),
695            Box::from([SmolStr::from(fn_name)]),
696            dummy,
697            arg_spans,
698            Box::from([]),
699        );
700
701        // Compile the trampoline (type-checks the call) under a diagnostic sink.
702        let offset = self.instructions.len() as u16;
703        let (mut output, ret_id) = match collect_diagnostic(|| {
704            let mut state = self.compiler_state();
705            let compiled = compile_trampoline(&mut state, offset, &call_expr, seed_vars);
706            // The halt that ends the run comes after it.
707            state.check_instructions(usize::from(offset) + compiled.0.len() + 1);
708            compiled
709        }) {
710            Ok(compiled) => compiled,
711            Err(diagnostic) => {
712                self.compiler_state().rollback_to(&checkpoint);
713                return Err(diagnostic);
714            }
715        };
716
717        output.push(Instr::Halt(0));
718        use_immediates(
719            &mut output,
720            &self.instructions,
721            &self.registers,
722            &self.const_registers,
723        );
724        let start = self.instructions.len();
725        self.instructions.extend(output);
726        Ok(CompiledCall {
727            start,
728            arg_registers,
729            ret_register: ret_id.unwrap_or(0),
730        })
731    }
732
733    /// Runs the handlers of events that have arrived for this program, at
734    /// most `budget` of them, and answers how many ran. Never waits.
735    ///
736    /// A host that runs its own loop calls this from it, on the thread the
737    /// program runs on, after the waker it set with
738    /// [`set_event_waker`](crate::set_event_waker) said something arrived. A
739    /// program that does not import `std/event` has no handlers, and the
740    /// answer is always 0.
741    ///
742    /// # Errors
743    ///
744    /// Returns a [`Diagnostic`] when a handler raised an error no `try`
745    /// caught. The events behind it stay queued for the next call.
746    pub fn dispatch_events(&mut self, budget: u32) -> Result<usize, Diagnostic> {
747        let Some(entry) = &self.event_entry else {
748            return Ok(0);
749        };
750        let (start, ret) = (entry.start, entry.ret_register as usize);
751        self.registers[entry.arg_registers[0] as usize] = Data::int(i64::from(budget));
752        self.registers[entry.arg_registers[1] as usize] = Data::from(false);
753        self.execute_from(start)?;
754        Ok(self.registers[ret].as_int().max(0) as usize)
755    }
756
757    /// Does up to about `budget` units of garbage collection while the
758    /// program is idle, and answers whether no collection work is left.
759    ///
760    /// Call it between calls into the program, where the host would otherwise
761    /// wait, such as between frames. It carries on a collection already under
762    /// way, or begins one when the heap has grown enough since the last; on a
763    /// heap that has not, it does nothing and answers `true`. A unit is about
764    /// one object traced or one freed slot, never a length of time, so the
765    /// same calls do the same work on every machine. `collect(u32::MAX)` runs
766    /// a whole collection. Beginning a collection reads every root at once
767    /// whatever the budget.
768    ///
769    /// Once a host has called this, allocations leave more of the work to it
770    /// and begin a collection themselves only when the heap has grown further.
771    pub fn collect(&mut self, budget: u32) -> bool {
772        self.pools.collect(&self.registers, budget)
773    }
774
775    /// What the collector has done over this program's heap, and how large
776    /// the heap is. See [`GcStats`].
777    #[must_use]
778    pub fn gc_stats(&self) -> GcStats {
779        self.pools.gc_stats()
780    }
781
782    /// Borrows the resident compiler state a trampoline compile writes into.
783    fn compiler_state(&mut self) -> State<'_> {
784        State {
785            registers: &mut self.registers,
786            fns: &mut self.functions,
787            structs: &mut self.structs,
788            enums: &mut self.enums,
789            pools: &mut self.pools,
790            instr_src: &mut self.instr_src,
791            callsite_registers: &mut self.callsite_registers,
792            dyn_libs: &mut self.dyn_libs,
793            allocated_arg_count: &mut self.allocated_arg_count,
794            allocated_call_depth: &mut self.allocated_call_depth,
795            const_registers: &mut self.const_registers,
796            free_registers: &mut self.free_registers,
797            sources: &mut self.sources,
798            reserved_registers: rustc_hash::FxHashSet::default(),
799            value_callsites: rustc_hash::FxHashSet::default(),
800            optimize: false,
801            namespaces: &mut self.namespaces,
802            generics: &mut self.generics,
803            indirect_registers: &mut self.indirect_registers,
804            propagations: Vec::new(),
805            fn_returns: Vec::new(),
806            captured_binders: Vec::new(),
807            string_slots: StringSlots::default(),
808            chain_values: Vec::new(),
809            literal_target: None,
810        }
811    }
812
813    /// Runs the VM against the resident state starting at instruction `start`,
814    /// capturing any error as a [`Diagnostic`].
815    fn execute_from(&mut self, start: usize) -> Result<(), Diagnostic> {
816        let err_ctx = ErrorCtx {
817            instr_src: &self.instr_src,
818            sources: &self.sources,
819        };
820
821        // Move the register file out so the VM can borrow it mutably, then
822        // reclaim it (register state must persist across calls).
823        let mut register_file = RegisterFile(std::mem::take(&mut self.registers));
824
825        let instructions = &self.instructions;
826        let pools = &mut self.pools;
827        let callsite_registers = &self.callsite_registers;
828        let dyn_lib_fns = &self.dyn_lib_fns;
829        let structs = &self.structs;
830        let enums = &self.enums;
831        let host_sigs = &self.host_sigs;
832        let host_dispatch = &self.host_dispatch;
833        let allocated_arg_count = self.allocated_arg_count;
834        let allocated_call_depth = self.allocated_call_depth;
835
836        // An error comes back as a value, so a call sets up no unwind and
837        // leaves the process panic hook alone.
838        let result = vm::execute(
839            instructions,
840            &mut register_file,
841            pools,
842            &err_ctx,
843            callsite_registers,
844            dyn_lib_fns,
845            structs,
846            enums,
847            allocated_arg_count,
848            allocated_call_depth,
849            host_sigs,
850            host_dispatch,
851            start,
852            None,
853        );
854
855        self.registers = std::mem::take(&mut register_file.0);
856        result.map_err(|error| error.diagnostic(&err_ctx))
857    }
858}
859
860/// Infers the candela [`DataType`] of a [`Value`] so a host-provided array/map
861/// argument can be given a type the call site type-checks against. Homogeneous
862/// element/value types are assumed (matching candela's static collection typing);
863/// the first element is sampled, empty collections yield an unknown element type.
864/// A struct is the one `structs` names it by, and `any` when it names none, which
865/// the check in [`Program::call`] then refuses. An enum only travels outward,
866/// and [`Program::call`] refuses an argument holding one before it gets here, so
867/// that arm is what keeps the match exhaustive rather than a type anything is
868/// given.
869fn value_datatype(v: &Value, structs: &[Struct]) -> DataType {
870    match v {
871        Value::Null | Value::Enum { .. } => DataType::Null,
872        Value::Int(_) => DataType::Int,
873        Value::Float(_) => DataType::Float,
874        Value::Bool(_) => DataType::Bool,
875        Value::String(_) => DataType::String,
876        Value::Array(items) => {
877            DataType::Array(items.first().map(|e| Box::new(value_datatype(e, structs))))
878        }
879        Value::Map(entries) => {
880            let value = entries.values().next().map(|e| value_datatype(e, structs));
881            DataType::Map(Box::new((Some(DataType::String), value)))
882        }
883        Value::Struct { name, .. } => {
884            struct_id(name, structs).map_or(DataType::Unknown, DataType::Struct)
885        }
886    }
887}
888
889/// Whether `v` is a struct or holds one.
890fn holds_struct(v: &Value) -> bool {
891    match v {
892        Value::Struct { .. } => true,
893        Value::Array(items) => items.iter().any(holds_struct),
894        Value::Map(entries) => entries.values().any(holds_struct),
895        _ => false,
896    }
897}
898
899/// The entry a package at `dir` is imported through, relative to `dir`: what
900/// its manifest names, or the default when there is no manifest to ask or it
901/// cannot be read. A manifest the `candela` command would refuse is not this
902/// API's to judge; the import simply lands on the default.
903#[cfg(not(target_arch = "wasm32"))]
904fn package_entry(dir: &Path) -> String {
905    Manifest::load(&dir.join(MANIFEST_NAME)).map_or_else(
906        |_| String::from(DEFAULT_PACKAGE_ENTRY),
907        |m| m.entry().to_owned(),
908    )
909}
910
911/// The wasm build carries no manifest reader, so every package enters at the
912/// default.
913#[cfg(target_arch = "wasm32")]
914fn package_entry(_dir: &Path) -> String {
915    String::from(DEFAULT_PACKAGE_ENTRY)
916}