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}