zero_copy_include_bytes/
zero_copy_include_bytes.rs

1//! Demonstrate true zero-copy execution of bytecode included from a
2//! file at compile time via `include_bytes!`.
3//!
4//! The `include_bytes!` macro returns `&'static [u8; N]` whose alignment
5//! is one byte. The zero-copy execution path requires the rkyv body to
6//! be at an 8-byte-aligned address within the slice. The wire format
7//! places the body at offset 16, so 8-byte body alignment follows from
8//! 8-byte alignment of the slice base. The `repr(C, align(16))`
9//! wrapper around the included array forces 16-byte alignment of the
10//! base, which satisfies the 8-byte body alignment by construction.
11//!
12//! With the alignment in place, `unsafe Vm::view_bytes_zero_copy`
13//! borrows the static slice directly. The runtime runs the program
14//! against `&ArchivedModule` read from the static buffer with no
15//! owned `Module` materialized. This is the embedded distribution
16//! pattern where compiled bytecode lives in `.rodata` and the runtime
17//! executes it in place.
18//!
19//! Source for the included bytecode is in
20//! `examples/zero_copy_demo.kel`. To regenerate the binary after a
21//! wire format change, run:
22//!
23//!     cargo run --example regenerate_zero_copy_bytecode
24//!
25//! Run this example with:
26//!
27//!     cargo run --example zero_copy_include_bytes
28
29use keleusma::{Value, vm::Vm, vm::VmState};
30
31/// Length of the included bytecode binary. Hardcoded to match the
32/// file size. If the wire format changes and the file size changes,
33/// regenerate the binary and update this constant.
34const BYTECODE_LEN: usize = 268;
35
36/// Align the included byte array to 16 bytes so the rkyv body at
37/// offset 16 is 8-byte aligned. The body alignment is required by
38/// the zero-copy execution path.
39#[repr(C, align(16))]
40struct AlignedBytecode([u8; BYTECODE_LEN]);
41
42/// Bytecode loaded at compile time from a binary fixture compiled
43/// from `examples/zero_copy_demo.kel`. The wrapper struct controls
44/// alignment.
45static BYTECODE: AlignedBytecode = AlignedBytecode(*include_bytes!("zero_copy_demo.kel.bin"));
46
47fn main() {
48    // Construct a VM that borrows the bytecode buffer directly. No
49    // body copy and no `Module` materialization. The VM lifetime is
50    // tied to the static buffer's `'static` lifetime.
51    //
52    // SAFETY. The bytecode was produced by the trusted Keleusma
53    // compiler in `regenerate_zero_copy_bytecode` and was previously
54    // verified at that step. The host attests through the unsafe
55    // marker that the wire format and structural invariants hold.
56    let arena = keleusma::Arena::with_capacity(64 * 1024);
57    let mut vm: Vm<'static, '_> =
58        unsafe { Vm::view_bytes_zero_copy(&BYTECODE.0, &arena).expect("framing valid") };
59
60    println!("buffer len {} bytes", BYTECODE.0.len());
61    println!("buffer base address 0x{:x}", BYTECODE.0.as_ptr() as usize);
62    println!(
63        "body offset 16 address 0x{:x} (expected 8-byte alignment)",
64        BYTECODE.0.as_ptr() as usize + 16
65    );
66
67    match vm.call(&[]) {
68        Ok(VmState::Finished(Value::Int(v))) => {
69            println!("program returned {}", v);
70            assert_eq!(v, 42);
71        }
72        Ok(other) => panic!("unexpected state {:?}", other),
73        Err(e) => panic!("execution error {:?}", e),
74    }
75
76    println!("zero-copy execution succeeded");
77}
zero_copy_include_bytes/zero_copy_include_bytes.rs

zero_copy_include_bytes/
zero_copy_include_bytes.rs
