Trait FileTarget

Source

pub trait FileTarget: Sealed {
    type Guard: Send + 'static;

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

Expand description

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

This exists because the two carry different lifetime obligations, and exactly one of them has none. A SharedFile 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. Both are therefore safe to push, and neither needs unsafe – which is why Batch::read and its siblings are generic over this trait rather than hardcoding SharedFile.

Guard is what the returned Token holds until the operation’s completion is observed. For SharedFile that is a clone of its Arc, which is what makes the handle 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.