Trait FileTarget 

pub trait FileTarget: Sealed {
    type Guard: Send + 'static + Into<FileGuard>;

    // Required methods
    fn as_file_ref(&self) -> FileRef;
    fn guard(&self) -> Self::Guard;
}

A file a safe push can address: either a SharedHandle or a RegisteredFile (M10.4; D-29, D-33 and D-82 in DESIGN-NOTES.md).

This exists because the two carry different lifetime obligations, and exactly one of them has none. A SharedHandle is a raw HANDLE underneath, so something must keep it open until the kernel is finished; a RegisteredFile is an index into a table the ring itself owns, minted by this crate and checked against the minting ring, so there is nothing for a caller to keep alive per push. (The handles behind that table are kept open for the ring’s life either by Batch::register_files’ caller, under its unsafe contract, or by the ring itself after Batch::register_shared_files.) Both are therefore safe to push, and neither needs unsafe – which is why Batch::read_owned and its siblings are generic over this trait rather than hardcoding SharedHandle.

Guard is what the ring holds until the operation’s completion is observed. For SharedHandle that is a clone, which shares the handle and so makes it outlive the operation; for RegisteredFile there is nothing to keep alive, so it is the (Copy) index itself, handed back for symmetry rather than out of necessity.

Sealed: this crate implements it for exactly those two types and no others. An outside implementation could return an arbitrary raw HANDLE from as_file_ref with no guard keeping it alive, which is precisely the unsoundness the _raw pushes make a caller take responsibility for with unsafe.

Required Associated Types

type Guard: Send + 'static + Into<FileGuard>

What the ring must hold for the operation until its completion is observed. What keeps the file valid while the operation runs.

Into<FileGuard> is expressible only because this trait is sealed (D-73): both implementors are this crate’s, so the ring can hold a guard in a concrete slot instead of a third generic parameter every consumer would have to name.

Required Methods

fn as_file_ref(&self) -> FileRef

How this target addresses its file.

fn guard(&self) -> Self::Guard

Produce the value the ring will hold for the operation’s duration.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl FileTarget for RegisteredFile

type Guard = RegisteredFile

impl FileTarget for SharedHandle

A SharedHandle is how a caller gives this crate a file it does not have to prove outlives every operation pushed against it (M8; D-82). One handle is legitimately the target of many concurrent pushes, so what must survive until every one of them completes is a reference, not sole ownership. Every safe push (e.g. Batch::read_owned, as opposed to its _raw sibling) clones it into the same inventory entry that tracks the operation’s own payload, so the handle survives until the ring returns that entry at its pop (D-4), whatever the caller does with its own clone.

type Guard = SharedHandle