Skip to main content

VirtualBacking

onnx_runtime_virtual_memory::backing

Trait VirtualBacking 

Source 
pub unsafe trait VirtualBacking:
    Send
    + Sync
    + Debug {
    type Reservation: Send + Sync + Debug;

    // Required methods
    fn granularity(&self) -> usize;
    fn reserve(
        &self,
        len: usize,
    ) -> Result<Self::Reservation, VirtualMemoryError>;
    fn base(reservation: &Self::Reservation) -> usize;
    fn commit(
        &self,
        reservation: &mut Self::Reservation,
        offset: usize,
        len: usize,
    ) -> Result<(), VirtualMemoryError>;
    fn release(
        &self,
        reservation: &mut Self::Reservation,
        offset: usize,
        len: usize,
    ) -> Result<(), VirtualMemoryError>;

    // Provided method
    fn physical_memory_accounting(&self) -> PhysicalMemoryAccounting { ... }
}
Expand description

The platform operations a VirtualBuffer is built from.

§Safety

This trait is unsafe to implement because VirtualBuffer hands out the base address and lets callers write to the committed prefix. An implementation that reported a range it had not reserved, or a granularity it did not honour, would turn those writes into memory corruption rather than an error. Specifically:

  • VirtualBacking::granularity is constant for the backing’s life and a power of two.
  • VirtualBacking::reserve takes address space only. It must not commit memory: the whole design rests on reserving generously being free.
  • VirtualBacking::base returns the address the reservation actually starts at, and that address does not change for the reservation’s life.
  • After VirtualBacking::commit returns Ok, every byte of base + offset .. base + offset + len is writable through that address.
  • Dropping a Reservation releases both its address space and any blocks still committed in it.

Required Associated Types§

Source

type Reservation: Send + Sync + Debug

One reserved address range, and whatever the platform needs to remember about what is committed in it.

Required Methods§

Source

fn granularity(&self) -> usize

Allocation granularity: every offset and length is a multiple of this.

Source

fn reserve(&self, len: usize) -> Result<Self::Reservation, VirtualMemoryError>

Reserve len bytes of address space, committing nothing.

Source

fn base(reservation: &Self::Reservation) -> usize

The address the reservation starts at.

Source

fn commit( &self, reservation: &mut Self::Reservation, offset: usize, len: usize, ) -> Result<(), VirtualMemoryError>

Back offset..offset + len of reservation with fresh memory.

offset and len are multiples of VirtualBacking::granularity and the range lies inside the reservation; the implementation is entitled to rely on both. Overlapping an already-committed block is a caller error the implementation should report rather than assume away.

Source

fn release( &self, reservation: &mut Self::Reservation, offset: usize, len: usize, ) -> Result<(), VirtualMemoryError>

Give back the block committed at offset, leaving the address space reserved so it can be committed again later.

Provided Methods§

Source

fn physical_memory_accounting(&self) -> PhysicalMemoryAccounting

Who owns accounting for committed physical memory.

Backings that retain physical allocations after unmapping must return PhysicalMemoryAccounting::Backing. A buffer validates the authority before reserving address space and does not take a second physical lease.

Dyn Compatibility§

This trait is not dyn compatible.

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

Implementors§