Skip to main content

Crate store_io_platform

Crate store_io_platform 

Source
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-thread Queues.
  • Queue: data operations, completion-shaped. Queue::submit takes an IoOp that owns its buffer; the buffer comes back in a Completion. A synchronous backend performs the system call inside submit and 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

  1. An operation’s buffer is not touched by the caller between submit and the completion that returns it, and is never freed by the backend: it is returned in the completion, or in Rejected if submit refuses 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).
  2. 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.
  3. submit returning Err means the operation never reached the kernel or device (the media is untouched).
  4. A completion’s result is the raw outcome: Ok(n) bytes transferred, which may be short, or Err(code).
  5. No call ever waits with a timeout. Queue::wait blocks until the requested completions exist.

Structs§

Completion
A finished operation.
CompletionBuf
Completions collected by Queue::reap / Queue::wait.
Evidence
Everything a backend could learn about one path.
FileName
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.
InvalidFileName
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.
QueueConfig
Per-queue configuration.
RangeState
Facts about a byte range of a file.
Rejected
An operation submit refused; it never reached the kernel or device.

Enums§

FileMode
How a file is opened.
IoInterface
A kernel interface for I/O (IoPath).
IoOp
A data operation. Owns its buffer until it completes.
LinuxTier
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).
ReleaseHow
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::wait from 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.