Skip to main content

Module mem

Module mem 

Source
Expand description

Rust-native, VMA-derived allocation, managed buffers/images and virtual placement.

Free functions and Allocator methods share one implementation. For example, create_buffer_with_options and Allocator::create_buffer_with_options create, allocate and bind a managed buffer. The root crate::create_buffer is the raw Vulkan operation and creates an unbound buffer.

Use use vk::mem as vma; for a caller-local alias. This adds no wrapper, runtime cost or second allocator type; crate::Allocator is Allocator. Full VMA equivalence, broad concurrent stress, multi-driver execution and additional platforms remain unqualified. See the qualification report.

Every public field on a plain record has a consuming set_*() method alongside direct field access. Default-backed records support new().set_*(); AllocRequest, ImportMemoryInfo and CacheRange take required inputs in new. Setters retain borrows and leave validation to the using operation. Editing a diagnostic snapshot changes only that record, never live allocator state. Resource identities and owners retain their checked operation APIs.

Allocator operations do not submit or wait. GPU completion, resource destruction and host/GPU access ordering remain caller responsibilities.

Re-exports§

pub use virtual_block::PlacementStrategy;
pub use virtual_block::VirtualAllocation;
pub use virtual_block::VirtualAllocationInfo;
pub use virtual_block::VirtualBlock;
pub use virtual_block::VirtualBlockDetails;
pub use virtual_block::VirtualBlockStats;

Modules§

virtual_block
Host-only region placement over an integer byte range.

Structs§

AllocRequest
Allocation
One live native region. No implicit free, unmap, submission or wait in Drop.
AllocationChain
A caller-owned VkMemoryAllocateInfo::pNext chain.
AllocationCreateInfo
Managed-resource policy, including optional borrowed native allocation storage; this Rust record is not part of the Vulkan ABI.
AllocationInfo
Checked binding and mapping snapshot of one live allocation.
Allocator
Borrows one device; native memory is released only by explicit operations.
AllocatorInfo
Captured native identities. Manual metadata constructors do not invent parent identities.
AllocatorStats
Local accounting snapshot; excludes allocations made by other allocators/raw calls.
BudgetSnapshot
CacheRange
One allocation-relative cache range. Each allocation must own a mapping hold.
DebugMemorySettings
Opt-in host-visible debug instrumentation, configured before native acquisition. Guard margins follow VMA’s coherent pooled-memory policy. Zero disables guards.
DefragmentationContext
Persistent multi-pass relocation state with one exclusive allocator borrow. Ignored allocations stay immovable for subsequent passes in this context. Each pass must be explicitly resolved and finished; neither context nor pass Drop submits, waits or destroys native resources. An abandoned unresolved pass leaks its reservations, as documented by DefragmentationPass.
DefragmentationInfo
Bounded relocation planning. Zero limits produce an empty pass.
DefragmentationMove
Borrow-free binding snapshots. They do not retain resources or mappings. Mapped pointers describe counted holds owned by the pass’s live regions. Source pointers expire on commit/destroy, destination pointers on ignore/destroy; copied snapshots extend no lifetime.
DefragmentationPass
Exclusively borrows the allocator while replacement resources are prepared.
DefragmentationStats
Actual completed work; proposed or ignored moves are not counted as moved bytes.
DetailedStatistics
Detailed local byte/count statistics. Empty populations have None extrema.
DeviceMemoryCallbacks
Informative notifications for actual native memory allocation/free effects. Callbacks do not allocate Rust metadata and do not own the native memory.
HeapBudget
One heap at the explicit snapshot boundary. Budget/usage can change immediately.
ImportMemoryInfo
Actual external backing extent and compatible types for one import.
MemoryPriority
Finite native memory priority in the inclusive range 0..=1.
MemoryStatistics
Explicit diagnostic snapshot, indexed by native memory type and heap.
MemoryTypeSelector
Validated device memory properties and non-coherent atom size.
Pool
Identity of one live custom pool. Dropping it never destroys native storage.
PoolCreateInfo
Fixed-type ordinary-memory pool; not a Vulkan ABI record.
PoolStats
Local pool statistics. No native budget query or host allocation is performed. Free spans describe physical holes; alignment/granularity may prevent their use. Linear holes additionally wait for their stack/ring lifetime to retire. Counts/bytes include pool-owned dedicated allocations and retained empty blocks.
SynchronizedAllocator
One allocator with synchronized direct operations and concurrent pool scopes.
SynchronizedVirtualBlock
One virtual block with serialized operation access from any host thread.
TrimStats
Native cache released by one explicit maintenance call. Live regions never move.

