Skip to main content

store_io_win/
lib.rs

1//! # store-io-win
2//!
3//! The Windows backend behind the `store-io-platform` traits.
4//!
5//! - Data handles are opened `FILE_FLAG_NO_BUFFERING | FILE_FLAG_OVERLAPPED`
6//!   with read, write and delete sharing; exclusivity comes from the
7//!   ownership lock ([`WinLock`]), never from share modes.
8//! - [`WinQueue`] submits overlapped `WriteFile` / `ReadFile` and reaps from
9//!   its own I/O completion port with `GetQueuedCompletionStatusEx`, waiting
10//!   `INFINITE` or polling with a zero timeout. No wait anywhere in this
11//!   crate has a finite non-zero timeout.
12//! - A data flush is `NtFlushBuffersFileEx(FLUSH_FLAGS_FILE_DATA_SYNC_ONLY)`
13//!   on NTFS and `FlushFileBuffers` elsewhere; the choice is made once at
14//!   open and recorded on the handle ([`WinFile::flush_mode`]).
15//! - A `dsync` write performs the write and then that same data flush before
16//!   it completes, so "durable at completion" never depends on
17//!   `FILE_FLAG_WRITE_THROUGH`, whose FUA path is not certified on Windows.
18//! - Rename replaces by handle with `FileRenameInfoEx(REPLACE_IF_EXISTS |
19//!   POSIX_SEMANTICS)`; delete uses `FileDispositionInfoEx(DELETE |
20//!   POSIX_SEMANTICS)`. Legacy fallbacks are recorded, never silent.
21//! - [`Platform::probe`](store_io_platform::Platform::probe) fills
22//!   `Evidence` from the volume, the file, the
23//!   physical drive's storage properties and, on NVMe, the controller and
24//!   namespace identify data, the write-cache feature and the health log.
25//!   Device output is parsed as untrusted bytes with bounds checks.
26//!
27//! Every `unsafe` block cites the Win32 contract it relies on. All of them
28//! live in the private `sys` module except the two calls in the queue that
29//! hand a buffer and its completion record to `WriteFile` / `ReadFile`,
30//! whose lifetime contract the queue's slot table upholds. On a non-Windows
31//! target the crate compiles to an empty shell: none of the types below
32//! exist there.
33
34#![deny(warnings)]
35// Off Windows the crate is an empty shell, so the links above have no target.
36#![cfg_attr(not(windows), allow(rustdoc::broken_intra_doc_links))]
37
38#[cfg(windows)]
39mod alloc;
40#[cfg(any(windows, fuzzing))]
41#[cfg_attr(not(windows), allow(dead_code))]
42mod bytes;
43#[cfg(windows)]
44mod dir;
45#[cfg(windows)]
46mod file;
47/// Fuzz entry point for the probe's parsers (cargo-fuzz builds only, on any
48/// platform: the parsers are pure).
49#[cfg(fuzzing)]
50#[doc(hidden)]
51pub mod fuzzing;
52// Off Windows, a fuzz build compiles only the probe's pure parsers.
53#[cfg(all(not(windows), fuzzing))]
54#[allow(dead_code)]
55mod probe {
56    pub(crate) mod nvme;
57    pub(crate) mod storage;
58    pub(crate) mod volume;
59}
60#[cfg(windows)]
61mod lock;
62#[cfg(windows)]
63mod platform;
64#[cfg(windows)]
65mod probe;
66#[cfg(windows)]
67mod queue;
68#[cfg(windows)]
69mod sys;
70
71#[cfg(windows)]
72pub use dir::WinDir;
73#[cfg(windows)]
74pub use file::{FlushMode, WinFile};
75#[cfg(windows)]
76pub use lock::WinLock;
77#[cfg(windows)]
78pub use platform::WinPlatform;
79#[cfg(windows)]
80pub use queue::{WinQueue, WinWaker};