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
evalin 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§
- Control
File - A Plan 9-style ctl file: writing bytes invokes a caller-supplied async handler, whose result is latched and served on the next read.
- DevFile
State - Per-fid state for a device file: a byte buffer latched by the last write
(for
ControlFile) or the last read (forFieldFilecaching). - Dynamic
Dir - Helper for the
vars/,defs/,procs/-style directories both shell mounts expose: areaddirthat lists live names and a per-name leaf read (and optional write) sourced from the same backing interpreter. - Field
File - 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
FieldFilewith no setter (read-only field).
Traits§
- Field
Setter - A field file’s write side: either
NoSetter(read-only) or a realFn(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
dataatoffset, returning at most the available remainder (9P read semantics: reading past EOF yields an empty result, not an error).countis accepted for symmetry with [Mount::read] callers but both primitives here return their full latched/rendered buffer fromoffsetonward — callers needing chunked reads should slice further.
Type Aliases§
- DevFuture
- Boxed future returned by device-file callbacks.
Sendoff wasm32 to match [Mount]’s#[async_trait](non-wasm) bound.