Enum WriteCaching 

pub enum WriteCaching {
    Cached,
    WriteThrough,
}

Where a write is allowed to stop: in the system cache, or past it (M12.3, D-25 in DESIGN-NOTES.md).

This is BuildIoRingWriteFile’s FILE_WRITE_FLAGS parameter, which the crate previously hardcoded to FILE_WRITE_FLAGS_NONE – so a consumer reading this API saw ordering but no way to express anything about caching at all, and could reasonably conclude the ring did not expose it. It does; the crate was narrowing the platform to what its own examples needed.

What write-through is, and what it is not

Worth stating precisely, because conflating these produced a wrong recommendation in the exchange that prompted this work.

It is a first-level cache directive: it tells the OS not to leave the data sitting in the system cache. Its practical value is latency shaping – data already at the device makes a later flush shorter, which can matter when the flush is on a commit path.

It is not a durability guarantee, and it is not FUA. Whether it becomes a Force Unit Access bit on the underlying command depends on the driver, the volume, and whether the device’s write cache is enabled – none of which this API can see or promise. A write that completes with WriteCaching::WriteThrough may still be sitting in a volatile device cache, and will be lost on power failure like any other.

The flush operation is the only durability primitive the ring has, and only with FlushCoverage::CoversPrecedingOperations. Reaching for write-through instead of a covering flush is the mistake this doc exists to prevent; reaching for it as well is a legitimate latency optimization.

Variants

Cached

FILE_WRITE_FLAGS_NONE: the write may be satisfied into the system cache, and reaching the device is a later flush’s job.

The default, and the right choice for the streaming writes of an epoch that a covering flush will close.

WriteThrough

FILE_WRITE_FLAGS_WRITE_THROUGH: ask the OS not to leave the data in the system cache.

A latency-shaping knob, not a durability marker – see this type’s docs. It does not remove the need for a flush.

Trait Implementations

impl Clone for WriteCaching

fn clone(&self) -> WriteCaching

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for WriteCaching

impl Debug for WriteCaching

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for WriteCaching

fn default() -> WriteCaching

Returns the “default value” for a type.

impl Eq for WriteCaching

impl PartialEq for WriteCaching

fn eq(&self, other: &WriteCaching) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for WriteCaching