Struct VirtualBuffer 

pub struct VirtualBuffer<B: VirtualBacking = HostBacking> { /* private fields */ }

A growable region whose base address never changes.

Created with a capacity — an upper bound on address space — and a length that starts at zero. VirtualBuffer::grow_to commits pages; VirtualBuffer::shrink_to gives them back. The pointer returned by VirtualBuffer::as_ptr is the same for the buffer’s whole life.

Implementations

impl VirtualBuffer<HostBacking>

pub fn with_capacity( capacity: usize, governor: Arc<dyn MemoryGovernor + Send + Sync>, tier: Tier, role: MemoryRole, holder: HolderId, ) -> Result<Self, VirtualBufferError>

Reserve capacity bytes of the process’s own address space.

The device equivalent takes a backing; see VirtualBuffer::with_backing.

impl<B: VirtualBacking> VirtualBuffer<B>

pub fn with_backing( backing: B, capacity: usize, governor: Arc<dyn MemoryGovernor + Send + Sync>, tier: Tier, role: MemoryRole, holder: HolderId, ) -> Result<Self, VirtualBufferError>

Reserve capacity bytes of address space from backing, committing nothing.

capacity is rounded up to the backing’s granularity. Reserve for the largest the buffer could ever be: it costs address space, not memory, and it is the only bound that cannot be raised later.

pub fn len(&self) -> usize

Bytes the caller has asked for.

pub fn is_empty(&self) -> bool

Whether the buffer holds nothing yet.

pub fn committed(&self) -> usize

Bytes backed by physical memory, and therefore leased.

At least VirtualBuffer::len and rounded to a granule, so the two differ by up to one granule after any growth.

pub fn capacity(&self) -> usize

Address space reserved at construction. Cannot be raised.

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

The base address, fixed for this buffer’s whole life.

Only the first VirtualBuffer::len bytes may be read or written.

pub fn as_mut_ptr(&mut self) -> *mut u8

The base address, mutable.

pub unsafe fn as_slice(&self) -> &[u8]

The committed prefix, as bytes.

Safety

Every byte of ..len must have been initialised by the caller. Growth commits pages but does not promise their contents beyond what the platform guarantees for fresh mappings.

pub fn grow_to(&mut self, bytes: usize) -> Result<(), VirtualBufferError>

Grow to bytes, committing and leasing whatever pages that needs.

A no-op when the buffer is already at least that long. On failure the buffer is exactly as it was: the lease is taken before the mapping, and released again if the mapping fails.

pub fn shrink_to(&mut self, bytes: usize) -> Result<(), VirtualBufferError>

Shrink to bytes, returning whole granules that fall entirely above it.

A no-op when the buffer is already that short. The granule containing bytes stays committed, because part of it is still in use — so a small shrink can return nothing, which is honest rather than a failure.

Trait Implementations

impl<B: VirtualBacking> Debug for VirtualBuffer<B>

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

Formats the value using the given formatter.