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, ®ister) 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, (®ister_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}