Skip to main content

store_io_platform/
lib.rs

1//! # store-io-platform
2//!
3//! The boundary between store-io's engine and the operating system.
4//!
5//! Everything above this crate (error classification, barriers, formats,
6//! provisioning, slots) is one shared code path. Below it, each platform
7//! backend (Linux, Windows, macOS) and the deterministic simulator implement
8//! two traits:
9//!
10//! - [`Platform`]: metadata operations (open, create, rename, directory
11//!   flush, lock, allocate, full flush, probe), synchronous and off the hot
12//!   path, plus a factory for per-thread [`Queue`]s.
13//! - [`Queue`]: data operations, completion-shaped. [`Queue::submit`] takes
14//!   an [`IoOp`] that owns its buffer; the buffer comes back in a
15//!   [`Completion`]. A synchronous backend performs the system call inside
16//!   `submit` and completes immediately (no thread hop); the simulator and the
17//!   io_uring / IOCP backends complete later, possibly out of order.
18//!
19//! Backends return raw operating-system codes ([`OsError`]) and never
20//! classify them; the engine decides what an error means (see
21//! `store_io_core::errno`).
22//!
23//! ## Contracts every implementation keeps
24//!
25//! 1. An operation's buffer is not touched by the caller between `submit` and
26//!    the completion that returns it, and is never freed by the backend: it is
27//!    returned in the completion, or in [`Rejected`] if `submit` refuses it.
28//!    Only a failed completion may withhold it, for ever, when the kernel may
29//!    still use it (an asynchronous backend that lost track of its kernel).
30//! 2. A file handle passed in an operation stays open until that operation's
31//!    completion has been reaped. The engine guarantees this by keeping the
32//!    handle alive while operations are in flight; a backend may copy the raw
33//!    descriptor.
34//! 3. `submit` returning `Err` means the operation never reached the kernel or
35//!    device (the media is untouched).
36//! 4. A completion's `result` is the raw outcome: `Ok(n)` bytes transferred,
37//!    which may be short, or `Err(code)`.
38//! 5. No call ever waits with a timeout. [`Queue::wait`] blocks until the
39//!    requested completions exist.
40
41#![deny(warnings)]
42#![forbid(unsafe_code)]
43
44use core::fmt;
45use std::path::Path;
46
47pub use store_io_buf::IoBuf;
48pub use store_io_core::error::OsError;
49pub use store_io_core::evidence::Evidence;
50pub use store_io_core::identity::DeviceIdentity;
51
52/// Result carrying a raw operating-system error.
53pub type RawResult<T> = Result<T, OsError>;
54
55/// A single path component: 1 to 255 bytes, no separators, not `.` or `..`,
56/// no NUL. Validated once at construction so backends never see a path that
57/// could escape its directory.
58#[derive(Clone, PartialEq, Eq, Hash)]
59pub struct FileName(String);
60
61/// The name is not a valid single path component.
62#[derive(Debug, Clone, Copy, PartialEq, Eq)]
63pub struct InvalidFileName;
64
65impl fmt::Display for InvalidFileName {
66    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
67        f.write_str("not a single path component (1-255 bytes, no separators, not . or .., no NUL)")
68    }
69}
70
71impl std::error::Error for InvalidFileName {}
72
73impl FileName {
74    /// Validates a file name.
75    ///
76    /// # Errors
77    ///
78    /// [`InvalidFileName`] for an empty, overlong, `.`/`..`, or separator- or
79    /// NUL-containing name.
80    ///
81    /// # Examples
82    ///
83    /// ```
84    /// use store_io_platform::FileName;
85    /// assert!(FileName::new("store.sio").is_ok());
86    /// assert!(FileName::new("../etc").is_err());
87    /// assert!(FileName::new("a/b").is_err());
88    /// ```
89    pub fn new(name: &str) -> Result<Self, InvalidFileName> {
90        let bad = name.is_empty()
91            || name.len() > 255
92            || name == "."
93            || name == ".."
94            || name
95                .bytes()
96                .any(|b| b == b'/' || b == b'\\' || b == 0 || b == b':');
97        if bad {
98            Err(InvalidFileName)
99        } else {
100            Ok(Self(name.to_owned()))
101        }
102    }
103
104    /// The name.
105    #[must_use]
106    pub fn as_str(&self) -> &str {
107        &self.0
108    }
109}
110
111impl fmt::Debug for FileName {
112    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
113        fmt::Debug::fmt(&self.0, f)
114    }
115}
116
117/// How a file is opened.
118#[derive(Debug, Clone, Copy, PartialEq, Eq)]
119pub enum FileMode {
120    /// Direct (unbuffered) reads and writes.
121    ReadWrite,
122    /// Direct reads only; the handle has no write rights.
123    ReadOnly,
124}
125
126/// How space is released.
127#[derive(Debug, Clone, Copy, PartialEq, Eq)]
128pub enum ReleaseHow {
129    /// Deallocate (punch a hole / mark sparse and zero): space returns to the
130    /// filesystem; the range must be provisioned again before use.
131    Deallocate,
132    /// Trim in place: allocation kept, contents undefined.
133    TrimInPlace,
134}
135
136/// What makes a file the file it is, whatever its name: equal for two
137/// handles, or a handle and a path, exactly when they name one file (POSIX
138/// device and inode; Windows volume serial and file id). Compared, never
139/// interpreted.
140#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
141pub struct FileIdentity {
142    /// The volume or device the file is on.
143    pub volume: u64,
144    /// The file on that volume.
145    pub file: u128,
146}
147
148/// Facts about a byte range of a file.
149#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
150pub struct RangeState {
151    /// Some extent in the range is allocated but unwritten.
152    pub unwritten: store_io_core::evidence::Tri,
153    /// Some extent in the range is shared with another file (reflink).
154    pub shared: store_io_core::evidence::Tri,
155    /// Pages of the range resident in the OS page cache, if knowable.
156    pub cached_pages: Option<u64>,
157    /// Valid data length covers the range (Windows), if knowable.
158    pub valid_data: store_io_core::evidence::Tri,
159}
160
161/// Per-queue configuration.
162#[derive(Debug, Clone, Copy, PartialEq, Eq)]
163pub struct QueueConfig {
164    /// Maximum operations in flight.
165    pub depth: u32,
166    /// A hint that the caller submits several independent operations before
167    /// it waits. A backend that would otherwise run them one by one inside
168    /// `submit` (the Linux synchronous tier) may then run them concurrently
169    /// on worker threads. `false` (the default) keeps every operation on the
170    /// calling thread: the Linux backend then performs each inside `submit`
171    /// on either tier, since a caller that waits for every operation gains
172    /// nothing from a ring (D-104).
173    pub parallel: bool,
174    /// Worker threads for the backend's shared pool, used only if this queue
175    /// is the one that starts it (0 = the backend's default; a backend may
176    /// cap it). A pool already running is never resized; the backend reports
177    /// its size.
178    pub pool_threads: u32,
179    /// Who uses the queue: one thread for its whole life, or any thread that
180    /// borrows it (D-081, D-083). A backend may set the queue up differently
181    /// for each (a thread-owned io_uring ring); others ignore it.
182    pub owner: Owner,
183}
184
185impl Default for QueueConfig {
186    fn default() -> Self {
187        Self {
188            depth: 64,
189            parallel: false,
190            pool_threads: 0,
191            owner: Owner::Shared,
192        }
193    }
194}
195
196/// Who uses a queue ([`QueueConfig::owner`]).
197#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
198#[non_exhaustive]
199pub enum Owner {
200    /// Borrowed by any thread, one at a time (the blocking layers' lanes).
201    #[default]
202    Shared,
203    /// Used by one thread for its whole life (an engine-layer submitter).
204    Thread,
205}
206
207/// Which kernel interface the Linux backend's queues use (D-082). Other
208/// backends have one interface and ignore it.
209#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
210#[non_exhaustive]
211pub enum LinuxTier {
212    /// io_uring where the kernel accepts store-io's rings (probed once per
213    /// process), else the synchronous tier; the reason is reported.
214    #[default]
215    Auto,
216    /// One blocking system call per operation (T3), inline or on the submit
217    /// pool.
218    Sync,
219    /// io_uring rings (store-io's own binding, D-093): operations complete
220    /// asynchronously and never run on kernel worker threads. Refused where
221    /// the kernel refuses the rings.
222    Uring,
223}
224
225/// A kernel interface for I/O ([`IoPath`]).
226#[derive(Debug, Clone, Copy, PartialEq, Eq)]
227#[non_exhaustive]
228pub enum IoInterface {
229    /// Linux io_uring.
230    IoUring,
231    /// One blocking system call per operation (the Linux synchronous tier).
232    Synchronous,
233    /// Windows I/O completion ports.
234    Iocp,
235    /// The deterministic simulator.
236    Simulator,
237    /// Another backend's interface.
238    Other,
239}
240
241impl fmt::Display for IoInterface {
242    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
243        f.write_str(match self {
244            Self::IoUring => "io_uring",
245            Self::Synchronous => "synchronous",
246            Self::Iocp => "IOCP",
247            Self::Simulator => "simulator",
248            Self::Other => "other",
249        })
250    }
251}
252
253/// The kernel interface a platform's queues use, and why (reported in
254/// `StoreReport`).
255#[derive(Debug, Clone, PartialEq, Eq)]
256pub struct IoPath {
257    /// The interface.
258    pub interface: IoInterface,
259    /// Why it was chosen.
260    pub reason: String,
261}
262
263/// Ends a [`Queue::wait`] from another thread (D-083): the queue's current
264/// wait, or its next one if none is in progress, returns, possibly having
265/// added nothing. A wake never creates, loses or repeats a completion.
266pub trait Wake: Send + Sync + Clone + 'static {
267    /// Wakes the queue's waiter. Cheap and never blocks.
268    fn wake(&self);
269}
270
271/// A data operation. Owns its buffer until it completes.
272#[derive(Debug)]
273pub enum IoOp<'a, F> {
274    /// Write the buffer's bytes at `offset`. `dsync` asks for durability at
275    /// completion (Linux `RWF_DSYNC`; FUA in the simulator).
276    Write {
277        /// Target file.
278        file: &'a F,
279        /// Byte offset.
280        offset: u64,
281        /// The data; its length is the transfer size.
282        buf: IoBuf,
283        /// Durable at completion.
284        dsync: bool,
285    },
286    /// Read `buf.len()` bytes at `offset` into the buffer.
287    Read {
288        /// Source file.
289        file: &'a F,
290        /// Byte offset.
291        offset: u64,
292        /// Destination.
293        buf: IoBuf,
294    },
295    /// Flush the device cache for this file's data (`fdatasync`,
296    /// `NtFlushBuffersFileEx(DATA_SYNC_ONLY)`, `F_FULLFSYNC`).
297    FlushData {
298        /// File whose data (and the device cache) is flushed.
299        file: &'a F,
300    },
301}
302
303/// A finished operation.
304#[derive(Debug)]
305pub struct Completion {
306    /// The tag passed to [`Queue::submit`].
307    pub tag: u64,
308    /// The operation's buffer, returned (`None` for flushes).
309    pub buf: Option<IoBuf>,
310    /// Bytes transferred (possibly short), or the raw error.
311    pub result: RawResult<usize>,
312}
313
314/// An operation `submit` refused; it never reached the kernel or device.
315#[derive(Debug)]
316pub struct Rejected {
317    /// The operation's buffer, returned to the caller.
318    pub buf: Option<IoBuf>,
319    /// The raw error, if the refusal came from the OS (a full queue has none).
320    pub raw: Option<OsError>,
321}
322
323/// Completions collected by [`Queue::reap`] / [`Queue::wait`].
324///
325/// Allocated once with a fixed capacity; reaping never grows it, so the hot
326/// path never allocates.
327#[derive(Debug)]
328pub struct CompletionBuf {
329    items: Vec<Completion>,
330    cap: usize,
331}
332
333impl CompletionBuf {
334    /// Creates a buffer for up to `cap` completions.
335    #[must_use]
336    pub fn with_capacity(cap: usize) -> Self {
337        Self {
338            items: Vec::with_capacity(cap),
339            cap,
340        }
341    }
342
343    /// Room left before the buffer is full.
344    #[must_use]
345    pub fn room(&self) -> usize {
346        self.cap - self.items.len()
347    }
348
349    /// Adds a completion; returns it back if the buffer is full.
350    pub fn push(&mut self, c: Completion) -> Result<(), Completion> {
351        if self.items.len() == self.cap {
352            return Err(c);
353        }
354        self.items.push(c);
355        Ok(())
356    }
357
358    /// Removes and returns every collected completion, in arrival order.
359    pub fn drain(&mut self) -> std::vec::Drain<'_, Completion> {
360        self.items.drain(..)
361    }
362
363    /// Number of collected completions.
364    #[must_use]
365    pub fn len(&self) -> usize {
366        self.items.len()
367    }
368
369    /// Whether nothing is collected.
370    #[must_use]
371    pub fn is_empty(&self) -> bool {
372        self.items.is_empty()
373    }
374}
375
376/// A per-thread submission queue. Not `Sync`: one thread submits and reaps.
377pub trait Queue {
378    /// The platform's file handle type.
379    type File;
380    /// The queue's waker ([`Self::waker`]).
381    type Waker: Wake;
382
383    /// Submits an operation tagged with a caller value.
384    ///
385    /// # Errors
386    ///
387    /// [`Rejected`] when the operation was not submitted (queue full or an OS
388    /// refusal before any I/O); its buffer is returned.
389    fn submit(&mut self, op: IoOp<'_, Self::File>, tag: u64) -> Result<(), Rejected>;
390
391    /// Moves finished completions into `out` without blocking; returns how
392    /// many were added.
393    fn reap(&mut self, out: &mut CompletionBuf) -> usize;
394
395    /// Blocks until at least `min` completions have been added to `out`, or
396    /// `out` is full, or nothing is left in flight, or the queue's waker
397    /// fired ([`Self::waker`]; the wait may then have added nothing); returns
398    /// how many were added. Never times out, and never waits for more than
399    /// is in flight.
400    ///
401    /// # Errors
402    ///
403    /// The raw error if waiting itself failed (not an operation error).
404    fn wait(&mut self, min: usize, out: &mut CompletionBuf) -> RawResult<usize>;
405
406    /// Operations submitted and not yet reaped.
407    fn in_flight(&self) -> usize;
408
409    /// Whether [`Self::perform`] would perform an operation now: this queue
410    /// runs every operation inside [`Self::submit`] and holds nothing. The
411    /// default: never.
412    fn performs(&self) -> bool {
413        false
414    }
415
416    /// Performs `op` now, on the calling thread, when [`Self::performs`]:
417    /// its buffer and result, exactly as its completion would carry them
418    /// (the same checks first, the same faults), with no completion left
419    /// behind. Otherwise the operation comes back (`Ok(Err(op))`) for
420    /// [`Self::submit`]. The default never performs.
421    ///
422    /// # Errors
423    ///
424    /// [`Rejected`] as [`Self::submit`]: refused before any I/O.
425    #[allow(clippy::type_complexity)]
426    fn perform<'a>(
427        &mut self,
428        op: IoOp<'a, Self::File>,
429    ) -> Result<Result<(Option<IoBuf>, RawResult<usize>), IoOp<'a, Self::File>>, Rejected> {
430        Ok(Err(op))
431    }
432
433    /// A handle another thread uses to end this queue's wait (D-083).
434    fn waker(&self) -> Self::Waker;
435
436    /// Worker threads that run this queue's operations concurrently, when
437    /// the backend runs them on a pool ([`QueueConfig::parallel`]); `None`
438    /// when they run inside `submit` or in the kernel.
439    fn workers(&self) -> Option<usize> {
440        None
441    }
442}
443
444/// A shareable handle to a backend's fine monotonic clock
445/// ([`Platform::clock`]): nanoseconds, never decreasing.
446pub type Clock = std::sync::Arc<dyn Fn() -> u64 + Send + Sync>;
447
448/// A platform backend.
449pub trait Platform: Send + Sync + 'static {
450    /// Open file handle (closed on drop).
451    type File: Send + Sync;
452    /// Open directory handle.
453    type Dir: Send + Sync;
454    /// Held ownership lock (released on drop, after in-flight I/O on the
455    /// locked file has completed).
456    type Lock: Send + Sync;
457    /// Per-thread queue.
458    type Queue: Queue<File = Self::File>;
459
460    /// Opens a directory; with `create`, creates it if missing and syncs its
461    /// parent (the directory holding its entry), also when it already exists
462    /// (an earlier attempt may have died before the sync). For an existing
463    /// directory, a parent that cannot be synced on that volume (no
464    /// directory flush: unsupported; read-only on macOS; on Windows not
465    /// openable for it or write-protected) is not an error. A directory this
466    /// call made is removed again if its sync fails (POSIX: also its open),
467    /// when it is still the one made.
468    ///
469    /// # Errors
470    ///
471    /// The raw error.
472    fn open_dir(&self, path: &Path, create: bool) -> RawResult<Self::Dir>;
473
474    /// Creates a new file exclusively (fails if it exists), mode 0600.
475    ///
476    /// # Errors
477    ///
478    /// The raw error; the file does not exist afterwards unless creation
479    /// itself succeeded.
480    fn create_file(&self, dir: &Self::Dir, name: &FileName) -> RawResult<Self::File>;
481
482    /// Opens an existing file for direct I/O.
483    ///
484    /// # Errors
485    ///
486    /// The raw error.
487    fn open_file(&self, dir: &Self::Dir, name: &FileName, mode: FileMode) -> RawResult<Self::File>;
488
489    /// Atomically replaces `to` with `from` in the same directory. The file
490    /// handle is the open `from` (Windows renames by handle).
491    ///
492    /// # Errors
493    ///
494    /// The raw error. After a failure the rename may or may not have
495    /// happened; the engine treats it as durability-unknown.
496    fn rename_replace(
497        &self,
498        dir: &Self::Dir,
499        from: &FileName,
500        to: &FileName,
501        file: &Self::File,
502    ) -> RawResult<()>;
503
504    /// Renames `from` to `to` in the same directory, refusing if `to`
505    /// exists (the platform's "already exists" error, nothing renamed): a
506    /// rename that can never replace a file another process created after
507    /// the caller looked. Atomic where the system has such a rename (Linux
508    /// `RENAME_NOREPLACE`, Windows); elsewhere a hard link named `to` made
509    /// to the file, the directory flushed, then `from` removed, so a crash
510    /// may leave both names on the file (never neither). The file handle is
511    /// the open `from` (Windows renames by handle).
512    ///
513    /// # Errors
514    ///
515    /// The raw error. After any other failure the file may be under `from`,
516    /// under `to`, or (the link fallback) under both; the engine treats it
517    /// as durability-unknown.
518    fn rename_noreplace(
519        &self,
520        dir: &Self::Dir,
521        from: &FileName,
522        to: &FileName,
523        file: &Self::File,
524    ) -> RawResult<()>;
525
526    /// Removes a file.
527    ///
528    /// # Errors
529    ///
530    /// The raw error.
531    fn unlink(&self, dir: &Self::Dir, name: &FileName) -> RawResult<()>;
532
533    /// Makes the directory's entries durable. An unsupported directory flush
534    /// is an error, never success.
535    ///
536    /// # Errors
537    ///
538    /// The raw error.
539    fn sync_dir(&self, dir: &Self::Dir) -> RawResult<()>;
540
541    /// Bytes this process may still write to the file system holding
542    /// `dir`: the blocks free to an unprivileged writer on Linux
543    /// (`fstatvfs`: `f_bavail * f_frsize`) and macOS (`fstatfs`: `f_bavail *
544    /// f_bsize`, its counts 64 bits wide), user and group quotas not
545    /// counted; `GetDiskFreeSpaceExW`'s bytes available to the caller on
546    /// Windows (its quota counted); in the simulator its capacity less the
547    /// files a directory entry still names. A hint for a check before a
548    /// large write (an import's), never a reservation: another writer may
549    /// take the space meanwhile, and a quota may refuse the write first.
550    ///
551    /// # Errors
552    ///
553    /// The OS error of the query.
554    fn free_space(&self, dir: &Self::Dir) -> RawResult<u64>;
555
556    /// Whether `dir` holds no entry (`.` and `..` aside): no file, no
557    /// directory, nothing else, hidden and system entries counted (so a
558    /// volume's root, which holds `lost+found` or `System Volume
559    /// Information`, is never empty, nor is a folder a file manager wrote
560    /// its `.DS_Store` or `desktop.ini` into). Read through `dir` itself on
561    /// Linux and macOS, by its path on Windows.
562    ///
563    /// # Errors
564    ///
565    /// The OS error of reading the directory.
566    fn dir_is_empty(&self, dir: &Self::Dir) -> RawResult<bool>;
567
568    /// A coarse monotonic clock in milliseconds (resolution 1-16 ms) that
569    /// never decreases. Cold: read only by queries such as
570    /// `oldest_outstanding`, never on the I/O path.
571    fn monotonic_ms(&self) -> u64;
572
573    /// A fine monotonic clock in nanoseconds that never decreases, from
574    /// one origin across the process's threads. Allowed on the I/O path
575    /// (pacing reads it at commit barriers): a user-space read where the
576    /// operating system offers one (Linux's vDSO, Windows's performance
577    /// counter, macOS's uptime clock). Deterministic in the simulator.
578    fn monotonic_ns(&self) -> u64;
579
580    /// The clock [`Self::monotonic_ns`] reads, as a handle the engine keeps
581    /// (PLANNING R5.4): the same values as `monotonic_ns`, from the same
582    /// origin. A store calls it at every barrier and, on a power-safe store,
583    /// every durable write, with engine locks held: so it must be cheap (a
584    /// user-space read where the system offers one), never block, never take
585    /// a lock the I/O path might hold, and never panic.
586    fn clock(&self) -> Clock;
587
588    /// The scope device identities of this backend are unique in: two
589    /// identities, file-system devices or volumes from backends of
590    /// different scopes never name one device. 0 for every backend on real
591    /// devices; the simulator's world (each world's devices are its own).
592    fn identity_scope(&self) -> u64 {
593        0
594    }
595
596    /// A queue as [`Platform::queue`] makes it, with `file` registered with
597    /// it where the backend can (D-078, D-107: an io_uring direct descriptor
598    /// on a thread-owned ring, used by reads only), so an operation on `file`
599    /// may skip the per-operation file lookup in the kernel. Best effort: a
600    /// backend that
601    /// cannot or will not register returns a plain queue (the default), and
602    /// an operation on any other file works as on a plain queue. The queue
603    /// keeps the file it registered open for as long as it lives.
604    ///
605    /// # Errors
606    ///
607    /// As [`Platform::queue`] (a refused registration is not an error).
608    fn queue_registered(&self, cfg: QueueConfig, file: &Self::File) -> RawResult<Self::Queue> {
609        let _ = file;
610        self.queue(cfg)
611    }
612
613    /// Whether flushes may run concurrently on separate handles of one file
614    /// (D-124). Both must hold: a flush through any handle persists every
615    /// write that completed through **any** handle of the file before the
616    /// flush began (file systems flush the file, not the handle); and a
617    /// flush reports every write-back failure since the previous flush **on
618    /// the same handle**, independently of flushes on other handles (Linux
619    /// 4.16 and later: the error sequence is kept per open file
620    /// description, and a handle opened after an unseen error still sees
621    /// it). False by default: one flush in flight.
622    fn flush_errors_per_handle(&self) -> bool {
623        false
624    }
625
626    /// A second handle on the very file `file` is (never another file that
627    /// has since taken its name), read-write, with an open file description
628    /// of its own and no lock: what a store's extra flush slots flush
629    /// through (D-124). `None` where the platform cannot (the default).
630    fn reopen(&self, file: &Self::File) -> Option<Self::File> {
631        let _ = file;
632        None
633    }
634
635    /// The kernel interface this platform's queues use, and why.
636    fn io_path(&self) -> IoPath {
637        IoPath {
638            interface: IoInterface::Other,
639            reason: "the backend's only interface".to_owned(),
640        }
641    }
642
643    /// Takes the exclusive ownership lock on an open file. At most one lock
644    /// (exclusive or shared) may be held per handle: on Linux a second lock
645    /// on the same handle shares the first's open file description, and
646    /// releasing either releases both.
647    ///
648    /// # Errors
649    ///
650    /// The raw error (another holder reports the platform's "would block").
651    fn lock_exclusive(&self, file: &Self::File) -> RawResult<Self::Lock>;
652
653    /// Takes the shared (reader) ownership lock on an open file, which may
654    /// be read-only. Shared holders coexist; a shared holder and an exclusive
655    /// holder exclude each other. At most one lock per handle (see
656    /// [`Self::lock_exclusive`]).
657    ///
658    /// # Errors
659    ///
660    /// The raw error (an exclusive holder reports the platform's "would
661    /// block").
662    fn lock_shared(&self, file: &Self::File) -> RawResult<Self::Lock>;
663
664    /// Sets the file's size to exactly `len` bytes, truncating or extending
665    /// with zeros. The data transfers stay block-aligned; only the size
666    /// moves. A metadata change: durable after [`Self::flush_all`].
667    ///
668    /// # Errors
669    ///
670    /// The raw error.
671    fn set_len(&self, file: &Self::File, len: u64) -> RawResult<()>;
672
673    /// Allocates real blocks up to `len` bytes, so the file size becomes
674    /// `len`. A file already at least `len` long is left as it is: this never
675    /// shrinks a file (that is [`Self::set_len`]).
676    /// Never leaves unwritten extents' contents readable as other files' data.
677    ///
678    /// # Errors
679    ///
680    /// The raw error (out of space reports the platform's ENOSPC equivalent).
681    fn allocate(&self, file: &Self::File, len: u64) -> RawResult<()>;
682
683    /// Allocates real blocks for `[offset, offset + len)`, inside the file:
684    /// its size never changes, and bytes already written stay as they are.
685    /// Blocks it allocates read as zeros until written (an unwritten extent
686    /// on Linux), never another file's data. For space a write will need
687    /// later without writing it now (format 2's capped regions): that holds
688    /// on a file system that overwrites in place; one that copies on write
689    /// (btrfs, ZFS) or a range sharing blocks with another file (a reflink)
690    /// may still allocate when the range is written. A length of 0 inside
691    /// the file or at its end does nothing.
692    ///
693    /// # Errors
694    ///
695    /// The raw error: out of space as the platform's ENOSPC equivalent; a
696    /// range past the end of the file as EINVAL's (Windows:
697    /// `ERROR_INVALID_PARAMETER`); a read-only handle (`EBADF`,
698    /// `ERROR_ACCESS_DENIED`); a file system that cannot allocate inside a
699    /// file (Linux `EOPNOTSUPP`: ext4 without extents, NFS before 4.2, many
700    /// FUSE file systems; macOS `ENOTSUP`, always: `F_PREALLOCATE` only
701    /// extends a file) or a file whose space a write may still need to
702    /// allocate (Windows: sparse, compressed or integrity-stream files,
703    /// `ERROR_NOT_SUPPORTED`) as unsupported.
704    fn allocate_range(&self, file: &Self::File, offset: u64, len: u64) -> RawResult<()>;
705
706    /// Current file size.
707    ///
708    /// # Errors
709    ///
710    /// The raw error.
711    fn size(&self, file: &Self::File) -> RawResult<u64>;
712
713    /// Releases a range.
714    ///
715    /// # Errors
716    ///
717    /// The raw error.
718    fn release_range(
719        &self,
720        file: &Self::File,
721        offset: u64,
722        len: u64,
723        how: ReleaseHow,
724    ) -> RawResult<()>;
725
726    /// Reports extent and cache state for a range.
727    ///
728    /// # Errors
729    ///
730    /// The raw error.
731    fn range_state(&self, file: &Self::File, offset: u64, len: u64) -> RawResult<RangeState>;
732
733    /// Makes data and metadata durable (fsync / FlushFileBuffers / F_FULLFSYNC).
734    ///
735    /// # Errors
736    ///
737    /// The raw error.
738    fn flush_all(&self, file: &Self::File) -> RawResult<()>;
739
740    /// Gathers raw evidence about the file's filesystem, stack and device.
741    ///
742    /// # Errors
743    ///
744    /// The raw error if nothing could be learned at all; partial evidence is
745    /// returned with `missing` set.
746    fn probe(&self, dir: &Self::Dir, file: &Self::File) -> RawResult<Evidence>;
747
748    /// The physical devices `file` lives on: the identity part of
749    /// [`Self::probe`] alone, with no flush and no device query that could
750    /// send one. Never fails: what cannot be read makes the identity
751    /// incomplete.
752    fn device_identity(&self, dir: &Self::Dir, file: &Self::File) -> DeviceIdentity;
753
754    /// The identity of an open file.
755    ///
756    /// # Errors
757    ///
758    /// The raw error.
759    fn file_identity(&self, file: &Self::File) -> RawResult<FileIdentity>;
760
761    /// The identity of the file `name` in `dir` names now (following the
762    /// same links [`Self::open_file`] follows).
763    ///
764    /// # Errors
765    ///
766    /// The raw error (`name` names nothing: the platform's "not found").
767    fn path_identity(&self, dir: &Self::Dir, name: &FileName) -> RawResult<FileIdentity>;
768
769    /// Creates a queue for the calling thread.
770    ///
771    /// # Errors
772    ///
773    /// The raw error.
774    fn queue(&self, cfg: QueueConfig) -> RawResult<Self::Queue>;
775}
776
777#[cfg(test)]
778mod tests {
779    use super::*;
780
781    #[test]
782    fn test_file_name_rejects_escapes_and_separators() {
783        for bad in ["", ".", "..", "a/b", "a\\b", "c:x", "nul\0"] {
784            assert!(FileName::new(bad).is_err(), "{bad:?}");
785        }
786        assert!(FileName::new(&"x".repeat(256)).is_err());
787        assert_eq!(
788            FileName::new("store.sio").map(|n| n.as_str().to_owned()),
789            Ok("store.sio".to_owned())
790        );
791    }
792
793    #[test]
794    fn test_completion_buf_never_grows() {
795        let mut b = CompletionBuf::with_capacity(1);
796        assert!(
797            b.push(Completion {
798                tag: 1,
799                buf: None,
800                result: Ok(0)
801            })
802            .is_ok()
803        );
804        assert!(
805            b.push(Completion {
806                tag: 2,
807                buf: None,
808                result: Ok(0)
809            })
810            .is_err()
811        );
812        assert_eq!(b.room(), 0);
813        assert_eq!(b.drain().map(|c| c.tag).collect::<Vec<_>>(), vec![1]);
814        assert!(b.is_empty());
815    }
816}