Skip to main content

Module devfile

Module devfile 

Source
Expand description

Reusable synthetic-file primitives for hand-built [Mount] implementations.

hyprstream-workers-tcl and hyprstream-workers-python (and future language-shell crates) each hand-roll the same two shapes:

  • a ctl file: write triggers an action, the next read returns the latched result (the Plan 9 ctl-file convention — see eval in both crates’ mounts).
  • a field file: a scalar read (optionally write) backed by live interpreter state (vars/<name>, defs/<name>, procs/<name>).

This module factors both into reusable, Send + Sync primitives so new language/device mounts don’t need to re-derive the write→latch→read pattern (or its hazards — see the unsafe *mut cast hyprstream-workers-tcl used before this module existed) by hand. Modeled after Wanix’s ControlFile / FieldFile devices, adapted to this crate’s async [Mount] trait and Box<dyn Any + Send + Sync> [Fid].

§Shape

ControlFile and FieldFile are descriptors: long-lived, held by the owning Mount (typically behind an Arc or directly by value), and they hold the caller-supplied async callback(s). Per-open state — the write→read latch — lives in DevFileState, a small Fid payload guarded by a std::sync::Mutex (not parking_lot, so this module stays wasm-portable; the lock is only ever held synchronously to clone/replace a Vec<u8>, never across an .await).

Both callback shapes take and return owned bytes (Vec<u8> in, boxed future of Vec<u8>/Result out) rather than borrowing — this sidesteps HRTB lifetime issues with Fn(&[u8]) -> impl Future<..> + '_ trait objects, and mirrors how both existing mounts already shuttle owned String/Vec<u8> across their command channels.

§wasm32 Send-ness

[Mount] is #[async_trait(?Send)] on wasm32 and #[async_trait] (requiring Send futures) elsewhere. The callback future type here is gated the same way: BoxFuture<'static, T> (Send) off wasm32, LocalBoxFuture<'static, T> (no Send bound) on wasm32. Callers building a ControlFile/FieldFile for a native mount must produce Send futures (true today for both hyprstream-workers-tcl and hyprstream-workers-python, which proxy through tokio::sync channels).

Structs§

ControlFile
A Plan 9-style ctl file: writing bytes invokes a caller-supplied async handler, whose result is latched and served on the next read.
DevFileState
Per-fid state for a device file: a byte buffer latched by the last write (for ControlFile) or the last read (for FieldFile caching).
DynamicDir
Helper for the vars/, defs/, procs/-style directories both shell mounts expose: a readdir that lists live names and a per-name leaf read (and optional write) sourced from the same backing interpreter.
FieldFile
A scalar field file: reading runs a caller-supplied async getter; writing (if a setter is supplied) runs a caller-supplied async setter. Used for vars/<name>, defs/<name>, procs/<name>-style leaves.
NoSetter
Marker type for a FieldFile with no setter (read-only field).

Traits§

FieldSetter
A field file’s write side: either NoSetter (read-only) or a real Fn(Vec<u8>) -> DevFuture<'static, Result<(), MountError>> closure. Sealed-by-convention — implemented here and via the blanket impl below; not meant to be implemented by downstream crates.

Functions§

read_from_offset
Slice data at offset, returning at most the available remainder (9P read semantics: reading past EOF yields an empty result, not an error). count is accepted for symmetry with [Mount::read] callers but both primitives here return their full latched/rendered buffer from offset onward — callers needing chunked reads should slice further.

Type Aliases§

DevFuture
Boxed future returned by device-file callbacks. Send off wasm32 to match [Mount]’s #[async_trait] (non-wasm) bound.