Enums§

AllocError
AllocationAlgorithm
Placement metadata for custom pools and host-only virtual blocks.
AllocationPolicy
Managed resource storage policy. Required or preferred native dedication takes precedence.
BudgetSource
Budget provenance. Heap-size/local accounting does not measure external pressure.
DefragmentationAlgorithm
Existing-block relocation policy, derived from the pinned VMA algorithms.
DefragmentationResource
Allocator-recorded primary resource, or raw storage, associated with a move.
HostAccess
CPU access intent used by automatic memory selection; never submits a transfer.
ImportResource
Resource-specific native dedication for an imported payload. The resource remains caller-owned; this record never destroys it.
MemoryUsage
Policy for managed resources. Raw allocation always uses explicit flags.

Functions§

allocate⚠
Allocate separate native storage with automatically admitted allocation flags.
allocate_dedicated⚠
Allocate separate native storage with an optional borrowed allocation chain. Equivalent to allocate_with_options with dedicated_memory enabled.
allocate_for_buffer⚠
Allocate for a caller-created unbound ordinary buffer without creating, binding or destroying it.
allocate_for_image⚠
Allocate for a caller-created unbound ordinary image; no creation, binding or destruction.
allocate_many⚠
Allocate identical ordinary requirement pages; failure releases new pages only.
allocate_with_options⚠
Allocate unbound ordinary storage from native requirements with explicit policy.
allocation_info
Snapshot one live allocation’s binding, actual properties and current mapping.
allocation_name
Borrow an allocation’s diagnostic name; no native lifetime is acquired.
allocator_info
Observe captured native identities without inferring manually omitted parent metadata.
begin_defragmentation⚠
Reserve earlier free storage without creating native resources, growing blocks or copying data.
begin_defragmentation_with_break⚠
Plan a pass with a borrowed cooperative stop predicate, following VMA’s pfnBreakCallback / CheckCounters contract. Returning true stops scheduling; already proposed moves still need explicit resolution. Use was_interrupted to distinguish a stop from an exhausted search. Polls occur between source candidates, after host snapshot/preflight, and never during consumer copies. A panic rolls back unpublished destinations before unwinding (with panic=unwind). The callback is used only during this call and cannot borrow this allocator.
bind_buffer_memory⚠
Bind at the allocation’s actual native offset. Failed binds retain allocation and resource for retry.
bind_buffer_memory2⚠
Bind one ordinary buffer with a checked allocation-local offset and borrowed native chain.
bind_image_memory⚠
Bind a live ordinary image at its allocation’s native offset; failure retains both objects.
bind_image_memory2⚠
Bind an ordinary image or one disjoint plane with an allocation-local offset and native chain. A plane uses unassociated raw storage allocated from caller-queried plane requirements. The allocator re-queries that exact plane before binding and tracks each plane independently; DRM modifier plane aspects remain excluded.
budget_snapshot
Local accounting is always distinguished from implementation-reported usage.
check_corruption⚠
Check enabled coherent pooled guard tails without waiting for GPU work.
check_pool_corruption⚠
Check coherent guard tails belonging to one checked custom pool.
close
Checked shutdown after all regions and their blocks have been explicitly released.
copy_from_allocation⚠
Invalidate and copy allocation bytes to initialized writable host storage.
copy_to_allocation⚠
Copy host bytes to an allocation, flush them and release only this helper’s map hold.
create_aliasing_buffer⚠
Create an ordinary alias buffer at a checked allocation-local offset.
create_aliasing_image⚠
Create a caller-owned ordinary alias image without allocating new native memory.
create_buffer⚠
Transactionally create, query, allocate and bind an ordinary buffer.
create_buffer_with_options⚠
Create, allocate, optionally map and bind an ordinary buffer transactionally.
create_dedicated_buffer⚠
Create, separately allocate and bind a buffer, optionally importing/exporting memory.
create_dedicated_image⚠
Create, separately allocate and bind an ordinary non-disjoint image with an optional chain.
create_image⚠
Create an ordinary image with separate storage and explicit memory properties.
create_image_with_options⚠
Create, query, allocate, optionally map and bind a non-disjoint image transactionally.
create_pool⚠
Create a fixed-memory-type TLSF pool transactionally.
create_pool_with_chain⚠
Create a pool retaining a borrowed native allocation chain for every block. Import chains are rejected: a single imported payload cannot back repeated growth.
destroy_buffer⚠
Destroy a matching resource pair in buffer-before-memory order with matching retained callbacks.
destroy_image⚠
Destroy the exact image/token pair with matching retained callbacks before freeing memory.
destroy_pool
Destroy an empty pool, releasing its retained native blocks explicitly.
detailed_pool_statistics
Walk actual blocks/live regions belonging to one checked custom pool.
detailed_statistics
Walk actual native blocks and live regions to build detailed local statistics.
external_memory_types
Observe the export flags retained for this allocation’s entire native block.
find_memory_type
Select from explicit native memory-type bits without allocating or querying a budget.
find_memory_type_for_buffer_info⚠
Select memory for an ordinary buffer using its actual creation usage and requirements.
find_memory_type_for_image_info⚠
Select memory for an ordinary non-disjoint image from creation usage and native requirements.
flush⚠
Flush a bounded allocation-relative mapped range, observing atom/end rules.
flush_many⚠
Flush checked ranges in one native call; coherent/empty ranges remain checked no-ops.
free⚠
Release a separate allocation or pooled placement and invalidate its token.
free_many⚠
Validate an entire release batch before freeing any allocation.
get_memory_fd⚠
Export a new caller-owned file descriptor for the complete backing memory. Allocation offsets still apply. Close the returned descriptor using the OS; neither token nor allocator owns it. No GPU synchronization occurs.
heap_budgets
Return an owned cached budget, refreshed on frame changes or after 30 region operations.
invalidate⚠
Invalidate a bounded allocation-relative mapped range; never waits for the GPU.
invalidate_many⚠
Invalidate checked ranges in one native call; never waits for device writes.
map⚠
Map one allocation. Distinct regions share a reference-counted block mapping. Repeated explicit maps acquire checked holds on the same native mapping.
mapped_pointer
Return a region pointer only if that region has an explicit or persistent hold. Does not map, acquire a hold, synchronize, or authorize pointer dereferences.
memory_properties
Borrow validated native memory metadata used by this allocator’s selection policy.
memory_type_properties
Observe one checked native memory type’s actual property flags.
physical_device_properties
Borrow queried physical-device properties, or None after manual metadata construction.
pool_name
Borrow a custom pool’s copied diagnostic name without native effects.
pool_statistics
Query a pool’s local native bytes, placements and free ranges.
query_budget⚠
Return an explicit native budget snapshot without caching admission decisions.
refresh_budget
Refresh an allocator-owned budget snapshot from the retained native context.
refresh_budget_with_context⚠
Capture a checked budget context for future refreshes, including manual constructors.
set_allocation_name
Replace a copied UTF-8 diagnostic name transactionally; None clears it.
set_allocation_pinned
Explicitly pin/unpin a region against future allocator relocation planning.
set_allocation_user_data
Set uninterpreted consumer metadata. It is never dereferenced, freed or owned.
set_current_frame_index
Mark a frame boundary for budget refresh; this never retires resources or waits.
set_debug_memory_settings
Configure debug instrumentation before native allocations or pools exist.
set_external_memory_types⚠
Configure copied per-memory-type external export flags before creating pools/storage. Zero flags leave that type ordinary. Every native allocation of a configured type receives VkExportMemoryAllocateInfo, including separate allocations.
set_heap_limit
Change a local policy ceiling; this never reserves native heap capacity.
set_mapping_hysteresis
Configure native pooled mapping retention before creating storage or pools. Enabled by default. Separate allocations never cache mappings. This affects native map/unmap call counts, never allocation-level pointer access rights.
set_pool_name
Replace a pool diagnostic name; metadata allocation failure preserves its old name.
set_preferred_block_size
Set preferred block bytes for heaps larger than 1 GiB before pool/storage creation. Small heaps use one eighth of their heap size; both paths round up to 32 bytes. Does not alter explicit Pooled/Adaptive policies or query/reserve a budget.
statistics
Calculate local live-region/native-block accounting without querying the driver.
trim
Release surplus empty, unmapped cached blocks, preserving each pool minimum.
trim_with_budget⚠
Query an explicit budget snapshot, then trim surplus empty blocks on pressured heaps.
unmap⚠
Release one explicit map; persistent holds and other regions remain mapped.
write_statistics_json
Write ordered local allocator diagnostics as vk.memory.statistics.v1 JSON.