Struct Allocator 

pub struct Allocator<'device> { /* private fields */ }

Borrows one device; native memory is released only by explicit operations.

Each allocation has an allocator identity and generation. Dropping either the allocator or a token can leak native objects; it never calls Vulkan.

Implementations

impl<'device> Allocator<'device>

pub unsafe fn set_external_memory_types( &mut self, types: &[ExternalMemoryHandleTypeFlags], ) -> Result<(), AllocError>

Copy an external export profile before any pool/native acquisition.

Errors

Same validation errors as mem::set_external_memory_types.

Safety

All future resources and native allocations must meet the configured export valid usage.

pub fn external_memory_types( &self, allocation: &Allocation, ) -> Result<ExternalMemoryHandleTypeFlags, AllocError>

pub unsafe fn get_memory_fd( &self, allocation: &Allocation, handle_type: ExternalMemoryHandleTypeFlagBits, ) -> Result<RawFd, AllocError>

Export one caller-owned descriptor for the complete backing memory.

Errors

Same checked identity/admission and native failures as mem::get_memory_fd.

Safety

Caller meets sharing/synchronization requirements and closes the returned descriptor.

pub unsafe fn create_pool_with_chain( &mut self, info: &PoolCreateInfo, chain: AllocationChain<'device>, ) -> Result<Pool, AllocError>

Create a custom pool retaining a borrowed chain for future native allocations.

Errors

Same checked policy/chain/native errors as mem::create_pool_with_chain.

Safety

Retain the complete immutable chain for the device borrow; every block must meet native valid usage.

impl Allocator<'_>

pub fn set_debug_memory_settings( &mut self, settings: DebugMemorySettings, ) -> Result<(), AllocError>

Configure opt-in guard/fill instrumentation before acquiring memory/pools.

pub unsafe fn check_corruption(&mut self, bits: u32) -> Result<(), AllocError>

Explicitly inspect enabled coherent pooled debug guards after completion.

Safety

Same all-selected-region access contract as mem::check_corruption.

pub unsafe fn check_pool_corruption( &mut self, pool: &Pool, ) -> Result<(), AllocError>

Inspect one custom pool’s enabled coherent debug guards.

Safety

Same pool completion/access contract as mem::check_pool_corruption.

impl<'device> Allocator<'device>

pub unsafe fn begin_defragmentation<'allocator>( &'allocator mut self, info: &DefragmentationInfo<'_>, ) -> Result<DefragmentationPass<'allocator, 'device>, AllocError>

Begin an explicitly resolved relocation pass over eligible ordinary TLSF allocations.

Safety

Same native resource and explicit completion/commit contract as mem::begin_defragmentation.

pub unsafe fn begin_defragmentation_with_break<'allocator>( &'allocator mut self, info: &DefragmentationInfo<'_>, should_break: &mut dyn FnMut() -> bool, ) -> Result<DefragmentationPass<'allocator, 'device>, AllocError>

Plan with a borrowed stop predicate; interrupted proposals still need resolution.

Safety

Same source/alias/pointer/completion contract as mem::begin_defragmentation_with_break.

pub fn set_allocation_pinned( &mut self, allocation: &Allocation, pinned: bool, ) -> Result<(), AllocError>

Prevent or admit an allocation in future explicit relocation passes.

impl Allocator<'_>

pub fn detailed_pool_statistics( &self, pool: &Pool, ) -> Result<DetailedStatistics, AllocError>

Calculate detailed checked custom-pool native/live/free-span diagnostics.

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

Stream explicit local JSON diagnostics; detailed mode includes allocations/free spans.

pub fn detailed_statistics(&self) -> Result<MemoryStatistics, AllocError>

Calculate explicit per-type/per-heap byte, count, free-span and extent diagnostics.

pub unsafe fn allocate_many( &mut self, requirements: &MemoryRequirements, options: &AllocationCreateInfo<'_>, count: usize, ) -> Result<Vec<Allocation>, AllocError>

Allocate a transactional batch of ordinary raw requirement pages.

Safety

Same requirements/feature/release contract as mem::allocate_many.

pub unsafe fn free_many( &mut self, allocations: &mut [Allocation], ) -> Result<(), AllocError>

Release a fully prevalidated batch after explicit native resource destruction.

Safety

Same completion/ownership contract as mem::free_many.

pub unsafe fn flush_many( &self, ranges: &[CacheRange<'_>], ) -> Result<(), AllocError>

Flush a batch of allocation-relative mapped ranges in one native call.

Safety

Same host/GPU visibility contract as mem::flush_many.

pub unsafe fn invalidate_many( &self, ranges: &[CacheRange<'_>], ) -> Result<(), AllocError>

Invalidate a batch after completion of device writes.

Safety

Same host/GPU visibility contract as mem::invalidate_many.

pub unsafe fn copy_to_allocation( &mut self, allocation: &Allocation, offset: u64, source: &[u8], ) -> Result<(), AllocError>

Copy host bytes, flush and balance the helper’s explicit map hold.

Safety

Same pointer/access/layout contract as mem::copy_to_allocation.

pub unsafe fn copy_from_allocation( &mut self, allocation: &Allocation, offset: u64, destination: &mut [u8], ) -> Result<(), AllocError>

Invalidate and copy bytes to exclusive writable host storage.

Safety

Same completion/initialization contract as mem::copy_from_allocation.

pub fn allocation_name<'a>( &'a self, allocation: &Allocation, ) -> Result<Option<&'a str>, AllocError>

Borrow an allocation’s checked diagnostic name.

pub fn set_allocation_name( &mut self, allocation: &Allocation, name: Option<&str>, ) -> Result<(), AllocError>

Replace a copied name; None clears it.

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

Set opaque consumer metadata, with no ownership or dereference.

pub fn pool_name<'a>( &'a self, pool: &Pool, ) -> Result<Option<&'a str>, AllocError>

Borrow a checked pool’s diagnostic name.

pub fn set_pool_name( &mut self, pool: &Pool, name: Option<&str>, ) -> Result<(), AllocError>

Replace a copied pool name; None clears it.

impl Allocator<'_>

pub fn allocation_callbacks(&self) -> Option<&AllocationCallbacks>

Borrow this allocator’s retained native callbacks for matching explicit resource cleanup.

pub unsafe fn create_aliasing_buffer( &mut self, allocation: &Allocation, local_offset: u64, info: &BufferCreateInfo<'_>, ) -> Result<Buffer, AllocError>

Create and bind a caller-owned buffer alias without allocating memory.

Safety

Same alias/barrier/feature/lifetime contract as mem::create_aliasing_buffer.

pub unsafe fn create_aliasing_image( &mut self, allocation: &Allocation, local_offset: u64, info: &ImageCreateInfo<'_>, ) -> Result<Image, AllocError>

Create and bind a caller-owned image alias without allocating memory.

Safety

Same native alias/layout/barrier contract as mem::create_aliasing_image.

impl<'device> Allocator<'device>

pub unsafe fn set_device_memory_callbacks( &mut self, callbacks: Option<&'device DeviceMemoryCallbacks>, ) -> Result<(), AllocError>

Register borrowed informative callbacks before acquiring native memory/pools.

Errors

Rejects closed allocators or any existing native allocation/pool domain.

Safety

User data must remain live for the callback registration. Functions must not unwind, reenter this allocator or violate their host thread/synchronization contract.

pub fn info(&self) -> Result<AllocatorInfo, AllocError>

Query retained native identity metadata, with explicit None for unknown manual parents.

pub fn memory_properties( &self, ) -> Result<&PhysicalDeviceMemoryProperties, AllocError>

Borrow this allocator’s validated physical memory properties.

pub fn physical_device_properties( &self, ) -> Result<Option<&PhysicalDeviceProperties>, AllocError>

Borrow queried physical-device properties if the construction route captured them.

pub fn memory_type_properties( &self, index: u32, ) -> Result<MemoryPropertyFlags, AllocError>

Query one validated native memory type’s property flags.

impl Allocator<'_>

pub fn find_memory_type( &self, bits: u32, options: &AllocationCreateInfo<'_>, ) -> Result<u32, AllocError>

Select from explicit requirements bits without allocating native storage.

Errors

Same checked policy/type/identity errors as mem::find_memory_type.

pub unsafe fn find_memory_type_for_buffer_info( &self, info: &BufferCreateInfo<'_>, options: &AllocationCreateInfo<'_>, ) -> Result<u32, AllocError>

Select using ordinary buffer creation usage and native requirements.

Safety

Same native valid-usage/lifetime contract as mem::find_memory_type_for_buffer_info.

pub unsafe fn find_memory_type_for_image_info( &self, info: &ImageCreateInfo<'_>, options: &AllocationCreateInfo<'_>, ) -> Result<u32, AllocError>

Select using ordinary image creation usage and native requirements.

Safety

Same native valid-usage/lifetime contract as mem::find_memory_type_for_image_info.

pub unsafe fn allocate_with_options( &mut self, requirements: &MemoryRequirements, options: &AllocationCreateInfo<'_>, ) -> Result<Allocation, AllocError>

Allocate raw separate/pooled storage using the canonical managed placement path.

Safety

Same ordinary requirements, completion and release contract as mem::allocate_with_options.

impl Allocator<'_>

pub unsafe fn allocate_dedicated<'a>( &mut self, requirements: &MemoryRequirements, options: &AllocationCreateInfo<'a>, chain: Option<AllocationChain<'a>>, ) -> Result<Allocation, AllocError>

Allocate separate native storage with a borrowed chain.

Errors

Same checked/native/chain errors as mem::allocate_dedicated.

Safety

Same requirements, chain, import ownership and completion obligations.

pub unsafe fn create_dedicated_buffer<'a>( &mut self, info: &BufferCreateInfo<'_>, options: &AllocationCreateInfo<'a>, chain: Option<AllocationChain<'a>>, ) -> Result<(Buffer, Allocation), AllocError>

Create a separately allocated/bound buffer with an optional native chain.

Errors

Same checked/native/rollback errors as mem::create_dedicated_buffer.

Safety

Same complete resource/allocation external-memory and completion obligations.

pub unsafe fn create_dedicated_image<'a>( &mut self, info: &ImageCreateInfo<'_>, options: &AllocationCreateInfo<'a>, chain: Option<AllocationChain<'a>>, ) -> Result<(Image, Allocation), AllocError>

Create a separately allocated/bound image with an optional native chain.

Errors

Same checked/native/rollback errors as mem::create_dedicated_image.

Safety

Same complete resource/allocation external-memory and completion obligations.

impl Allocator<'_>

pub unsafe fn bind_buffer_memory2( &mut self, buffer: Buffer, allocation: &Allocation, local_offset: u64, next: *const c_void, ) -> Result<(), AllocError>

Bind an ordinary buffer with explicit local offset and borrowed native bind chain.

Safety

Same native chain/resource contract as mem::bind_buffer_memory2.

pub unsafe fn bind_image_memory2( &mut self, image: Image, allocation: &Allocation, local_offset: u64, next: *const c_void, ) -> Result<(), AllocError>

Bind an ordinary image with explicit local offset and borrowed native bind chain.

Safety

Same native chain/resource contract as mem::bind_image_memory2.

pub unsafe fn allocate_for_buffer( &mut self, buffer: Buffer, options: &AllocationCreateInfo<'_>, ) -> Result<Allocation, AllocError>

Allocate for an existing unbound ordinary buffer; retains caller ownership on error.

Safety

Same resource/feature/callback/lifetime contract as mem::allocate_for_buffer.

pub unsafe fn allocate_for_image( &mut self, image: Image, options: &AllocationCreateInfo<'_>, ) -> Result<Allocation, AllocError>

Allocate for an existing ordinary image using conservative unknown-tiling placement.

Safety

Same resource/feature/callback/lifetime contract as mem::allocate_for_image.

pub unsafe fn bind_buffer_memory( &mut self, buffer: Buffer, allocation: &Allocation, ) -> Result<(), AllocError>

Bind a matching buffer/allocation pair; failure retains both for explicit retry.

Safety

Same native unbound-resource and synchronization contract as mem::bind_buffer_memory.

pub unsafe fn bind_image_memory( &mut self, image: Image, allocation: &Allocation, ) -> Result<(), AllocError>

Bind a matching ordinary image/allocation pair; no implicit destruction on failure.

Safety

Same native image/lifetime/synchronization contract as mem::bind_image_memory.

impl Allocator<'_>

pub fn set_heap_limit( &mut self, heap: u32, limit: u64, ) -> Result<(), AllocError>

Set a local native-byte ceiling. Existing allocations are never evicted.

pub fn budget_snapshot(&self) -> BudgetSnapshot

Heap-size/local-accounting estimate, without querying the driver.

pub fn trim(&mut self) -> Result<TrimStats, AllocError>

Release empty, unmapped cached blocks above their pool minimums. No driver budget query, allocation, synchronization or live-object movement.

Errors

Returns Closed after allocator close.

pub unsafe fn trim_with_budget( &mut self, instance: &Instance, physical: PhysicalDevice, ) -> Result<TrimStats, AllocError>

Query budget pressure and release eligible empty blocks on pressured heaps. Minimum blocks and all live/mapped blocks remain owned by their pools.

Errors

Returns closed/context/capability/native query errors before freeing memory.

Safety

Supply the live instance and physical device used to create this allocator’s device.

pub unsafe fn query_budget( &self, instance: &Instance, physical: PhysicalDevice, ) -> Result<BudgetSnapshot, AllocError>

Query enabled EXT_memory_budget; otherwise return an explicitly local estimate.

Safety

Instance/physical device must be the live parent used to create this allocator’s device.

impl Allocator<'_>

pub fn refresh_budget(&mut self) -> Result<BudgetSnapshot, AllocError>

Explicitly refresh allocator-owned native/local budgets.

pub unsafe fn refresh_budget_with_context( &mut self, instance: &Instance, physical: PhysicalDevice, ) -> Result<BudgetSnapshot, AllocError>

Capture a native query context under a retained parent-lifetime contract.

Safety

Same identity/lifetime contract as mem::refresh_budget_with_context.

pub fn heap_budgets(&mut self) -> Result<BudgetSnapshot, AllocError>

Get owned cached/periodically refreshed heap budgets with local native-byte deltas.

pub fn set_current_frame_index(&mut self, index: u32) -> Result<(), AllocError>

Mark an explicit budget frame boundary; no completion or retirement is implied.

pub fn current_frame_index(&self) -> u32

impl Allocator<'_>

pub unsafe fn create_pool( &mut self, info: &PoolCreateInfo, ) -> Result<Pool, AllocError>

Create a fixed-type pool with the selected placement algorithm and minimum blocks.

Errors

Rejects invalid policy/types/limits and preserves metadata/native failures.

Safety

The device/physical metadata and native allocation limits must remain valid.

pub fn destroy_pool(&mut self, pool: &mut Pool) -> Result<(), AllocError>

Release an empty pool and invalidate its identity. Live pooled/dedicated regions are rejected.

pub fn pool_statistics(&self, pool: &Pool) -> Result<PoolStats, AllocError>

Observe checked local pool accounting without native queries.

impl Allocator<'_>

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

Configure large-heap automatic block sizing before any pool/storage creation.

impl Allocator<'_>

pub fn set_mapping_hysteresis( &mut self, enabled: bool, ) -> Result<(), AllocError>

Configure pooled mapping retention before native/pool acquisition.

impl<'device> Allocator<'device>

pub unsafe fn new( device: &'device Device, properties: PhysicalDeviceMemoryProperties, atom: u64, ) -> Result<Self, AllocError>

Construct from caller-supplied physical-device metadata.

Prefer Self::new_from_physical_device for queried properties and the local native-allocation count limit. Managed buffers require the device’s owned creation capabilities; raw imports without them support only the explicitly unsafe low-level allocation route. Without a buffer/image granularity limit, blocks conservatively exclude conflicting image tilings. Use Self::new_with_granularity to supply it.

Safety

Properties and atom size must belong to this device’s physical device. Caller must enforce device allocation size/count limits and enabled features.

pub unsafe fn new_retained( device: Arc<Device>, properties: PhysicalDeviceMemoryProperties, atom: u64, ) -> Result<Allocator<'static>, AllocError>

Construct retaining one shared device context.

The allocator owns an Arc clone of the device, so it may outlive its construction scope and be adopted or destroyed on another thread. Follows Self::new; callback forms stay borrowed-only.

Safety

Properties and atom size must belong to this device’s physical device. Caller must enforce device allocation size/count limits and enabled features.

pub unsafe fn new_with_granularity( device: &'device Device, properties: PhysicalDeviceMemoryProperties, atom: u64, granularity: u64, ) -> Result<Self, AllocError>

Construct from memory properties and both physical-device alignment limits.

Enables mixed buffer/linear/optimal image blocks with checked granularity page separation. Otherwise follows Self::new.

Errors

Rejects invalid memory properties, non-power-of-two limits or missing PFNs.

Safety

Properties, atom (nonCoherentAtomSize) and granularity (bufferImageGranularity) must describe this device’s physical device. The caller enforces native size/count limits, enabled features and lifetimes.

pub unsafe fn new_retained_with_granularity( device: Arc<Device>, properties: PhysicalDeviceMemoryProperties, atom: u64, granularity: u64, ) -> Result<Allocator<'static>, AllocError>

Self::new_with_granularity retaining one shared device context.

Safety

Same metadata and native lifetime contract as new_with_granularity.

pub unsafe fn new_from_physical_device( instance: &Instance, physical_device: PhysicalDevice, device: &'device Device, ) -> Result<Self, AllocError>

Query properties and limits for the selected physical device.

Requires owned instance/device creation metadata and a compatible parent snapshot. It does not discover a logical device’s physical-device identity. Queries the maximum allocation size when core 1.1 or enabled maintenance3 provides it. Legacy 1.0 leaves this limit unknown; see Self::max_allocation_size. The local count limit excludes allocations made by other allocators/raw calls.

Safety

physical_device must belong to instance and be the physical device used to create device. All contexts must remain live; native ownership and host synchronization remain the caller’s responsibility. Unqueried size limits and resource valid usage must still be observed by the caller.

pub unsafe fn new_retained_from_physical_device( instance: &Instance, physical_device: PhysicalDevice, device: Arc<Device>, ) -> Result<Allocator<'static>, AllocError>

Self::new_from_physical_device retaining one shared device context.

Safety

physical_device must belong to instance and be the physical device used to create device. Native ownership and host synchronization remain the caller’s responsibility.

pub unsafe fn new_with_callbacks( device: &'device Device, properties: PhysicalDeviceMemoryProperties, atom: u64, callbacks: &'device AllocationCallbacks, ) -> Result<Self, AllocError>

Construct with borrowed callbacks for native effects and CPU metadata. Callback storage is borrowed for the allocator’s complete borrow lifetime.

Errors

Same metadata/PFN errors as new; rejects missing host allocation/free functions.

Safety

All new requirements apply. Callbacks/user data must remain valid and satisfy Vulkan alignment, thread, reentrancy and non-unwinding contracts. They are used consistently for native allocation, creation and rollback; CPU metadata uses the allocation/free pair with OBJECT scope. The inline allocator and non-owning tokens need no heap identity. Returned Vec output collections and caller-owned writers retain their Rust allocation policy. Callback free may run while host metadata is dropped; it never frees native Vulkan objects implicitly.

pub unsafe fn new_from_physical_device_with_callbacks( instance: &Instance, physical_device: PhysicalDevice, device: &'device Device, callbacks: &'device AllocationCallbacks, ) -> Result<Self, AllocError>

Query limits and retain matching caller-owned native allocation callbacks.

Errors

Same provenance/property/PFN errors as new_from_physical_device.

Safety

Match the physical-device constructor’s identity/lifetime contract and the callback lifetime/alignment/thread/reentrancy contract of new_with_callbacks.

pub fn live_count(&self) -> usize

pub fn is_closed(&self) -> bool

pub fn max_allocation_size(&self) -> Option<u64>

Queried native per-allocation size ceiling, or unknown on the caller-supplied metadata route and legacy 1.0 without admitted maintenance3 properties. A known ceiling is not a promise of available heap space or allocation success.

pub fn close(&mut self) -> Result<(), AllocError>

Close only when all allocations have been explicitly released; repeat close succeeds.

pub unsafe fn allocate( &mut self, request: &AllocRequest, ) -> Result<Allocation, AllocError>

Allocate separate native storage without a resource-specific allocation chain.

Safety

Request must satisfy resource requirements and device size/count limits. External and required-dedication semantics are excluded. Protected storage requires captured enabled feature metadata and explicit required flags. Owned core/KHR device-address enablement automatically flags raw storage.

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

Safety

Destroy every bound resource and complete all GPU/host accesses first.

pub unsafe fn map( &mut self, allocation: &Allocation, ) -> Result<*mut c_void, AllocError>

Acquire one explicit mapping hold; every successful call needs one unmap.

Safety

Synchronize host/GPU access; returned pointers cannot outlive the mapping.

pub unsafe fn unmap( &mut self, allocation: &Allocation, ) -> Result<(), AllocError>

Safety

No pointer into this mapping may be used after unmapping.

pub unsafe fn flush( &self, allocation: &Allocation, offset: u64, size: u64, ) -> Result<(), AllocError>

Safety

Mapping and accesses must satisfy Vulkan host/device synchronization rules.

pub unsafe fn invalidate( &self, allocation: &Allocation, offset: u64, size: u64, ) -> Result<(), AllocError>

Safety

Complete device writes before invalidating and do not race host accesses.

pub unsafe fn create_buffer( &mut self, info: &BufferCreateInfo<'_>, required: MemoryPropertyFlags, preferred: MemoryPropertyFlags, ) -> Result<(Buffer, Allocation), AllocError>

Create, allocate and bind an ordinary buffer transactionally.

Safety

Info must satisfy device limits/valid usage. Sparse, external and arbitrary pNext chains are not admitted. Protected resources need captured enabled feature metadata and matching creation flags. Device-address usage requires captured enabled core/KHR feature metadata.

pub unsafe fn destroy_buffer( &mut self, buffer: Buffer, allocation: &mut Allocation, ) -> Result<(), AllocError>

Destroy a matching managed buffer before freeing its allocation.

Safety

Complete every CPU/GPU use; do not separately destroy this buffer first. The buffer must use this allocator’s callbacks; otherwise destroy it directly then free.

pub unsafe fn create_buffer_with_options( &mut self, info: &BufferCreateInfo<'_>, options: &AllocationCreateInfo<'_>, ) -> Result<(Buffer, Allocation), AllocError>

Create and bind an ordinary buffer using explicit separate/pooled policy.

Safety

Same native valid-usage, completion and synchronization obligations as create_buffer.

pub unsafe fn create_image( &mut self, info: &ImageCreateInfo<'_>, required: MemoryPropertyFlags, preferred: MemoryPropertyFlags, ) -> Result<(Image, Allocation), AllocError>

Create and bind an image using separate storage and explicit memory properties.

Safety

All image/create-chain valid usage and host/GPU lifetimes remain caller obligations.

pub unsafe fn create_image_with_options( &mut self, info: &ImageCreateInfo<'_>, options: &AllocationCreateInfo<'_>, ) -> Result<(Image, Allocation), AllocError>

Create, allocate and bind an image using explicit or automatic memory policy.

Safety

Match native image, feature, pointer-chain and synchronization valid usage.

pub unsafe fn destroy_image( &mut self, image: Image, allocation: &mut Allocation, ) -> Result<(), AllocError>

Destroy a managed image and release its allocation after exact completion.

Safety

Destroy views first; complete all host/GPU uses and end explicit maps. The image must use this allocator’s callbacks; otherwise destroy it directly then free.

pub fn mapped_pointer( &self, allocation: &Allocation, ) -> Result<Option<*mut c_void>, AllocError>

Observe a current explicit or persistent mapping without acquiring a hold.

pub fn allocation_info( &self, allocation: &Allocation, ) -> Result<AllocationInfo, AllocError>

Query checked binding metadata and this region’s current mapping without native calls.

Errors

Returns Closed, WrongAllocator or UnknownAllocation for invalid identity/state.

pub fn statistics(&self) -> AllocatorStats