Struct Win32FileTarget 

pub struct Win32FileTarget { /* private fields */ }

A target backed by a Win32 file, a raw volume or a whole disk this crate opened, held as a SharedHandle – an owning form, never a raw handle (DI-D-4).

It is made from an OpenedFile, an OpenedVolume or an OpenedDisk and from nothing else, and takes its warranty class, its alignment and its capabilities from how that was opened, not from a declaration (DI-D-60): one opened cached is WarrantyClass::BestEffort, and one opened Unbuffered is WarrantyClass::SharedDevice, needs a sector’s alignment, and offers per-write write-through. WarrantyClass::Complete is never derived from how a file was opened: it needs knowledge of what else writes the device, which a volume’s lock does not give (DI-D-61). A consumer who has that knowledge says so through new_attested_exclusive, from_volume_attested_exclusive or from_disk_attested_exclusive (DI-D-68).

A target needs a data right, so it is made only from a handle whose data access is HasData: one opened with NoData is refused when the program is compiled, not when the first operation fails.

use win_durable_ioring::Wtf16String;
use win_durable_ioring::windows_backend::{Cached, FileOptions, OpenedFile, Win32FileTarget};

let name = Wtf16String::from_os_str("a-file".as_ref());
let no_data = OpenedFile::<Cached, _>::open(name, FileOptions::new()).unwrap();
let _ = Win32FileTarget::new(no_data);

A volume’s flush domains are found from its disks. A file’s are what it cannot know, so they are declared with with_domains; declaring them on a volume adds to the ones found, and never removes one.

Implementations

impl Win32FileTarget

pub fn new<B: Buffering, A: HasData>(file: OpenedFile<B, A>) -> Self

The target file makes, claiming what its open mode allows and no more.

pub fn from_volume<B: Buffering, A: HasData>(volume: OpenedVolume<B, A>) -> Self

The target volume makes: its sector’s alignment, the flush domains of the disks it sits on, and what its open mode allows and no more.

pub fn from_disk<B: Buffering, A: HasData>(disk: OpenedDisk<B, A>) -> Self

The target disk makes: its sector’s alignment, the disk itself as its flush domain, and what its open mode allows and no more.

pub fn new_attested_exclusive<A: HasData>( file: OpenedFile<Unbuffered, A>, ) -> Self

The target file makes, with the consumer’s attestation that nothing else writes the device it is on and that the flush domains it reports are all of them, so that it claims WarrantyClass::Complete (DI-D-68).

The claim is the consumer’s and nothing here can check it: a handle cannot show what else writes a device. A wrong claim mislabels what the target reports and changes nothing the layer does, which behaves the same for every class (DI-D-50 P3). The flush domains, the alignment and the capabilities are what new gives the same file.

Only a file opened Unbuffered can be attested. A cached file claims WarrantyClass::BestEffort because the cache may report success for data already lost, and what else writes the device does not change that, so there is nothing to attest; it is refused when the program is compiled.

use win_durable_ioring::Wtf16String;
use win_durable_ioring::windows_backend::{
    Cached, FileOptions, OpenedFile, Win32FileTarget,
};

let name = Wtf16String::from_os_str("a-file".as_ref());
let cached = OpenedFile::<Cached, _>::open(name, FileOptions::new().read().write()).unwrap();
let _ = Win32FileTarget::new_attested_exclusive(cached);

pub fn from_volume_attested_exclusive<A: HasData>( volume: OpenedVolume<Unbuffered, A>, ) -> Self

The target volume makes, with the consumer’s attestation that nothing else writes the disks it sits on and that the flush domains it reports, which are those disks, are all of them, so that it claims WarrantyClass::Complete. The claim, what it does not change and why a cached volume cannot make it are those of new_attested_exclusive.

A volume’s lock keeps other handles off the volume, not other writers off its disks (DI-D-61), so a locked volume is not thereby attested.

pub fn from_disk_attested_exclusive<A: HasData>( disk: OpenedDisk<Unbuffered, A>, ) -> Self

The target disk makes, with the consumer’s attestation that nothing else writes the disk and that the flush domain it reports, the disk itself, is all of them, so that it claims WarrantyClass::Complete. The claim, what it does not change and why a cached disk cannot make it are those of new_attested_exclusive.

pub fn with_domains( self, domains: impl IntoIterator<Item = FlushDomain>, ) -> Self

Declare every flush domain its writes depend on, beyond any the backing found for itself. Declaring again replaces what was declared before, and never what the backing found.

pub fn handle(&self) -> &SharedHandle

The file’s handle.

Trait Implementations

impl Clone for Win32FileTarget

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Win32FileTarget

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

Formats the value using the given formatter.

impl IoTarget for Win32FileTarget

fn flush_domains(&self) -> &[FlushDomain]

Every flush domain its writes depend on. The declaration must be complete; an extra domain is safe, a missing one is not. None means it shares fate with every target.

fn warranty(&self) -> WarrantyClass

How far it honours its obligations.

fn geometry(&self) -> Geometry

The alignment its operations need.

fn capabilities(&self) -> Capabilities

What it offers beyond its obligations.

fn access(&self) -> Access

What it can do with its data: read it, write it, or both. A backend refuses a write to a target that cannot write and a read from one that cannot read, with RefusalCause::AccessDenied. There is no default: a target that has not said what it can do has not said it can do everything.

fn describe(&self) -> IoTargetDescription

Everything it states, as the core takes it.