Skip to main content

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}