Struct Handles 

pub struct Handles { /* private fields */ }

A job’s open files.

Scoping this to a single job is a security property rather than tidiness. Because the table lives and dies with one job, a handle from another job names nothing here — which is what lets Handles::slice skip a capability check entirely. The check happened once, at Handles::open, and a handle cannot be forged into a reference to someone else’s data.

Implementations

impl Handles

pub fn open( &mut self, path: &Path, ) -> Result<(u32, u64, MediaKind), HandleError>

Open a file, returning its handle, length, and what the host made of it.

The caller is responsible for having capability-checked path first — this type deliberately knows nothing about capabilities, so that the check lives in exactly one place rather than being half-enforced here.

pub fn insert_bytes(&mut self, bytes: Vec<u8>, kind: MediaKind) -> (u32, u64)

Register bytes the host produced — a rendered page — as a new handle.

pub fn kind(&self, handle: u32) -> Result<MediaKind, HandleError>

What a handle refers to.

pub fn read_all(&mut self, handle: u32) -> Result<Vec<u8>, HandleError>

Every byte behind a handle.

Used for images headed to a vision model, where the whole thing has to be sent. Deliberately host-side only — this is the one place a whole file is materialized, and it never crosses into guest memory.

pub fn slice_bytes( &mut self, handle: u32, offset: u64, len: u64, ) -> Result<(Vec<u8>, u64), HandleError>

Read one window as raw bytes, with no character-boundary handling.

pub fn slice( &mut self, handle: u32, offset: u64, len: u64, ) -> Result<Window, HandleError>

Read one window, truncated to a UTF-8 character boundary.

The truncation is the subtle part, and the reason Window::next_offset exists at all. A caller walking a file picks window sizes with no idea where characters begin, so a naive read splits a multi-byte character at nearly every seam and yields mojibake. Instead the window is cut back to the last complete character and next_offset reports where that landed — so a caller resuming from next_offset, rather than advancing by the length it requested, never observes a split.

Reading past the end is not an error: the window is clamped, because a block asking for a full window at the tail of a file is behaving correctly. Starting past the end is an error, since that indicates the caller has lost track of where it is.

Trait Implementations

impl Default for Handles

fn default() -> Handles

Returns the “default value” for a type.