Struct VirtualBlock 

pub struct VirtualBlock<'callbacks> { /* private fields */ }

Virtual TLSF or linear allocator; owns host metadata and no native objects.

Mutations require exclusive access. Drop releases host metadata only. Callback construction borrows its allocation/free record through Drop; raw callback user data remains the unsafe constructor caller’s responsibility. This is not a Vulkan memory block or a pool with GPU lifetime tracking.

Implementations

impl<'callbacks> VirtualBlock<'callbacks>

pub fn is_empty(&self) -> bool

Observe checked virtual emptiness in constant time.

pub fn set_user_data( &mut self, allocation: &VirtualAllocation, data: usize, ) -> Result<(), AllocError>

Set opaque per-allocation metadata, with no native pointer dereference or ownership.

pub fn detailed_statistics(&self) -> VirtualBlockDetails

Calculate explicit virtual allocation/free-span extrema.

pub fn write_statistics_json( &self, output: &mut impl Write, detailed: bool, ) -> Result<(), AllocError>

Stream virtual JSON diagnostics; no native memory is accessed.

pub fn new(size: u64) -> Result<Self, AllocError>

pub fn new_with_algorithm( size: u64, algorithm: AllocationAlgorithm, ) -> Result<Self, AllocError>

Create TLSF or linear host-only placement. No native storage is acquired.

use vk::{VirtualBlock, mem::{AllocationAlgorithm, PlacementStrategy}};
let mut block = VirtualBlock::new_with_algorithm(4096, AllocationAlgorithm::Linear)?;
let mut lower = block.allocate(64, 16, PlacementStrategy::Default)?;
let mut upper = block.allocate_upper(64, 16)?;
assert_eq!(block.allocation_info(&lower)?.offset, 0);
assert_eq!(block.allocation_info(&upper)?.offset, 4032);
block.free(&mut upper)?;
block.free(&mut lower)?;

Errors

Rejects a zero size or failed host metadata reservation.

pub unsafe fn new_with_callbacks( size: u64, algorithm: AllocationAlgorithm, callbacks: &'callbacks AllocationCallbacks, ) -> Result<Self, AllocError>

Create host-only placement whose metadata uses borrowed Vulkan allocation callbacks.

TLSF/linear buffers, growth and detailed-JSON scratch storage use only this allocation/free pair, with SystemAllocationScope::OBJECT. The block value stays inline; tokens need no reference-count allocation. Reallocation and driver internal-allocation notifications are not invoked. Drop releases host metadata only; no Vulkan device or native memory is involved. The callback record cannot expire while the block still owns storage:

let mut block;
{
    let callbacks = vk::AllocationCallbacks::new();
    // SAFETY: demonstration of record lifetime; null functions are rejected at runtime.
    block = unsafe {
        VirtualBlock::new_with_callbacks(1024, AllocationAlgorithm::Tlsf, &callbacks)
    }.unwrap();
}
block.clear();

Errors

Rejects zero size, a missing allocation/free function or failed host storage.

Safety

Callbacks must return uniquely owned memory of the requested size/alignment, or null on failure, and free only their own allocations. They must not unwind or reenter this block. Their code and user data must remain valid through block Drop and support calls from any thread, including concurrent independent blocks. Borrowing retains the callback record, not ownership of its raw user data.

pub fn allocate( &mut self, size: u64, alignment: u64, strategy: PlacementStrategy, ) -> Result<VirtualAllocation, AllocError>

Allocate an aligned region. Linear placement ignores the TLSF search strategy.

pub fn allocate_upper( &mut self, size: u64, alignment: u64, ) -> Result<VirtualAllocation, AllocError>

Allocate downward in a linear block. Active ring mode rejects this request.

Errors

Rejects TLSF, invalid extents/alignment, exhausted space or host metadata.

pub fn free( &mut self, allocation: &mut VirtualAllocation, ) -> Result<(), AllocError>

Release a matching live identity. No native resource is destroyed or waited on.

pub fn allocation_info( &self, allocation: &VirtualAllocation, ) -> Result<VirtualAllocationInfo, AllocError>

Validate identity/generation and return the current offset/size snapshot.

pub fn clear(&mut self)

Invalidate all tokens and restore the full range, retaining host capacity. Users of previously returned offsets must stop using them before reuse.

pub fn statistics(&self) -> VirtualBlockStats

Calculate detailed free-span statistics; this is not a constant-time hot path.