Expand description
§store-io-platform
The boundary between store-io’s engine and the operating system.
Everything above this crate (error classification, barriers, formats, provisioning, slots) is one shared code path. Below it, each platform backend (Linux, Windows, macOS) and the deterministic simulator implement two traits:
Platform: metadata operations (open, create, rename, directory flush, lock, allocate, full flush, probe), synchronous and off the hot path, plus a factory for per-threadQueues.Queue: data operations, completion-shaped.Queue::submittakes anIoOpthat owns its buffer; the buffer comes back in aCompletion. A synchronous backend performs the system call insidesubmitand completes immediately (no thread hop); the simulator and the io_uring / IOCP backends complete later, possibly out of order.
Backends return raw operating-system codes (OsError) and never
classify them; the engine decides what an error means (see
store_io_core::errno).
§Contracts every implementation keeps
- An operation’s buffer is not touched by the caller between
submitand the completion that returns it, and is never freed by the backend: it is returned in the completion, or inRejectedifsubmitrefuses it. Only a failed completion may withhold it, for ever, when the kernel may still use it (an asynchronous backend that lost track of its kernel). - A file handle passed in an operation stays open until that operation’s completion has been reaped. The engine guarantees this by keeping the handle alive while operations are in flight; a backend may copy the raw descriptor.
submitreturningErrmeans the operation never reached the kernel or device (the media is untouched).- A completion’s
resultis the raw outcome:Ok(n)bytes transferred, which may be short, orErr(code). - No call ever waits with a timeout.
Queue::waitblocks until the requested completions exist.
Structs§
- Completion
- A finished operation.
- Completion
Buf - Completions collected by
Queue::reap/Queue::wait. - Evidence
- Everything a backend could learn about one path.
- File
Name - A single path component: 1 to 255 bytes, no separators, not
.or.., no NUL. Validated once at construction so backends never see a path that could escape its directory. - Invalid
File Name - The name is not a valid single path component.
- IoBuf
- An owned, aligned I/O buffer from a
BufPool. - IoPath
- The kernel interface a platform’s queues use, and why (reported in
StoreReport). - OsError
- Raw operating-system error code, kept exactly as the OS reported it.
- Queue
Config - Per-queue configuration.
- Range
State - Facts about a byte range of a file.
- Rejected
- An operation
submitrefused; it never reached the kernel or device.
Enums§
- File
Mode - How a file is opened.
- IoInterface
- A kernel interface for I/O (
IoPath). - IoOp
- A data operation. Owns its buffer until it completes.
- Linux
Tier - Which kernel interface the Linux backend’s queues use (D-082). Other backends have one interface and ignore it.
- Owner
- Who uses a queue (
QueueConfig::owner). - Release
How - How space is released.
Traits§
- Platform
- A platform backend.
- Queue
- A per-thread submission queue. Not
Sync: one thread submits and reaps. - Wake
- Ends a
Queue::waitfrom another thread (D-083): the queue’s current wait, or its next one if none is in progress, returns, possibly having added nothing. A wake never creates, loses or repeats a completion.
Type Aliases§
- RawResult
- Result carrying a raw operating-system error.