Struct Window 

pub struct Window { /* private fields */ }

A read only view of part of a file, at a fixed address, that can be moved.

See the module documentation for what this is for and what it guarantees. In short: the address the window lives at is reserved once and held until the window is dropped, and moving the view makes the bytes that used to be there unreadable rather than stale.

Implementations

impl Window

pub fn open(path: &Path) -> Result<Self, WindowError>

Opens path read only and reserves DEFAULT_SPAN bytes of address space for it.

Errors

If the file cannot be opened or measured, or the reservation is refused.

pub fn with_span(file: File, span: usize) -> Result<Self, WindowError>

Reserves span bytes of address space for file, rounded up to what the platform allows.

The span bounds the largest range this window can serve in one piece, so it has to be at least as large as the largest request plus the alignment slack in front of it. A view starts on an allocation boundary, so in the worst case that slack is one whole unit of allocation granularity, which is sixty four kibibytes on Windows and the page size elsewhere. A span of exactly one unit therefore serves a request only when it happens not to straddle a boundary, and a span for a largest request of n wants to be at least n plus one unit.

A span of zero is rounded up to one unit of allocation granularity rather than rejected, because a window over an empty file is a reasonable thing to ask for and reserving nothing is not.

Errors

If the file cannot be measured, or the reservation is refused.

pub fn len(&self) -> u64

How long the file is.

pub fn is_empty(&self) -> bool

Whether the file is empty.

pub fn file(&self) -> &File

The file this window reads from.

pub fn span(&self) -> usize

How much address space this window holds.

pub fn slides(&self) -> u64

How many times the view has moved since the window was opened.

A scan whose requests are clustered slides rarely. One that slides on nearly every request is either reading in an order the window is the wrong structure for or was opened with too small a span, and this is how a host tells those apart from the outside.

pub fn range(&mut self, at: u64, len: usize) -> Result<&[u8], WindowError>

The bytes of the file from at, len of them.

If the range is already inside the current view this costs a comparison. If it is not, the view moves first, which unmaps the old one and maps a new one, and every address the old view covered stops being readable.

The returned slice borrows the window, so it cannot outlive the view it came from. That is the safe half of the guarantee in the module documentation; the other half is about raw addresses and is a property of the mapping rather than of this signature.

Errors

WindowError::OutOfBounds if the range runs past the end of the file, WindowError::TooLarge if no single view could cover it, and WindowError::Os if the remap is refused.

pub fn address(&self) -> *const u8

The address the reservation starts at.

This is the address a host would hand to a sandbox, and it does not move for the life of the window, which is the point of reserving rather than mapping. Reading through it is only defined for the part of the reservation the current view covers. It is public so that the stale read tests can hold an address across a slide and check that it stopped being readable, which is a property no safe signature can express.

pub fn mapped(&self) -> Option<(u64, usize)>

Where the current view sits in the file and how long it is, or None if nothing is mapped.

The length is the mapped length, which is rounded out to a page and so is usually longer than the part of the file it covers.

Trait Implementations

impl Debug for Window

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

Formats the value using the given formatter.