vihaco_module/loader.rs
1// SPDX-FileCopyrightText: 2026 The vihaco Authors
2// SPDX-License-Identifier: MIT
3
4//! Program-construction capabilities and legacy section-loading hooks.
5//!
6//! With `program-image-execution`, callers construct images explicitly and the
7//! section-loading hooks are unavailable. Lowering capabilities remain available
8//! in both feature configurations.
9
10#[cfg(not(feature = "program-image-execution"))]
11use vihaco_bytecode::{BytecodeSectionView, SSTSectionView};
12
13pub use crate::lowering::{InternedStrings, MetadataLoweringContext};
14
15/// Allow a machine to load one bytecode section.
16///
17/// Sections form a flat table; pick one with [`BytecodeFile::section`] and pass
18/// its view here. Return program data to an outer owner rather than storing it
19/// inside Dispatch. Loaders that only mutate their receiver use
20/// `type Output = ();`.
21///
22/// Loading is not transactional. On error, no output is returned, but earlier
23/// mutations to this loader are retained.
24///
25/// [`BytecodeFile::section`]: vihaco_bytecode::BytecodeFile::section
26#[cfg(not(feature = "program-image-execution"))]
27pub trait LoadBytecodeSection<C> {
28 /// The artifact produced for this section, or `()` for a loader that stores it.
29 type Output;
30
31 fn load_bytecode_section<'bc>(
32 &mut self,
33 section: BytecodeSectionView<'bc, C>,
34 ) -> eyre::Result<Self::Output>;
35}
36
37/// Allow a machine to load one SST section.
38///
39/// Sections form a flat list; pick one with [`SSTFile::section`] and pass its
40/// view here. Return program data to an outer owner rather than storing it
41/// inside Dispatch. Loaders that only mutate their receiver use
42/// `type Output = ();`.
43///
44/// Loading is not transactional. On error, no output is returned, but earlier
45/// mutations to this loader are retained.
46///
47/// [`SSTFile::section`]: vihaco_bytecode::SSTFile::section
48#[cfg(not(feature = "program-image-execution"))]
49pub trait LoadSSTSection<C> {
50 /// The artifact produced for this section, or `()` for a loader that stores it.
51 type Output;
52
53 fn load_sst_section<'bc>(
54 &mut self,
55 section: SSTSectionView<'bc, C>,
56 ) -> eyre::Result<Self::Output>;
57
58 /// Lower a section's parsed instructions after preparing loader capabilities.
59 ///
60 /// Call this from `load_sst_section` before storing executable code.
61 /// For a generated composite syntax aggregate, the single `Lower<Self>`
62 /// bound requires every included instruction's loader capabilities. An
63 /// error returns no partial instruction vector.
64 fn lower_instructions<I>(
65 &mut self,
66 instructions: impl IntoIterator<Item = I>,
67 ) -> eyre::Result<Vec<I::Runtime>>
68 where
69 I: vihaco_abi::Lower<Self>,
70 {
71 instructions
72 .into_iter()
73 .map(|instruction| instruction.lower(self))
74 .collect()
75 }
76}