candela_vm/artifact.rs
1//! Bytecode artifact format (`.cdlb`) and the VM-only load/run API.
2//!
3//! This mirrors an AOT model: the full `candela` toolchain (compiler + VM)
4//! compiles a `.cdl` source to a compact, self-contained bytecode artifact
5//! ([`ProgramImage`] serialized via [`serialize_image`]), and the VM-only
6//! `candela-vm` binary loads it ([`load_program`]) and runs it
7//! ([`RuntimeProgram::run`]) WITHOUT the parser, compiler, or REPL.
8//!
9//! An embedding host gets the same two halves the `Engine`/`Program` pair
10//! gives it, minus the compiler: it supplies a [`HostRegistry`] at load so the
11//! artifact's `host` functions bind to Rust closures, and it invokes script
12//! functions by name through [`RuntimeProgram::call`], which runs a trampoline
13//! the compiler emitted at build time.
14//!
15//! The on-disk format is: a 4-byte magic (`CDLB`), a 1-byte format version, then
16//! a `postcard`-encoded [`ProgramImage`]. `postcard` was chosen over `bincode`
17//! because it is `no_std`/`alloc`-friendly and its varint encoding keeps the
18//! artifact small; it also pulls in the least code, which matters for the
19//! `candela-vm` binary-size budget.
20//!
21//! [`ProgramImage`] carries `pub` fields so the `candela` crate's `build`
22//! subcommand can populate it from a fresh compile; everything needed to LOAD
23//! and RUN it lives here.
24
25use crate::attributes::Attribute;
26use crate::attributes::AttributeTable;
27use crate::data::Data;
28use crate::embed::HostBindError;
29use crate::embed::HostDispatch;
30use crate::embed::HostRegistry;
31use crate::embed::Value;
32use crate::embed::describe_value;
33use crate::embed::marshal_args;
34use crate::embed::unmarshal_value;
35use crate::embed::value_matches_type;
36use crate::errors::Diagnostic;
37use crate::errors::ErrorCtx;
38use crate::errors::RuntimeError;
39use crate::instr::Instr;
40use crate::rt::DataType;
41use crate::rt::DynamicLibFn;
42use crate::rt::EnumType;
43use crate::rt::EnumVariant;
44use crate::rt::GcStats;
45use crate::rt::HostFnSig;
46use crate::rt::InstrSrc;
47use crate::rt::LibraryOrigin;
48use crate::rt::Pools;
49use crate::rt::Source;
50use crate::rt::Span;
51use crate::rt::Struct;
52#[cfg(not(target_arch = "wasm32"))]
53use crate::rt::TargetOs;
54#[cfg(not(target_arch = "wasm32"))]
55use crate::rt::resolve_library_filename;
56use crate::vm;
57use crate::vm::CandelaMap;
58use crate::vm::MapPool;
59use crate::vm::ObjectPool;
60use crate::vm::Pool;
61use crate::vm::RegisterFile;
62use crate::vm::StringPool;
63use serde::Deserialize;
64use serde::Serialize;
65use smol_strc::SmolStr;
66use std::collections::HashMap;
67
68/// The pair of words a value is recorded as. See [`Data::into_words`].
69pub type DataWords = (u64, i64);
70
71/// 4-byte artifact magic, so a non-`.cdlb` file fails cleanly.
72const MAGIC: [u8; 4] = *b"CDLB";
73/// Bumped whenever the serialized shape changes, so a mismatched artifact is
74/// rejected instead of mis-decoded. Version 2 added the dynamic-library and
75/// host-function recipe tables (`dyn_lib_fns`/`host_fns`). Version 3 added the
76/// native-enum type table (`enums`) and the `CloneEnum` instruction. Version 4
77/// added the map/json/any library functions (`Keys`/`Values`/`JsonParse`/
78/// `JsonStringify` and the `is_*`/`as_*` value ops). Version 5 added the export
79/// table (`exports`), the call trampolines that back
80/// [`RuntimeProgram::call`]. Version 6 added the `MapRemove` instruction and
81/// the origin of each dynamic-library recipe, which says whether its spec is
82/// the program's own or a path into the standard library's `libs` directory.
83/// Version 7 widened `int` to 64 bits, so every recorded value carries a
84/// second word. Version 8 added the cell instructions a captured variable is
85/// read and written through. Version 9 added the indirect call, which dispatches
86/// on the function a value carries. Version 10 added the instruction that
87/// builds a function value, which tells a function from the list it is built
88/// as wherever one becomes text. Version 11 added the string comparison and
89/// bitwise instructions, which sit among the existing ones and so renumber the
90/// instructions after them, and gave the order of each map's recorded pairs a
91/// meaning: a map is walked in the order its keys went in, so the pair list is
92/// the program's order and an artifact from before the change cannot supply it.
93/// Version 12 added the loop step and the add-a-constant instructions, which
94/// sit among the existing ones and so renumber the instructions after them.
95/// Version 13 added the move chain and the add-to-a-float-field instructions,
96/// which renumber the instructions after them the same way. Version 14 added
97/// the machine code sections ([`ProgramImage::native`]) and the function table
98/// that follows the image ([`FunctionTable`]). Version 15 added the type test
99/// `is` compiles to for a struct, an enum, a function, a union or a collection,
100/// and the nested type codes that check what a list or a map holds. Version 16
101/// added the event entry ([`ProgramImage::event_entry`]) and the instructions
102/// `std/event` and the new `std/fs` functions compile to. Version 17 added the
103/// attribute table ([`ProgramImage::attributes`]).
104const FORMAT_VERSION: u8 = 17;
105
106/// Serializable mirror of a compiled program's runtime state.
107///
108/// A dedicated DTO keeps `serde` off the hot runtime types: `Data` becomes its
109/// pair of raw words, `SmolStr` becomes `String`, maps become key/value pairs.
110/// Only [`Instr`], [`Span`], and [`DataType`] carry `serde` derives directly.
111/// Fields are `pub` so the compiler front-end can build an image from a fresh
112/// compile.
113#[derive(Serialize, Deserialize)]
114pub struct ProgramImage {
115 pub instructions: Vec<Instr>,
116 pub registers: Vec<DataWords>,
117 pub objs: Vec<Vec<DataWords>>,
118 pub maps: Vec<Vec<(DataWords, DataWords)>>,
119 pub strings: Vec<String>,
120 pub instr_src: Vec<InstrSrcImage>,
121 /// The registers each recursive call site saves across its call, indexed by
122 /// the call-site id its `SaveFrame` carries.
123 pub callsite_registers: Vec<Vec<u16>>,
124 pub structs: Vec<StructImage>,
125 pub enums: Vec<EnumImage>,
126 pub sources: Vec<SourceImage>,
127 pub allocated_arg_count: u64,
128 pub allocated_call_depth: u64,
129 /// Recipe for each dynamic-library binding, in `DynamicLibFn` id order. The
130 /// artifact stores only the logical library name, symbol, and marshalling
131 /// signature, never the shared object's bytes, so the VM re-opens the
132 /// library and re-binds the symbol by name at load time (see
133 /// [`resolve_library_filename`]).
134 pub dyn_lib_fns: Vec<DynLibFnImage>,
135 /// Recipe for each `host` function declared by the program, in host-fn id
136 /// order. The [`HostRegistry`] handed to [`load_program`] supplies the
137 /// closure behind each one; an unregistered name is a load error.
138 pub host_fns: Vec<HostFnImage>,
139 /// One entry per host-callable function, each with the call trampoline the
140 /// compiler emitted for it at build time. This is what lets the VM invoke a
141 /// script function by name with no compiler present.
142 pub exports: Vec<ExportImage>,
143 /// The trampoline the runtime runs event handlers through: `std/event`'s
144 /// `dispatch`, taking a budget and whether to wait. Present when the
145 /// program imports `std/event`.
146 pub event_entry: Option<ExportImage>,
147 /// Machine code for some of the program's functions, one section per
148 /// machine it was built for. The VM runs the first section this machine
149 /// can run and the bytecode for everything else; a program whose sections
150 /// all name another machine runs on bytecode alone. The bytecode stays
151 /// complete either way.
152 pub native: Vec<NativeImage>,
153 /// Every attribute a `host` block declares that the program's scripts
154 /// wrote on a function or a struct, as the compiler checked it.
155 pub attributes: Vec<Attribute>,
156}
157
158/// Machine code `candela build` generated for one kind of machine, and what
159/// the VM needs to know to run it.
160///
161/// The code has no relocations left: calls between its functions were
162/// resolved when it was laid out, and it reaches the VM only through the
163/// context the VM passes in. Loading it is a copy into memory the VM then
164/// makes executable, and a rewrite of the calls it covers.
165#[derive(Serialize, Deserialize, Clone, Debug)]
166pub struct NativeImage {
167 /// The version of the contract between the code and the VM: the context
168 /// layout, the helper functions, and the layout of a value. A VM that
169 /// speaks another version runs bytecode.
170 pub abi: u32,
171 pub arch: NativeArch,
172 /// The operating system the calling convention is that of.
173 pub os: NativeOs,
174 /// Instruction set extensions the code uses beyond the architecture's
175 /// baseline, by the names Rust's feature detection uses. The VM checks
176 /// each one on the machine it runs on.
177 pub cpu_features: Vec<String>,
178 /// Where the object pool's per-object vector keeps its size, buffer
179 /// pointer and length, as the build measured it. The code reads objects
180 /// through that layout, so the VM checks it against its own.
181 pub object_layout: [u8; 3],
182 /// The most stack one of the functions takes per call, in bytes. The VM
183 /// sizes how deep native recursion may go from it before a call carries
184 /// on in the interpreter.
185 pub frame_bytes: u32,
186 /// The functions the section holds.
187 pub functions: Vec<NativeFunctionImage>,
188 /// The function that stands in for `main`, when `main` itself was
189 /// compiled.
190 pub main: Option<u32>,
191 /// The call instructions the VM rewrites to call into the section.
192 pub sites: Vec<NativeSiteImage>,
193 pub code: Vec<u8>,
194}
195
196/// An architecture machine code is built for.
197#[derive(Serialize, Deserialize, Clone, Copy, Debug, PartialEq, Eq)]
198pub enum NativeArch {
199 X86_64,
200 Aarch64,
201}
202
203/// An operating system whose calling convention machine code follows.
204#[derive(Serialize, Deserialize, Clone, Copy, Debug, PartialEq, Eq)]
205pub enum NativeOs {
206 Linux,
207 MacOs,
208 Windows,
209}
210
211/// One function in a [`NativeImage`].
212#[derive(Serialize, Deserialize, Clone, Debug)]
213pub struct NativeFunctionImage {
214 /// The instruction its bytecode starts at.
215 pub loc: u32,
216 /// Where its entry point starts in the section's code.
217 pub offset: u32,
218 /// Whether it returns a value.
219 pub returns: bool,
220}
221
222/// A call instruction the VM points at a native function once it loads.
223#[derive(Serialize, Deserialize, Clone, Copy, Debug)]
224pub struct NativeSiteImage {
225 /// The instruction, a `CallFunc` or a `CallFuncRecursive`.
226 pub at: u32,
227 /// Its callee, by index into [`NativeImage::functions`].
228 pub function: u32,
229}
230
231/// What the compiler knows about each function of a program, written after
232/// the [`ProgramImage`] in a `.cdlb`.
233///
234/// It is what code generation reads instead of working types out of the
235/// bytecode: where each function starts, which registers its parameters
236/// arrive in, and the type of every value each instruction writes. The VM
237/// never reads it.
238#[derive(Serialize, Deserialize, Clone, Debug, Default)]
239pub struct FunctionTable {
240 pub functions: Vec<FunctionImage>,
241}
242
243/// One compiled function in a [`FunctionTable`]: `main`, or one
244/// specialisation of a declared function or closure.
245#[derive(Serialize, Deserialize, Clone, Debug)]
246pub struct FunctionImage {
247 /// The name the function was declared with; `main` for the program's
248 /// entry.
249 pub name: String,
250 /// The instruction the body starts at.
251 pub entry: u32,
252 /// The register each parameter arrives in, in declaration order.
253 pub params: Vec<u16>,
254 /// The type of each parameter.
255 pub param_types: Vec<DataType>,
256 /// What the function returns: `Null` for nothing.
257 pub returns: DataType,
258 /// The register a closure reads its captured environment from.
259 pub env: Option<u16>,
260 /// Whether a call through a function value can reach it.
261 pub indirect: bool,
262 /// The type of the value each instruction of the body writes into each
263 /// register it writes, in instruction order.
264 pub defs: Vec<DefImage>,
265}
266
267/// The type of one value an instruction writes.
268#[derive(Serialize, Deserialize, Clone, Debug)]
269pub struct DefImage {
270 /// The instruction.
271 pub at: u32,
272 /// The register it writes.
273 pub reg: u16,
274 /// The type of what it writes there. `Unknown` where the compiler cannot
275 /// tell, such as an element of a list built from a literal.
276 pub ty: DataType,
277}
278
279/// Serializable recipe for one dynamic-library binding: enough to re-open the
280/// library and re-resolve the symbol by name at load, with no embedded bytes.
281#[derive(Serialize, Deserialize)]
282pub struct DynLibFnImage {
283 /// Logical library name (`z`, `sqlite3`) or path. A program's own binding
284 /// records it exactly as the source `dylib "..."` block wrote it; a
285 /// standard-library one records it relative to the `libs` directory.
286 pub library: String,
287 /// The C symbol resolved within `library`.
288 pub symbol: String,
289 /// `[ return_type, arg_types... ]`, driving the rebuilt libffi CIF.
290 pub types: Vec<DataType>,
291 /// Which search `library` is resolved through at load.
292 pub origin: LibraryOrigin,
293}
294
295/// Serializable recipe for one `host` function: its fully-qualified name and
296/// marshalling signature, so an embedding runtime can re-bind it by name.
297#[derive(Serialize, Deserialize)]
298pub struct HostFnImage {
299 pub namespace: String,
300 pub name: String,
301 /// `[ return_type, arg_types... ]`.
302 pub types: Vec<DataType>,
303 pub variadic: bool,
304}
305
306impl From<&HostFnImage> for HostFnSig {
307 fn from(image: &HostFnImage) -> Self {
308 Self {
309 types: image.types.clone().into_boxed_slice(),
310 namespace: SmolStr::from(image.namespace.as_str()),
311 name: SmolStr::from(image.name.as_str()),
312 variadic: image.variadic,
313 }
314 }
315}
316
317/// One host-callable function, with the call trampoline `candela build`
318/// compiled for it.
319///
320/// The compiler specialises the function for its declared parameter types and
321/// lays down a short instruction run that moves the parameter registers into
322/// place, calls the specialisation, and halts. Invoking it is then a matter of
323/// writing marshalled arguments into `arg_registers` and executing from
324/// `entry`; the result is left in `ret_register`.
325#[derive(Serialize, Deserialize)]
326pub struct ExportImage {
327 /// The name the function is called by, as written in the source.
328 pub name: String,
329 /// Instruction index the trampoline starts at.
330 pub entry: u64,
331 /// The register holding each parameter, in declaration order.
332 pub arg_registers: Vec<u16>,
333 /// The declared type of each parameter, checked against the host's
334 /// arguments before the call runs.
335 pub arg_types: Vec<DataType>,
336 /// The register the trampoline leaves the result in. Register 0 is the null
337 /// sink, which is what a function returning nothing lands on.
338 pub ret_register: u16,
339}
340
341#[derive(Serialize, Deserialize)]
342pub struct InstrSrcImage {
343 pub instr: Instr,
344 pub span: Span,
345 pub file_id: u16,
346}
347
348#[derive(Serialize, Deserialize)]
349pub struct StructImage {
350 pub name: String,
351 pub fields: Vec<(String, DataType, Span)>,
352 pub id: u16,
353 pub name_span: Span,
354}
355
356#[derive(Serialize, Deserialize)]
357pub struct EnumImage {
358 pub name: String,
359 pub variants: Vec<EnumVariantImage>,
360 pub id: u16,
361 pub name_span: Span,
362}
363
364#[derive(Serialize, Deserialize)]
365pub struct EnumVariantImage {
366 pub name: String,
367 pub payload: Vec<DataType>,
368 pub name_span: Span,
369}
370
371#[derive(Serialize, Deserialize)]
372pub struct SourceImage {
373 pub filename: String,
374 pub contents: String,
375}
376
377/// The registers a call read its arguments from and left its result in.
378struct ExportRegisters {
379 arg_registers: Box<[u16]>,
380 ret_register: u16,
381}
382
383/// Whether a host value reaches a script function by reference, so a call
384/// can hand back what the function did to it.
385#[must_use]
386pub fn passed_by_reference(value: &Value) -> bool {
387 matches!(
388 value,
389 Value::Array(_) | Value::Map(_) | Value::Struct { .. }
390 )
391}
392
393/// One host-callable function in a loaded program: where its trampoline starts,
394/// which registers its parameters live in, and what it leaves the result in.
395struct Export {
396 entry: usize,
397 arg_registers: Box<[u16]>,
398 arg_types: Box<[DataType]>,
399 ret_register: u16,
400}
401
402impl From<ExportImage> for Export {
403 fn from(e: ExportImage) -> Self {
404 Self {
405 entry: e.entry as usize,
406 arg_registers: e.arg_registers.into_boxed_slice(),
407 arg_types: e.arg_types.into_boxed_slice(),
408 ret_register: e.ret_register,
409 }
410 }
411}
412
413/// A loaded, ready-to-run program image with owned runtime state.
414///
415/// Produced by [`load_program`] from `.cdlb` bytes. [`Self::run`] executes it
416/// exactly as the full `candela` binary runs a freshly compiled program, and
417/// [`Self::call`] invokes an exported function by name. Registers and heap
418/// pools stay resident between calls, so state one call establishes is visible
419/// to the next.
420pub struct RuntimeProgram {
421 instructions: Vec<Instr>,
422 registers: Vec<Data>,
423 pools: Pools,
424 instr_src: Vec<InstrSrc>,
425 callsite_registers: Vec<Vec<u16>>,
426 dyn_lib_fns: Vec<DynamicLibFn>,
427 host_sigs: Vec<HostFnSig>,
428 host_dispatch: Vec<HostDispatch>,
429 exports: HashMap<String, Export>,
430 /// Where the event dispatcher's trampoline starts, when there is one.
431 event_entry: Option<Export>,
432 structs: Vec<Struct>,
433 enums: Vec<EnumType>,
434 sources: Vec<Source>,
435 allocated_arg_count: usize,
436 allocated_call_depth: usize,
437 /// The program's machine code, when its artifact carries some this
438 /// machine runs.
439 native: Option<crate::native::NativeCode>,
440 /// The attributes its scripts wrote.
441 attributes: Vec<Attribute>,
442}
443
444impl RuntimeProgram {
445 /// Loads the first of `sections` this machine can run, and points the
446 /// calls it covers at it. Without one the program runs on bytecode.
447 fn load_native(&mut self, sections: &[NativeImage]) {
448 if sections.is_empty() {
449 return;
450 }
451 #[cfg(not(target_arch = "wasm32"))]
452 let dylibs = self
453 .dyn_lib_fns
454 .iter()
455 .map(|f| f.ptr.as_ptr().cast::<u8>())
456 .collect();
457 #[cfg(target_arch = "wasm32")]
458 let dylibs = Vec::new();
459 self.native = crate::native::load(sections, &mut self.instructions, dylibs);
460 }
461
462 /// How many of the program's functions run as machine code on this
463 /// machine: zero when its artifact carries none this machine runs.
464 #[must_use]
465 pub fn native_functions(&self) -> usize {
466 self.native.as_ref().map_or(0, |n| n.functions.len())
467 }
468
469 /// Runs the program's `main` to completion.
470 ///
471 /// A runtime error prints its report and ends the process, matching the
472 /// full `candela <file.cdl>` path exactly. A
473 /// host that wants the error as a value instead runs this inside
474 /// [`collect_diagnostic`](crate::collect_diagnostic).
475 pub fn run(&mut self) {
476 let err_ctx = ErrorCtx {
477 instr_src: &self.instr_src,
478 sources: &self.sources,
479 };
480 let mut register_file = RegisterFile(std::mem::take(&mut self.registers));
481 let result = vm::execute(
482 &self.instructions,
483 &mut register_file,
484 &mut self.pools,
485 &err_ctx,
486 &self.callsite_registers,
487 &self.dyn_lib_fns,
488 &self.structs,
489 &self.enums,
490 self.allocated_arg_count,
491 self.allocated_call_depth,
492 &self.host_sigs,
493 &self.host_dispatch,
494 0,
495 self.native.as_ref(),
496 );
497 self.registers = std::mem::take(&mut register_file.0);
498 if let Err(error) = result {
499 error.report(&err_ctx);
500 }
501 // Work `main` started may still be running: keep running its handlers
502 // until nothing is held and nothing is queued.
503 if self.event_entry.is_some()
504 && let Err(error) = self.run_events(-1, true)
505 {
506 let err_ctx = ErrorCtx {
507 instr_src: &self.instr_src,
508 sources: &self.sources,
509 };
510 error.report(&err_ctx);
511 }
512 }
513
514 /// Runs the handlers of events that have arrived for this program, at
515 /// most `budget` of them, and answers how many ran. Never waits.
516 ///
517 /// A host that runs its own loop calls this from it, on the thread the
518 /// program runs on, after the waker it set with
519 /// [`set_event_waker`](crate::set_event_waker) said something arrived. A
520 /// program that does not import `std/event` has no handlers, and the
521 /// answer is always 0.
522 ///
523 /// # Errors
524 ///
525 /// Returns [`CallError::Runtime`] when a handler raised an error no `try`
526 /// caught. The events behind it stay queued for the next call.
527 pub fn dispatch_events(&mut self, budget: u32) -> Result<usize, CallError> {
528 if self.event_entry.is_none() {
529 return Ok(0);
530 }
531 self.run_events(i64::from(budget), false).map_err(|error| {
532 CallError::Runtime(error.diagnostic(&ErrorCtx {
533 instr_src: &self.instr_src,
534 sources: &self.sources,
535 }))
536 })
537 }
538
539 /// Runs the event entry with `budget` and `wait`, answering how many
540 /// handlers ran.
541 fn run_events(&mut self, budget: i64, wait: bool) -> Result<usize, RuntimeError> {
542 let Some(entry) = &self.event_entry else {
543 return Ok(0);
544 };
545 let (start, ret) = (entry.entry, entry.ret_register as usize);
546 self.registers[entry.arg_registers[0] as usize] = Data::int(budget);
547 self.registers[entry.arg_registers[1] as usize] = Data::from(wait);
548 self.execute_raw(start)?;
549 Ok(self.registers[ret].as_int().max(0) as usize)
550 }
551
552 /// Invokes the exported function `name` with `args`, returning its value
553 /// (or [`Value::Null`] for a function that returns nothing).
554 ///
555 /// The call runs the trampoline the compiler emitted for the function at
556 /// build time, against the resident register and heap state, so globals a
557 /// previous call or `main` established remain visible. Arguments are
558 /// checked against the declared parameter types before anything runs.
559 ///
560 /// # Errors
561 ///
562 /// Returns a [`CallError`] if the artifact exports no such function, if the
563 /// arguments disagree with the declared signature, or if the call raises a
564 /// runtime error.
565 pub fn call(&mut self, name: &str, args: &[Value]) -> Result<Value, CallError> {
566 let export = self.run_export(name, args)?;
567 Ok(self.read_register(export.ret_register))
568 }
569
570 /// [`Self::call`], handing back what the function left in each argument it
571 /// was passed by reference.
572 ///
573 /// A list, a map and a struct reach a script function by reference, so
574 /// what the function writes into one is written into the value the call
575 /// passed. Once the call returns, every argument that is one of those is
576 /// replaced with its final value; every other argument is left as it was.
577 /// This is how a host passes data in, lets the script change it, and reads
578 /// the result back in one call.
579 ///
580 /// # Errors
581 ///
582 /// As [`Self::call`]. An argument is only replaced once the call has run
583 /// without an error.
584 pub fn call_in_out(&mut self, name: &str, args: &mut [Value]) -> Result<Value, CallError> {
585 let export = self.run_export(name, args)?;
586 for (arg, ®ister) in args.iter_mut().zip(export.arg_registers.iter()) {
587 if passed_by_reference(arg) {
588 *arg = self.read_register(register);
589 }
590 }
591 Ok(self.read_register(export.ret_register))
592 }
593
594 /// Checks `args` against the export `name`, marshals them into its
595 /// argument registers and runs its trampoline, answering the registers it
596 /// read its arguments from and left its result in.
597 fn run_export(&mut self, name: &str, args: &[Value]) -> Result<ExportRegisters, CallError> {
598 let export = self
599 .exports
600 .get(name)
601 .ok_or_else(|| CallError::UnknownFunction(name.to_owned()))?;
602
603 if export.arg_registers.len() != args.len() {
604 return Err(CallError::ArgCount {
605 function: name.to_owned(),
606 expected: export.arg_registers.len(),
607 found: args.len(),
608 });
609 }
610 for (idx, (arg, declared)) in args.iter().zip(export.arg_types.iter()).enumerate() {
611 if !value_matches_type(arg, declared, &self.structs) {
612 return Err(CallError::ArgType {
613 function: name.to_owned(),
614 index: idx + 1,
615 expected: AttributeTable::new(Vec::new(), &self.structs, &self.enums)
616 .type_name(declared),
617 found: describe_value(arg),
618 });
619 }
620 }
621
622 let entry = export.entry;
623 let registers = ExportRegisters {
624 arg_registers: export.arg_registers.clone(),
625 ret_register: export.ret_register,
626 };
627 marshal_args(
628 args,
629 ®isters.arg_registers,
630 &mut self.registers,
631 &mut self.pools,
632 &self.structs,
633 );
634
635 self.execute_from(entry)?;
636 Ok(registers)
637 }
638
639 /// The value register `register` holds, read back into a host [`Value`].
640 fn read_register(&self, register: u16) -> Value {
641 unmarshal_value(
642 self.registers[register as usize],
643 &self.pools.objs,
644 &self.pools.maps,
645 &self.pools.strings,
646 &self.structs,
647 &self.enums,
648 )
649 }
650
651 /// Every attribute the program's scripts wrote, with the struct and enum
652 /// tables the types in it refer to.
653 #[must_use]
654 pub fn attributes(&self) -> AttributeTable {
655 AttributeTable::new(self.attributes.clone(), &self.structs, &self.enums)
656 }
657
658 /// Does up to about `budget` units of garbage collection while the
659 /// program is idle, and answers whether no collection work is left.
660 ///
661 /// Call it between calls into the program, where the host would otherwise
662 /// wait, such as between frames. It carries on a collection already under
663 /// way, or begins one when the heap has grown enough since the last; on a
664 /// heap that has not, it does nothing and answers `true`. A unit is about
665 /// one object traced or one freed slot, never a length of time, so the
666 /// same calls do the same work on every machine. `collect(u32::MAX)` runs
667 /// a whole collection. Beginning a collection reads every root at once
668 /// whatever the budget.
669 ///
670 /// Once a host has called this, allocations leave more of the work to it
671 /// and begin a collection themselves only when the heap has grown further.
672 pub fn collect(&mut self, budget: u32) -> bool {
673 self.pools.collect(&self.registers, budget)
674 }
675
676 /// What the collector has done over this program's heap, and how large
677 /// the heap is. See [`GcStats`].
678 #[must_use]
679 pub fn gc_stats(&self) -> GcStats {
680 self.pools.gc_stats()
681 }
682
683 /// The names of every function this artifact exports, in no particular
684 /// order.
685 pub fn exports(&self) -> impl Iterator<Item = &str> {
686 self.exports.keys().map(String::as_str)
687 }
688
689 /// Runs the VM against the resident state starting at instruction `start`,
690 /// capturing any runtime error as a [`Diagnostic`].
691 fn execute_from(&mut self, start: usize) -> Result<(), Diagnostic> {
692 self.execute_raw(start).map_err(|error| {
693 error.diagnostic(&ErrorCtx {
694 instr_src: &self.instr_src,
695 sources: &self.sources,
696 })
697 })
698 }
699
700 /// Runs the VM against the resident state starting at instruction `start`.
701 fn execute_raw(&mut self, start: usize) -> Result<(), RuntimeError> {
702 let err_ctx = ErrorCtx {
703 instr_src: &self.instr_src,
704 sources: &self.sources,
705 };
706
707 // Move the register file out so the VM can borrow it mutably, then
708 // reclaim it (register state must persist across calls).
709 let mut register_file = RegisterFile(std::mem::take(&mut self.registers));
710
711 // An error comes back as a value, so a call sets up no unwind and
712 // leaves the process panic hook alone.
713 let result = vm::execute(
714 &self.instructions,
715 &mut register_file,
716 &mut self.pools,
717 &err_ctx,
718 &self.callsite_registers,
719 &self.dyn_lib_fns,
720 &self.structs,
721 &self.enums,
722 self.allocated_arg_count,
723 self.allocated_call_depth,
724 &self.host_sigs,
725 &self.host_dispatch,
726 start,
727 self.native.as_ref(),
728 );
729
730 self.registers = std::mem::take(&mut register_file.0);
731 result
732 }
733}
734
735/// Why a [`RuntimeProgram::call`] did not produce a value.
736#[derive(Debug)]
737pub enum CallError {
738 /// The artifact exports no function under this name.
739 UnknownFunction(String),
740 /// The call passed a different number of arguments than the function
741 /// declares.
742 ArgCount {
743 function: String,
744 expected: usize,
745 found: usize,
746 },
747 /// An argument does not match the parameter type it was passed for.
748 /// `index` is 1-based.
749 ArgType {
750 function: String,
751 index: usize,
752 expected: String,
753 found: String,
754 },
755 /// The call ran and raised a runtime error.
756 Runtime(Diagnostic),
757}
758
759impl From<Diagnostic> for CallError {
760 fn from(diagnostic: Diagnostic) -> Self {
761 Self::Runtime(diagnostic)
762 }
763}
764
765impl std::fmt::Display for CallError {
766 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
767 match self {
768 Self::UnknownFunction(name) => write!(
769 f,
770 "this artifact exports no function named '{name}'; only functions defined in the file it was built from, with every parameter annotated, are callable by name"
771 ),
772 Self::ArgCount {
773 function,
774 expected,
775 found,
776 } => write!(
777 f,
778 "'{function}' takes {expected} argument(s) but the call passed {found}"
779 ),
780 Self::ArgType {
781 function,
782 index,
783 expected,
784 found,
785 } => write!(
786 f,
787 "argument {index} of '{function}' is declared '{expected}' but the call passed a {found}"
788 ),
789 Self::Runtime(diagnostic) => f.write_str(&diagnostic.message),
790 }
791 }
792}
793
794impl std::error::Error for CallError {}
795
796impl RuntimeProgram {
797 /// Reconstructs a runnable program from a decoded [`ProgramImage`].
798 ///
799 /// This is where a `.cdlb`'s dynamic-library and host recipes are turned
800 /// back into live bindings: each `dylib` symbol is re-resolved through the
801 /// OS loader by logical name (never from embedded bytes), and each `host`
802 /// function is bound to the closure `hosts` registered under the same name,
803 /// with its signature checked against the recorded declaration.
804 ///
805 /// # Errors
806 ///
807 /// Returns [`LoadError`] if a referenced library cannot be opened, a symbol
808 /// cannot be resolved, or a declared `host` function is unregistered or
809 /// bound to a closure of a different shape.
810 fn from_image(img: ProgramImage, hosts: &HostRegistry) -> Result<Self, LoadError> {
811 let objs: ObjectPool = Pool(
812 img.objs
813 .into_iter()
814 .map(|v| {
815 v.into_iter()
816 .map(|(boxed, int)| Data::from_words(boxed, int))
817 .collect()
818 })
819 .collect(),
820 );
821 let maps: MapPool = Pool(
822 img.maps
823 .into_iter()
824 .map(|pairs| {
825 let mut m = CandelaMap::default();
826 for ((k_boxed, k_int), (v_boxed, v_int)) in pairs {
827 m.insert(
828 Data::from_words(k_boxed, k_int),
829 Data::from_words(v_boxed, v_int),
830 );
831 }
832 m
833 })
834 .collect(),
835 );
836 let strings = StringPool::from_strings(img.strings);
837
838 let structs = structs_from_images(img.structs);
839 let enums = enums_from_images(img.enums);
840
841 // `host` functions need a host-supplied closure to dispatch to. Bind
842 // them all before anything runs, so an unbound call is impossible once
843 // the program is loaded.
844 let host_sigs: Vec<HostFnSig> = img.host_fns.iter().map(HostFnSig::from).collect();
845 let host_dispatch = hosts.bind(&host_sigs, &structs)?;
846
847 let dyn_lib_fns = resolve_dyn_lib_fns(&img.dyn_lib_fns, &structs)?;
848
849 let exports = img
850 .exports
851 .into_iter()
852 .map(|e| (e.name.clone(), Export::from(e)))
853 .collect();
854 let event_entry = img.event_entry.map(Export::from);
855
856 Ok(Self {
857 instructions: img.instructions,
858 registers: img
859 .registers
860 .into_iter()
861 .map(|(boxed, int)| Data::from_words(boxed, int))
862 .collect(),
863 pools: Pools::new(objs, maps, strings),
864 instr_src: img
865 .instr_src
866 .into_iter()
867 .map(|s| InstrSrc {
868 instr: s.instr,
869 span: s.span,
870 file_id: s.file_id,
871 })
872 .collect(),
873 callsite_registers: img.callsite_registers,
874 dyn_lib_fns,
875 host_sigs,
876 host_dispatch,
877 exports,
878 event_entry,
879 structs,
880 enums,
881 sources: img
882 .sources
883 .into_iter()
884 .map(|s| Source {
885 filename: SmolStr::from(s.filename),
886 contents: s.contents,
887 })
888 .collect(),
889 allocated_arg_count: img.allocated_arg_count as usize,
890 allocated_call_depth: img.allocated_call_depth as usize,
891 native: None,
892 attributes: img.attributes,
893 })
894 }
895}
896
897/// The runtime struct table a `.cdlb` recorded.
898fn structs_from_images(images: Vec<StructImage>) -> Vec<Struct> {
899 images
900 .into_iter()
901 .map(|s| Struct {
902 name: SmolStr::from(s.name),
903 fields: s
904 .fields
905 .into_iter()
906 .map(|(n, t, sp)| (SmolStr::from(n), t, sp))
907 .collect::<Vec<_>>()
908 .into_boxed_slice(),
909 id: s.id,
910 name_span: s.name_span,
911 })
912 .collect()
913}
914
915/// The runtime enum table a `.cdlb` recorded.
916fn enums_from_images(images: Vec<EnumImage>) -> Vec<EnumType> {
917 images
918 .into_iter()
919 .map(|e| EnumType {
920 name: SmolStr::from(e.name),
921 variants: e
922 .variants
923 .into_iter()
924 .map(|v| EnumVariant {
925 name: SmolStr::from(v.name),
926 payload: v.payload.into_boxed_slice(),
927 name_span: v.name_span,
928 })
929 .collect::<Vec<_>>()
930 .into_boxed_slice(),
931 id: e.id,
932 name_span: e.name_span,
933 })
934 .collect()
935}
936
937/// Re-opens each referenced dynamic library through the OS loader and rebuilds a
938/// live [`DynamicLibFn`] (libffi CIF + code pointer) for every recorded symbol.
939///
940/// Libraries are opened once and shared across their symbols. The logical name
941/// is mapped to this platform's filename convention via
942/// [`resolve_library_filename`], so an artifact built on one OS resolves the
943/// right file on another. The directories a host named with
944/// [`set_dylib_dirs`](crate::rt::set_dylib_dirs) are searched before the
945/// loader's own paths, which is how an application ships its libraries in a
946/// directory of its own. A recipe the standard library owns is searched for
947/// under the toolchain's `libs` directory as well, so an artifact that imports
948/// `std/math` runs from any working directory.
949#[cfg(not(target_arch = "wasm32"))]
950fn resolve_dyn_lib_fns(
951 recipes: &[DynLibFnImage],
952 structs: &[Struct],
953) -> Result<Vec<DynamicLibFn>, LoadError> {
954 use crate::rt::open_library;
955 use libloading::Library;
956 use std::rc::Rc;
957
958 // Keyed by origin as well as filename: the same relative path means one
959 // file under the toolchain's `libs` and another beside the program.
960 let mut libs: HashMap<(LibraryOrigin, String), Rc<Library>> = HashMap::default();
961 let mut out: Vec<DynamicLibFn> = Vec::with_capacity(recipes.len());
962
963 for recipe in recipes {
964 let filename = resolve_library_filename(&recipe.library, TargetOs::CURRENT);
965 let key = (recipe.origin, filename.clone());
966 let lib = if let Some(lib) = libs.get(&key) {
967 Rc::clone(lib)
968 } else {
969 let lib = Rc::new(open_library(&filename, recipe.origin).map_err(|e| {
970 LoadError::LibraryOpen {
971 spec: recipe.library.clone(),
972 filename: filename.clone(),
973 message: e,
974 }
975 })?);
976 // A library that posts events gets the runtime's table before
977 // the program can call into it.
978 crate::events::init_library(&lib);
979 libs.insert(key, Rc::clone(&lib));
980 lib
981 };
982
983 let ptr = unsafe {
984 let sym = lib
985 .get::<*const ()>(recipe.symbol.as_bytes())
986 .map_err(|_| LoadError::SymbolNotFound {
987 library: recipe.library.clone(),
988 symbol: recipe.symbol.clone(),
989 })?;
990 libffi::middle::CodePtr(sym.try_as_raw_ptr().ok_or_else(|| {
991 LoadError::SymbolNotFound {
992 library: recipe.library.clone(),
993 symbol: recipe.symbol.clone(),
994 }
995 })?)
996 };
997
998 // types[0] is the return type; types[1..] are the argument types.
999 let (return_type, arg_types) = recipe.types.split_first().unwrap_or((&DataType::Null, &[]));
1000 let cif = libffi::middle::Cif::new(
1001 arg_types.iter().map(|t| t.to_c_type(structs)),
1002 return_type.to_c_type(structs),
1003 );
1004
1005 out.push(DynamicLibFn {
1006 types: recipe.types.clone().into_boxed_slice(),
1007 library: SmolStr::from(recipe.library.as_str()),
1008 origin: recipe.origin,
1009 symbol: SmolStr::from(recipe.symbol.as_str()),
1010 _lib: lib,
1011 ptr,
1012 cif,
1013 });
1014 }
1015
1016 Ok(out)
1017}
1018
1019/// On targets without the FFI backend (wasm) no library loads. A binding the
1020/// standard library owns resolves to the runtime's own function for it; any
1021/// other refuses the load rather than silently dropping the binding.
1022#[cfg(target_arch = "wasm32")]
1023fn resolve_dyn_lib_fns(
1024 recipes: &[DynLibFnImage],
1025 _structs: &[Struct],
1026) -> Result<Vec<DynamicLibFn>, LoadError> {
1027 recipes
1028 .iter()
1029 .map(|recipe| {
1030 let intrinsic = match recipe.origin {
1031 LibraryOrigin::StandardLibrary => {
1032 crate::intrinsics::lookup(&recipe.library, &recipe.symbol)
1033 }
1034 LibraryOrigin::Program => None,
1035 };
1036 let Some(intrinsic) = intrinsic else {
1037 return Err(LoadError::LibraryOpen {
1038 spec: recipe.library.clone(),
1039 filename: recipe.library.clone(),
1040 message: String::from("dynamic libraries are not supported on this target"),
1041 });
1042 };
1043 Ok(DynamicLibFn {
1044 types: recipe.types.clone().into_boxed_slice(),
1045 library: SmolStr::from(recipe.library.as_str()),
1046 origin: recipe.origin,
1047 symbol: SmolStr::from(recipe.symbol.as_str()),
1048 intrinsic,
1049 })
1050 })
1051 .collect()
1052}
1053
1054/// Why a `.cdlb` artifact could not be loaded.
1055#[derive(Debug)]
1056pub enum LoadError {
1057 /// The magic header is missing (not a `.cdlb` file).
1058 BadMagic,
1059 /// The file is shorter than the fixed header.
1060 Truncated,
1061 /// The artifact's format version is not understood by this runtime.
1062 UnsupportedVersion(u8),
1063 /// The `postcard` body failed to decode.
1064 Decode(postcard::Error),
1065 /// A referenced dynamic library could not be opened by the OS loader.
1066 LibraryOpen {
1067 /// Logical name/path as written in the source.
1068 spec: String,
1069 /// The platform filename it mapped to at load.
1070 filename: String,
1071 /// The loader's error text.
1072 message: String,
1073 },
1074 /// A symbol declared by a `dylib` block was not found in its library.
1075 SymbolNotFound { library: String, symbol: String },
1076 /// The artifact's `host` functions could not be bound to the registry the
1077 /// load was given.
1078 HostBinding(HostBindError),
1079}
1080
1081impl From<HostBindError> for LoadError {
1082 fn from(error: HostBindError) -> Self {
1083 Self::HostBinding(error)
1084 }
1085}
1086
1087impl std::fmt::Display for LoadError {
1088 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1089 match self {
1090 Self::BadMagic => write!(f, "not a candela bytecode artifact (bad magic header)"),
1091 Self::Truncated => write!(f, "truncated candela bytecode artifact"),
1092 Self::UnsupportedVersion(v) => write!(
1093 f,
1094 "unsupported .cdlb format version {v} (this runtime understands version {FORMAT_VERSION})"
1095 ),
1096 Self::Decode(e) => write!(f, "failed to decode .cdlb body: {e}"),
1097 Self::LibraryOpen {
1098 spec,
1099 filename,
1100 message,
1101 } => write!(
1102 f,
1103 "cannot open dynamic library '{spec}' (resolved to '{filename}') referenced by this artifact: {message}"
1104 ),
1105 Self::SymbolNotFound { library, symbol } => write!(
1106 f,
1107 "dynamic library '{library}' does not export the symbol '{symbol}' this artifact needs"
1108 ),
1109 Self::HostBinding(error) => write!(f, "{error}"),
1110 }
1111 }
1112}
1113
1114impl std::error::Error for LoadError {}
1115
1116/// Loads a `.cdlb` bytecode artifact into a runnable [`RuntimeProgram`].
1117///
1118/// `hosts` supplies the Rust closures the artifact's `host` blocks bind to.
1119/// Pass an empty [`HostRegistry`] for a program that declares none; a program
1120/// that declares one it does not cover fails to load, naming what is missing.
1121///
1122/// # Errors
1123///
1124/// Returns a [`LoadError`] if the magic/version header is wrong, the body fails
1125/// to decode, a dynamic library cannot be re-bound, or a `host` function cannot
1126/// be bound to the registry.
1127pub fn load_program(bytes: &[u8], hosts: &HostRegistry) -> Result<RuntimeProgram, LoadError> {
1128 if bytes.len() < 5 {
1129 return Err(LoadError::Truncated);
1130 }
1131 if bytes[0..4] != MAGIC {
1132 return Err(LoadError::BadMagic);
1133 }
1134 let version = bytes[4];
1135 if version != FORMAT_VERSION {
1136 return Err(LoadError::UnsupportedVersion(version));
1137 }
1138 // The function table follows the image, and the VM has no use for it.
1139 let (mut img, _table): (ProgramImage, &[u8]) =
1140 postcard::take_from_bytes(&bytes[5..]).map_err(LoadError::Decode)?;
1141 let sections = std::mem::take(&mut img.native);
1142 #[allow(unused_mut)]
1143 let mut program = RuntimeProgram::from_image(img, hosts)?;
1144 program.load_native(§ions);
1145 Ok(program)
1146}
1147
1148/// Serializes a [`ProgramImage`] to `.cdlb` bytes (magic + version + body),
1149/// followed by the function table when there is one.
1150///
1151/// # Errors
1152///
1153/// Returns the serialization error as a string if the `postcard` body cannot be
1154/// encoded.
1155pub fn serialize_image(
1156 image: &ProgramImage,
1157 functions: Option<&FunctionTable>,
1158) -> Result<Vec<u8>, String> {
1159 let mut bytes = Vec::new();
1160 bytes.extend_from_slice(&MAGIC);
1161 bytes.push(FORMAT_VERSION);
1162 let body = postcard::to_allocvec(image).map_err(|e| e.to_string())?;
1163 bytes.extend_from_slice(&body);
1164 if let Some(functions) = functions {
1165 let table = postcard::to_allocvec(functions).map_err(|e| e.to_string())?;
1166 bytes.extend_from_slice(&table);
1167 }
1168 Ok(bytes)
1169}
1170
1171/// Reads a `.cdlb` back into its image and the function table that follows
1172/// it, for a tool that works on the program rather than runs it. The table
1173/// is `None` for an artifact written without one.
1174///
1175/// # Errors
1176///
1177/// Returns a [`LoadError`] if the header is wrong or either part fails to
1178/// decode.
1179pub fn read_artifact(bytes: &[u8]) -> Result<(ProgramImage, Option<FunctionTable>), LoadError> {
1180 if bytes.len() < 5 {
1181 return Err(LoadError::Truncated);
1182 }
1183 if bytes[0..4] != MAGIC {
1184 return Err(LoadError::BadMagic);
1185 }
1186 if bytes[4] != FORMAT_VERSION {
1187 return Err(LoadError::UnsupportedVersion(bytes[4]));
1188 }
1189 let (image, rest): (ProgramImage, &[u8]) =
1190 postcard::take_from_bytes(&bytes[5..]).map_err(LoadError::Decode)?;
1191 if rest.is_empty() {
1192 return Ok((image, None));
1193 }
1194 let table: FunctionTable = postcard::from_bytes(rest).map_err(LoadError::Decode)?;
1195 Ok((image, Some(table)))
1196}
1197
1198/// Reads the attribute table out of a `.cdlb` without loading the program:
1199/// no library is opened and no `host` function is bound, so a build tool or
1200/// an editor lists what a program declares with nothing registered.
1201///
1202/// # Errors
1203///
1204/// Returns a [`LoadError`] if the header is wrong or the image fails to
1205/// decode.
1206pub fn read_attributes(bytes: &[u8]) -> Result<AttributeTable, LoadError> {
1207 let (image, _) = read_artifact(bytes)?;
1208 let structs = structs_from_images(image.structs);
1209 let enums = enums_from_images(image.enums);
1210 Ok(AttributeTable::new(image.attributes, &structs, &enums))
1211}