vfsi_core/api/
handles.rs

1use super::Result;
2use std::path::Path;
3
4/// Owned handle to one open file instance.
5///
6/// A descriptor is the handle to the instance; this contract does not require
7/// exposing a numeric OS descriptor. [`crate::Fd`] is a backend-assigned numeric
8/// slot, while implementations such as `vfsi_sync::OpenFile` own cleanup.
9///
10/// This is neither an underlying filesystem-object ID nor a protocol
11/// filehandle such as an NFS filehandle. Separate opens of the same object
12/// yield separate instances. Borrowed requests preserve the instance's
13/// lifetime; clients validate connection ownership before dispatch.
14///
15/// Clients validate ownership before I/O and report positional progress.
16/// Standard-I/O adapters manage their own independent cursors. `ReadOp` borrows handles directly; constructing it does no I/O.
17/// A backend must retain ownership of live descriptors through cleanup failures.
18pub trait FileHandle {
19    /// Diagnostic name captured at open; not current path or object identity.
20    fn path(&self) -> &Path;
21    /// Close without surrendering cleanup ownership on failure. After an
22    /// ambiguous failure, reconcile/close rather than resume ordinary I/O.
23    fn try_close(&mut self) -> Result<()>;
24    /// Local close ownership only, not proof of remote liveness after failure.
25    fn is_closed(&self) -> bool;
26    /// Consuming close: on failure the handle is lost and Drop retries cleanup
27    /// best-effort on a later operation or cleanup drain. Prefer `try_close` when
28    /// cleanup failures need reconciliation.
29    fn close(self) -> Result<()>
30    where
31        Self: Sized;
32}
33
34/// Owned directory retaining the opened object's identity after rename or path
35/// replacement. Paths are diagnostic only; clients validate ownership and live
36/// state before handle-rooted operations. Failed `try_close` retains cleanup ownership.
37pub trait DirHandle {
38    /// Diagnostic name captured at open, not current path or identity.
39    fn path(&self) -> &Path;
40    /// Close while retaining cleanup ownership on failure.
41    fn try_close(&mut self) -> Result<()>;
42    /// Local close ownership, not proof of remote liveness after failure.
43    fn is_closed(&self) -> bool;
44    /// Consuming close; on failure Drop queues best-effort cleanup.
45    fn close(self) -> Result<()>
46    where
47        Self: Sized;
48}
vfsi_core/api/handles.rs

vfsi_core/api/
handles.rs
