Struct DataCap 

pub struct DataCap {
    pub backing: Arc<PageSlab>,
    pub overlay: BTreeMap<u32, PageSlot>,
}

Data cap: an Arc-shared immutable PageSlab backing plus a copy-on-write overlay of modified pages. The cap identity (when flushed) is the flat size-scaled { size, pages } merkle (see the module docs).

Fields

backing: Arc<PageSlab>

Immutable backing, shared across a MGMT_COPY lineage by Arc.

overlay: BTreeMap<u32, PageSlot>

Copy-on-write modified pages (absolute page index → page). Empty for a clean / settled cap. A present entry shadows the backing; zero-writes are stored explicitly (a present PageSlot::Loaded) so they shadow a possibly-nonzero backing page.

Implementations

impl DataCap

pub fn empty() -> Self

An empty DataCap: logical size 0, no pages, no overlay.

pub fn content_len(&self) -> u64

Total logical content size in bytes (always a PAGE_SIZE multiple).

pub fn page_count(&self) -> usize

Number of logical pages.

pub fn is_dirty(&self, i: usize) -> bool

Is page i overlaid (CoW’d)? A page is dirty iff it is present in the overlay (Empty slots / absent entries are clean — defer to the backing).

pub fn page_slot(&self, i: usize) -> &PageSlot

Borrow the effective page slot at absolute page index i: the overlay page if dirty, else the backing page. Both engines resolve a page’s physical address from the returned PageSlot::Loaded slab.

pub fn page_at(&self, off: u64) -> PageResolution<'_>

Resolve the effective page containing byte offset off (need not be page-aligned). Both engines call this so their materialized page contents are identical.

pub fn copy_into(&self, start: u64, out: &mut [u8])

Copy out.len() logical bytes starting at byte offset start into out (effective content), fully defining every byte: materialized pages are copied; Zero pages read as zero.

Panics

Panics on a PageResolution::Missing page — elided content known only by hash is not zero, and the recompiler hard-faults on it; silently zero-filling would fork consensus. V1 never mints Missing.

pub fn put_page(&mut self, off: u64, content: &[u8])

Overwrite the backing page containing absolute offset off with up to PAGE_SIZE content bytes (zero-padded tail), canonically. This is the construction / settle primitive (it mutates the backing via Arc::make_mut, so it is O(slab) on a shared backing — only use it while building a fresh cap). Copy-on-write during execution goes through write_page (the overlay) instead.

Panics (debug) if off >= self.content_len().

pub fn write_page(&mut self, off: u64, content: &[u8])

Copy-on-write the overlay page containing absolute offset off with up to PAGE_SIZE content bytes (zero-padded tail). The page is stored explicitly as a present Loaded slab — even all-zero content — so it shadows the backing. This is the execution write boundary.

Panics (debug) if off >= self.content_len().

pub fn insert_overlay_page(&mut self, p: u32, slot: PageSlot)

Insert an already-built overlay page slot at absolute page index p (move, no copy). The slab is page-aligned by construction; used by the engines’ CoW path to hand a freshly-written page to the cap directly.

pub fn place_shared(&mut self, dst_off: u64, src: &DataCap)

Place every effective page of src into this cap’s backing starting at absolute byte offset dst_off (page-aligned): backing page dst_off/PAGE_SIZE + i becomes a clone of src.page_slot(i) — an Arc refcount bump, not a byte copy. Pages beyond this cap’s extent are dropped (clamped, mirroring the interpreter’s off < extent fold guard).

This is the page-sharing instance-memory composer: a fresh Instance mem built by placing an Image’s mapped Cap::Data sources shares those sources’ physical pages, so N sub-VMs spawned from one Image all map the same read-only frames and each CoWs (into its overlay) only the pages it writes — the shared backing is never mutated. Effective bytes are identical to the copying put_page fold; only the allocation is shared.

pub fn flush(&self) -> DataCap

Fold the overlay into a fresh, clean (overlay-empty) DataCap whose hash_tree_root is defined. Clones the backing and folds every overlaid page in via the canonical backing CoW. This is the settle / content- address primitive (it replaces the old DataViewCap::settle).

pub fn from_bytes(content: &[u8]) -> Self

Build a DataCap from contiguous content, sized to the next page boundary (at least one page). All-zero pages become PageSlot::Empty.

pub fn from_bytes_sized(content: &[u8], target_size: u64) -> Self

Build a DataCap from content with a logical size of at least target_size (rounded up to a page boundary, minimum one page). content fills the low bytes; the remainder is zero (sparse). The cap is clean (empty overlay).

pub fn from_sparse_pages<'a>( size: u64, pages: impl IntoIterator<Item = (u32, &'a [u8])>, ) -> Self

Build a clean (overlay-free) DataCap from sparse named pages over a logical size. See PageSlab::from_sparse_pages. This is the decode target for crate::image::DataDesc::to_data_cap; the result is byte- and hash-identical to a contiguous Self::from_bytes_sized of equivalent logical content.

Trait Implementations

impl Archive for DataCap

where Arc<PageSlab>: Archive, BTreeMap<u32, PageSlot>: Archive,

const COPY_OPTIMIZATION: CopyOptimization<Self>

An optimization flag that allows the bytes of this type to be copied directly to a writer instead of calling serialize.

type Archived = ArchivedDataCap

The archived representation of this type.

type Resolver = DataCapResolver

The resolver for this type. It must contain all the additional information from serializing needed to make the archived type from the normal type.

fn resolve(&self, resolver: Self::Resolver, out: Place<Self::Archived>)

Creates the archived version of this value at the given position and writes it to the given output.

impl Clone for DataCap

fn clone(&self) -> DataCap

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DataCap

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<__D: Fallible + ?Sized> Deserialize<DataCap, __D> for Archived<DataCap>

where Arc<PageSlab>: Archive, <Arc<PageSlab> as Archive>::Archived: Deserialize<Arc<PageSlab>, __D>, BTreeMap<u32, PageSlot>: Archive, <BTreeMap<u32, PageSlot> as Archive>::Archived: Deserialize<BTreeMap<u32, PageSlot>, __D>,

fn deserialize( &self, deserializer: &mut __D, ) -> Result<DataCap, <__D as Fallible>::Error>

Deserializes using the given deserializer

impl HashTreeRoot for DataCap

fn hash_tree_root<D: Digest<OutputSize = U32>>(&self) -> [u8; 32]

Compute the hash tree root using D as the underlying hash.

impl<__S: Fallible + ?Sized> Serialize<__S> for DataCap

where Arc<PageSlab>: Serialize<__S>, BTreeMap<u32, PageSlot>: Serialize<__S>,

fn serialize( &self, serializer: &mut __S, ) -> Result<<Self as Archive>::Resolver, <__S as Fallible>::Error>

Writes the dependencies for the object and returns a resolver that can create the archived type.