vk::mem · Structs · S1

2 public declarations with native signatures and source-owned contracts.

StRustExperimental

Stvk::mem::SynchronizedAllocator

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

One allocator with synchronized direct operations and concurrent pool scopes.

Contract

One allocator with synchronized direct operations and concurrent pool scopes.

Placement uses one mutex per owner. Direct map/unmap/bind operations acquire a live allocation lease, then execute under that backing’s stable mutex without the placement mutex. Other backings can map/bind, allocate and free concurrently, including inside the same pool. Regions sharing one backing serialize native map/bind work and retain exact explicit/persistent counts. The first such operation fallibly reserves callback-owned backing metadata.

Borrowed results, relocation and global services use exclusive access and wait for outstanding native leases. try_with_allocator reports busy during those leases. Borrowed pool/type/block scopes add independent placement owners for their documented domains. There is no process-global lock or new Send/Sync assertion on ordinary Allocator. Performance is unmeasured. Callbacks must never reenter this owner or create cross-owner lock cycles. Vulkan completion and mapped-byte synchronization remain caller obligations. Drop frees CPU metadata only; explicitly close native storage before Drop. A scoped operation cannot return its allocator borrow:

ⓘ

let escaped = unsafe { shared.with_allocator(|allocator| allocator) };

An existing ordinary allocator’s device borrow may still be shortened:

fn shorten<'device: 'scope, 'scope>(owner: vk::Allocator<'device>) -> vk::Allocator<'scope> {
    owner
}

The ordinary allocator remains non-Send:

ⓘ

fn require_send<T: Send>() {}
require_send::<vk::Allocator<'static>>();

// SAFETY: retained chains/callbacks and mapped storage satisfy new's
// any-thread contract through final host cleanup.
let shared = unsafe { vk::SynchronizedAllocator::new(allocator) };
std::thread::scope(|scope| {
    scope.spawn(|| {
        // SAFETY: no replacement/thread-affine state is installed; no
        // native work is live and ordinary close preconditions hold.
        unsafe { shared.with_allocator(|allocator| allocator.close()) }??;
        Ok::<_, vk::AllocError>(())
    }).join().unwrap()
})?;

Methods and associated items

live_count

Method

pub fn live_count(&self) -> Result<usize, AllocError>

Number of live allocation registrations under this allocator’s lock.

Errors

Returns SynchronizationPoisoned after a closure panic.

is_closed

Method

pub fn is_closed(&self) -> Result<bool, AllocError>

Observe explicit close state under this allocator’s lock.

Errors

Returns SynchronizationPoisoned after a closure panic.

max_allocation_size

Method

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

Optional caller-configured size limit under this allocator’s lock.

Errors

Returns SynchronizationPoisoned after a closure panic.

close

Method

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

Close the allocator under its lock; later access reports Closed. Concurrent operations complete or fail before this runs.

Errors

Same live-resource errors as Allocator::close, plus SynchronizationPoisoned.

allocator_info

Method

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

Captured native identities under this allocator’s lock.

Errors

Same errors as Allocator::allocator_info, plus SynchronizationPoisoned.

memory_type_properties

Method

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

Queried properties of one native memory type under this allocator’s lock.

Errors

Same errors as Allocator::memory_type_properties, plus SynchronizationPoisoned.

find_memory_type

Method

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

Score memory types for one allocation request under this allocator’s lock.

Errors

Same errors as Allocator::find_memory_type, plus SynchronizationPoisoned.

find_memory_type_for_buffer_info

Method

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

Score memory types for one buffer’s requirements under this allocator’s lock.

Errors

Same errors as Allocator::find_memory_type_for_buffer_info, plus SynchronizationPoisoned.

Safety

Same create-chain and requirement query contract as Allocator::find_memory_type_for_buffer_info.

find_memory_type_for_image_info

Method

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

Score memory types for one image’s requirements under this allocator’s lock.

Errors

Same errors as Allocator::find_memory_type_for_image_info, plus SynchronizationPoisoned.

Safety

Same create-chain and requirement query contract as Allocator::find_memory_type_for_image_info.

allocate

Method

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

Run Allocator::allocate under this allocator’s lock.

Errors

Same checked/native errors as Allocator::allocate, plus SynchronizationPoisoned.

Safety

Same request/chain/import and completion contract as Allocator::allocate.

allocate_with_options

Method

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

Run Allocator::allocate_with_options under this allocator’s lock.

Errors

Same checked/native errors as Allocator::allocate_with_options, plus SynchronizationPoisoned.

Safety

Same requirements/options/chain contract as Allocator::allocate_with_options.

allocate_dedicated

Method

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

Run Allocator::allocate_dedicated under this allocator’s lock.

Errors

Same checked/native errors as Allocator::allocate_dedicated, plus SynchronizationPoisoned.

Safety

Same requirements/chain/import contract as Allocator::allocate_dedicated.

allocate_many

Method

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

Run Allocator::allocate_many under this allocator’s lock.

Errors

Same checked/native errors as Allocator::allocate_many, plus SynchronizationPoisoned.

Safety

Same requirements/options contract as Allocator::allocate_many.

free

Method

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

Run Allocator::free under this allocator’s lock.

Errors

Same checked/native errors as Allocator::free, plus SynchronizationPoisoned.

Safety

Same live-token, mapped-byte and completion contract as Allocator::free.

free_many

Method

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

Run Allocator::free_many under this allocator’s lock.

Errors

Same checked/native errors as Allocator::free_many, plus SynchronizationPoisoned.

Safety

Same live-token and completion contract as Allocator::free_many.

allocation_info

Method

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

Checked allocation snapshot under this allocator’s lock.

Errors

Same errors as Allocator::allocation_info, plus SynchronizationPoisoned.

set_allocation_pinned

Method

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

Run Allocator::set_allocation_pinned under this allocator’s lock.

Errors

Same errors as Allocator::set_allocation_pinned, plus SynchronizationPoisoned.

set_allocation_name

Method

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

Run Allocator::set_allocation_name under this allocator’s lock.

Errors

Same errors as Allocator::set_allocation_name, plus SynchronizationPoisoned.

set_allocation_user_data

Method

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

Run Allocator::set_allocation_user_data under this allocator’s lock.

Errors

Same errors as Allocator::set_allocation_user_data, plus SynchronizationPoisoned.

create_buffer

Method

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

Run Allocator::create_buffer under this allocator’s lock.

Errors

Same transaction errors as Allocator::create_buffer, plus SynchronizationPoisoned.

Safety

Same resource/allocation contract as Allocator::create_buffer.

create_buffer_with_options

Method

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

Run Allocator::create_buffer_with_options under this allocator’s lock.

Errors

Same transaction errors as Allocator::create_buffer_with_options, plus SynchronizationPoisoned.

Safety

Same resource/allocation contract as Allocator::create_buffer_with_options.

create_dedicated_buffer

Method

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

Run Allocator::create_dedicated_buffer under this allocator’s lock.

Errors

Same transaction errors as Allocator::create_dedicated_buffer, plus SynchronizationPoisoned.

Safety

Same resource/chain/import contract as Allocator::create_dedicated_buffer.

destroy_buffer

Method

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

Run Allocator::destroy_buffer under this allocator’s lock.

Errors

Same checked errors as Allocator::destroy_buffer, plus SynchronizationPoisoned.

Safety

Same resource ownership and completion contract as Allocator::destroy_buffer.

create_image

Method

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

Run Allocator::create_image under this allocator’s lock.

Errors

Same transaction errors as Allocator::create_image, plus SynchronizationPoisoned.

Safety

Same resource/allocation contract as Allocator::create_image.

create_image_with_options

Method

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

Run Allocator::create_image_with_options under this allocator’s lock.

Errors

Same transaction errors as Allocator::create_image_with_options, plus SynchronizationPoisoned.

Safety

Same resource/allocation contract as Allocator::create_image_with_options.

create_dedicated_image

Method

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

Run Allocator::create_dedicated_image under this allocator’s lock.

Errors

Same transaction errors as Allocator::create_dedicated_image, plus SynchronizationPoisoned.

Safety

Same resource/chain/import contract as Allocator::create_dedicated_image.

destroy_image

Method

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

Run Allocator::destroy_image under this allocator’s lock.

Errors

Same checked errors as Allocator::destroy_image, plus SynchronizationPoisoned.

Safety

Same resource ownership and completion contract as Allocator::destroy_image.

allocate_for_buffer

Method

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

Run Allocator::allocate_for_buffer under this allocator’s lock.

Errors

Same checked/native errors as Allocator::allocate_for_buffer, plus SynchronizationPoisoned.

Safety

Same external-resource and allocation contract as Allocator::allocate_for_buffer.

allocate_for_image

Method

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

Run Allocator::allocate_for_image under this allocator’s lock.

Errors

Same checked/native errors as Allocator::allocate_for_image, plus SynchronizationPoisoned.

Safety

Same external-resource and allocation contract as Allocator::allocate_for_image.

create_aliasing_buffer

Method

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

Run Allocator::create_aliasing_buffer under this allocator’s lock.

Errors

Same checked errors as Allocator::create_aliasing_buffer, plus SynchronizationPoisoned.

Safety

Same alias/storage contract as Allocator::create_aliasing_buffer.

create_aliasing_image

Method

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

Run Allocator::create_aliasing_image under this allocator’s lock.

Errors

Same checked errors as Allocator::create_aliasing_image, plus SynchronizationPoisoned.

Safety

Same alias/storage contract as Allocator::create_aliasing_image.

copy_to_allocation

Method

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

Run Allocator::copy_to_allocation under this allocator’s lock.

Errors

Same checked errors as Allocator::copy_to_allocation, plus SynchronizationPoisoned.

Safety

Same mapped-range and byte-validity contract as Allocator::copy_to_allocation.

copy_from_allocation

Method

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

Run Allocator::copy_from_allocation under this allocator’s lock.

Errors

Same checked errors as Allocator::copy_from_allocation, plus SynchronizationPoisoned.

Safety

Same mapped-range and byte-validity contract as Allocator::copy_from_allocation.

bind_buffer_memory

Method

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

Run Allocator::bind_buffer_memory under a live lease and this backing’s mutex.

Errors

Same checked errors as Allocator::bind_buffer_memory, plus SynchronizationPoisoned.

Safety

Same native binding contract as Allocator::bind_buffer_memory.

bind_image_memory

Method

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

Run Allocator::bind_image_memory under a live lease and this backing’s mutex.

Errors

Same checked errors as Allocator::bind_image_memory, plus SynchronizationPoisoned.

Safety

Same native binding contract as Allocator::bind_image_memory.

bind_buffer_memory2

Method

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

Run Allocator::bind_buffer_memory2 under a live lease and this backing’s mutex.

Errors

Same checked errors as Allocator::bind_buffer_memory2, plus SynchronizationPoisoned.

Safety

Same native chain/binding contract as Allocator::bind_buffer_memory2.

bind_image_memory2

Method

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

Run Allocator::bind_image_memory2 under a live lease and this backing’s mutex.

Errors

Same checked errors as Allocator::bind_image_memory2, plus SynchronizationPoisoned.

Safety

Same native chain/binding contract as Allocator::bind_image_memory2.

map

Method

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

Run Allocator::map under a live lease and this backing’s mutex.

Errors

Same checked/native errors as Allocator::map, plus SynchronizationPoisoned.

Safety

May fail to reserve the stable backing metadata before native effects. Same mapping, mapped-byte synchronization and completion contract as Allocator::map; escaping pointers retain SynchronizedAllocator rules.

unmap

Method

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

Run Allocator::unmap under a live lease and this backing’s mutex.

Errors

Same checked errors as Allocator::unmap, plus SynchronizationPoisoned.

Safety

Same mapped-byte and completion contract as Allocator::unmap.

mapped_pointer

Method

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

Current mapping pointer for one allocation under this allocator’s lock.

Errors

Same errors as Allocator::mapped_pointer, plus SynchronizationPoisoned.

flush

Method

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

Run Allocator::flush under this allocator’s lock.

Errors

Same checked/native errors as Allocator::flush, plus SynchronizationPoisoned.

Safety

Same cache-range and completion contract as Allocator::flush.

invalidate

Method

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

Run Allocator::invalidate under this allocator’s lock.

Errors

Same checked/native errors as Allocator::invalidate, plus SynchronizationPoisoned.

Safety

Same cache-range and completion contract as Allocator::invalidate.

flush_many

Method

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

Run Allocator::flush_many under this allocator’s lock.

Errors

Same checked/native errors as Allocator::flush_many, plus SynchronizationPoisoned.

Safety

Same cache-range contract as Allocator::flush_many.

invalidate_many

Method

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

Run Allocator::invalidate_many under this allocator’s lock.

Errors

Same checked/native errors as Allocator::invalidate_many, plus SynchronizationPoisoned.

Safety

Same cache-range contract as Allocator::invalidate_many.

set_heap_limit

Method

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

Run Allocator::set_heap_limit under this allocator’s lock.

Errors

Same errors as Allocator::set_heap_limit, plus SynchronizationPoisoned.

budget_snapshot

Method

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

Cached budget snapshot under this allocator’s lock.

Errors

Returns SynchronizationPoisoned after a closure panic.

query_budget

Method

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

Run Allocator::query_budget under this allocator’s lock.

Errors

Same errors as Allocator::query_budget, plus SynchronizationPoisoned.

Safety

Same instance/physical-device and PFN contract as Allocator::query_budget.

refresh_budget

Method

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

Run Allocator::refresh_budget under this allocator’s lock.

Errors

Same errors as Allocator::refresh_budget, plus SynchronizationPoisoned.

refresh_budget_with_context

Method

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

Run Allocator::refresh_budget_with_context under this allocator’s lock.

Errors

Same errors as Allocator::refresh_budget_with_context, plus SynchronizationPoisoned.

Safety

Same context/PFN contract as Allocator::refresh_budget_with_context.

heap_budgets

Method

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

Run Allocator::heap_budgets under this allocator’s lock.

Errors

Same errors as Allocator::heap_budgets, plus SynchronizationPoisoned.

set_current_frame_index

Method

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

Run Allocator::set_current_frame_index under this allocator’s lock.

Errors

Same errors as Allocator::set_current_frame_index, plus SynchronizationPoisoned.

current_frame_index

Method

pub fn current_frame_index(&self) -> Result<u32, AllocError>

Current frame index under this allocator’s lock.

Errors

Returns SynchronizationPoisoned after a closure panic.

trim

Method

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

Run Allocator::trim under this allocator’s lock.

Errors

Same errors as Allocator::trim, plus SynchronizationPoisoned.

trim_with_budget

Method

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

Run Allocator::trim_with_budget under this allocator’s lock.

Errors

Same errors as Allocator::trim_with_budget, plus SynchronizationPoisoned.

Safety

Same instance/physical-device and PFN contract as Allocator::trim_with_budget.

create_pool

Method

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

Run Allocator::create_pool under this allocator’s lock.

Errors

Same checked/native errors as Allocator::create_pool, plus SynchronizationPoisoned.

Safety

Same policy/storage contract as Allocator::create_pool.

create_pool_with_chain

Method

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

Run Allocator::create_pool_with_chain under this allocator’s lock.

Errors

Same checked/native errors as Allocator::create_pool_with_chain, plus SynchronizationPoisoned.

Safety

Same retained-chain contract as Allocator::create_pool_with_chain; the chain must also satisfy SynchronizedAllocator::new’s any-thread rules.

destroy_pool

Method

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

Run Allocator::destroy_pool under this allocator’s lock.

Errors

Same live-resource errors as Allocator::destroy_pool, plus SynchronizationPoisoned.

pool_statistics

Method

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

One pool’s statistics under this allocator’s lock.

Errors

Same errors as Allocator::pool_statistics, plus SynchronizationPoisoned.

set_pool_name

Method

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

Run Allocator::set_pool_name under this allocator’s lock.

Errors

Same errors as Allocator::set_pool_name, plus SynchronizationPoisoned.

set_preferred_block_size

Method

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

Run Allocator::set_preferred_block_size under this allocator’s lock.

Errors

Same errors as Allocator::set_preferred_block_size, plus SynchronizationPoisoned.

set_mapping_hysteresis

Method

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

Run Allocator::set_mapping_hysteresis under this allocator’s lock.

Errors

Same errors as Allocator::set_mapping_hysteresis, plus SynchronizationPoisoned.

detailed_statistics

Method

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

Aggregate memory statistics under this allocator’s lock.

Errors

Same errors as Allocator::detailed_statistics, plus SynchronizationPoisoned.

detailed_pool_statistics

Method

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

One pool’s detailed statistics under this allocator’s lock.

Errors

Same errors as Allocator::detailed_pool_statistics, plus SynchronizationPoisoned.

write_statistics_json

Method

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

Run Allocator::write_statistics_json under this allocator’s lock.

Errors

Same errors as Allocator::write_statistics_json, plus SynchronizationPoisoned.

set_debug_memory_settings

Method

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

Run Allocator::set_debug_memory_settings under this allocator’s lock.

Errors

Same errors as Allocator::set_debug_memory_settings, plus SynchronizationPoisoned.

check_corruption

Method

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

Run Allocator::check_corruption under this allocator’s lock.

Errors

Same checked errors as Allocator::check_corruption, plus SynchronizationPoisoned.

Safety

Same guard-pattern byte-validity contract as Allocator::check_corruption.

check_pool_corruption

Method

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

Run Allocator::check_pool_corruption under this allocator’s lock.

Errors

Same checked errors as Allocator::check_pool_corruption, plus SynchronizationPoisoned.

Safety

Same guard-pattern byte-validity contract as Allocator::check_pool_corruption.

set_external_memory_types

Method

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

Run Allocator::set_external_memory_types under this allocator’s lock.

Errors

Same errors as Allocator::set_external_memory_types, plus SynchronizationPoisoned.

Safety

Same capability/creation contract as Allocator::set_external_memory_types.

external_memory_types

Method

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

One allocation’s external handle types under this allocator’s lock.

Errors

Same errors as Allocator::external_memory_types, plus SynchronizationPoisoned.

get_memory_fd

Method

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

Run Allocator::get_memory_fd under this allocator’s lock.

Errors

Same checked/native errors as Allocator::get_memory_fd, plus SynchronizationPoisoned.

Safety

Same external-memory and descriptor-ownership contract as Allocator::get_memory_fd.

set_device_memory_callbacks

Method

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

Run Allocator::set_device_memory_callbacks under this allocator’s lock.

Errors

Same errors as Allocator::set_device_memory_callbacks, plus SynchronizationPoisoned.

Safety

Same retained-callback contract as Allocator::set_device_memory_callbacks; callbacks must also satisfy SynchronizedAllocator::new’s any-thread rules.

new

Method

pub unsafe fn new(allocator: Allocator<'device>) -> Self

Adopt one allocator for synchronized access from any host thread. No native operation, allocation, mapping or thread is started.

Safety

Every retained callback record/code/user datum, pool allocation chain and nested external reference must remain valid for the device borrow and support access on any participating thread, including final CPU cleanup. Retained records must be immutable across threads; callback-owned mutable state needs its own synchronization when shared with independent owners. Existing mapped-byte uses must be synchronized against subsequent operations. Native contexts must meet Vulkan’s host-thread lifetime/valid-usage contract. No callback may unwind or reenter this same allocator.

new_owned

Method

pub fn new_owned(allocator: Allocator<'static>) -> Self

Adopt one device-retained allocator for synchronized access from any host thread. Every retained reference is owned or 'static, so the unsafe contract of Self::new is satisfied by construction; the remaining caller obligations are the documented host-thread, non-reentrancy and mapped-byte synchronization rules.

with_allocator

Method

pub unsafe fn with_allocator<R>( &self, operation: impl FnOnce(&mut Allocator<'device>) -> R, ) -> Result<R, AllocError>

Run one operation/batch with exclusive access to the canonical allocator. The borrow cannot escape the closure. Returned tokens/handles remain raw native identities; no lock covers their later GPU or mapped-byte uses.

Errors

Returns SynchronizationPoisoned without running the closure after a panic. Operation errors remain the closure’s result and do not poison the mutex.

Panics

A closure panic propagates and poisons subsequent access. Reentrant use of this same allocator can deadlock and violates the unsafe access contract.

Safety

Preserve new’s any-thread contract for every retained registration/state change. Do not replace the allocator with thread-affine state. All native operation/callback/completion rules apply. Inside any partitioned scope, never move out or replace the borrowed child allocator. Synchronize any escaping mapped pointer before unmap/free/relocation; the mutex protects metadata only.

try_with_allocator

Method

pub unsafe fn try_with_allocator<R>( &self, operation: impl FnOnce(&mut Allocator<'device>) -> R, ) -> Result<Option<R>, AllocError>

Attempt one exclusive operation without waiting for another host user. None means busy; poison is an error and never bypassed.

Errors

Same poison refusal as with_allocator; operation failures stay in R.

Safety

The complete with_allocator contract applies, including any-thread retained state, callback non-reentrancy and synchronization of escaping mappings.

with_pools

Method

pub unsafe fn with_pools<R>( &self, pools: &[&Pool], operation: impl FnOnce(&[Self]) -> R, ) -> Result<R, AllocError>

Run independent custom pools concurrently through borrowed child owners.

Children correspond to pools in input order, preserve allocation/pool identities and use the same canonical methods through with_allocator. Each child serializes its own pool; different pools can execute native operations concurrently, even on the same memory type. A shared reservation lock enforces aggregate native-count, heap and within-budget limits, but never covers native PFNs. The parent remains locked for the whole scope. Its ordinary operations, statistics and relocation resume after restoration.

All scope metadata uses the allocator’s CPU callbacks. Merge capacity is reserved before native effects; scope exit and panic restoration allocate no host memory and perform no native cleanup. Existing mappings remain live. Budget pressure is sampled at entry and corrected for all local reservations through this batch; split long-lived workloads into bounded scopes to refresh.

// SAFETY: all retained references/callbacks support concurrent workers;
// this batch installs no thread-affine state and leaves native cleanup explicit.
unsafe { shared.with_pools(&[first, second], |children| {
    std::thread::scope(|scope| {
        for (child, pool) in children.iter().zip([first, second]) {
            scope.spawn(move || child.with_allocator(|allocator| {
                allocator.pool_statistics(pool)
            }).unwrap().unwrap());
        }
    });
})?; }

Errors

Rejects foreign/stale/duplicate pools, nested pool scopes, preparation OOM, and poisoned access. A child panic poisons the parent even if caught by the operation. Cached export-root ownership follows its backing memory across the scope.

Safety

The complete with_allocator contract applies to every child. Use only its selected pool for allocations; allocator-wide changes are rejected. Never replace, move out or retain a child’s allocator/context. All borrowed workers must finish before returning; do not reenter the locked parent. Synchronize shared callbacks/user data across pools. Mapped-byte and GPU ownership/completion remain explicit, including after a worker panic.

with_memory_types

Method

pub unsafe fn with_memory_types<R>( &self, memory_types: &[u32], operation: impl FnOnce(&[Self]) -> R, ) -> Result<R, AllocError>

Run independent default memory-type vectors concurrently.

Children correspond to distinct native memory-type indices. They own only default storage of that type, including separate allocations and cached blocks; custom pools remain with the parent. Native type selection cannot escape its selected type. Tokens/maps and accounting retain parent identity.

// SAFETY: retained device/callback state supports these joined workers;
// no replacement, registration or mapped byte access occurs in this batch.
unsafe { shared.with_memory_types(&[0], |children| {
    std::thread::scope(|scope| {
        scope.spawn(|| children[0].with_allocator(|allocator| {
            allocator.memory_type_properties(0)
        }).unwrap().unwrap()).join().unwrap();
    });
})?; }

Errors

Rejects absent/duplicate types, nested scopes, poison and metadata OOM.

Safety

The complete with_pools worker/callback/native-lifetime contract applies. Use default allocation policies, without a custom pool. Never move out or replace child owners, reenter the parent or form cross-child lock cycles.

with_blocks

Method

pub unsafe fn with_blocks<R>( &self, allocations: &[&Allocation], operation: impl FnOnce(&[Self]) -> R, ) -> Result<R, AllocError>

Run mapping/cache/binding work concurrently on distinct native blocks.

Each seed is a live allocation; seeds must select different backing memory objects. A child contains every live region on that backing object, including regions not used as seeds. Regions sharing a block share its one mutex/map count. Different blocks of one custom/default pool can progress independently. Allocation/free, pool changes, trim and relocation are excluded for this borrowed phase. Map holds, metadata, cached exports and original block order return to the parent, including after panic. No native cleanup occurs on exit. A child borrow cannot escape this phase:

ⓘ

let child = unsafe { shared.with_blocks(&[seed], |children| &children[0]) };

Errors

Rejects stale/foreign seeds, duplicate backings, nested scopes, poison and OOM.

Safety

The complete with_pools borrowing/any-thread/native contract applies. Use each token only in its matching child. No worker/reference may escape; synchronize mapped bytes and external object uses, and avoid lock cycles.

statistics

Method

pub fn statistics(&self) -> Result<AllocatorStats, AllocError>

Observe a serialized allocator-owned statistics snapshot.

Errors

Returns SynchronizationPoisoned after a closure panic.

into_inner

Method

pub fn into_inner( self, ) -> Result<Allocator<'device>, PoisonError<Allocator<'device>>>

Recover the exclusive allocator without performing native cleanup.

Errors

PoisonError retains the allocator for deliberate inspection/recovery using into_inner; do not assume panic-interrupted native transactions completed.

Stvk::mem::SynchronizedVirtualBlock

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

One virtual block with serialized operation access from any host thread.

Contract

One virtual block with serialized operation access from any host thread.

Default-constructed blocks allocate metadata with the system allocator and are safe to share immediately. Callback-backed blocks are adopted through unsafe constructors under the same any-thread contract as VirtualBlock’s unsafe callback construction. Access serializes per block; independent blocks run concurrently. There is no GPU or native completion tracking. Caller-provided diagnostic writers must not reenter this block.

Methods and associated items

new

Method

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

Create TLSF host-only placement behind one mutex. No callbacks are borrowed.

Errors

Rejects a zero size or failed host metadata reservation.

new_with_algorithm

Method

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

Create TLSF or linear host-only placement behind one mutex.

Errors

Rejects a zero size or failed host metadata reservation.

new_with_callbacks

Method

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

Create callback-backed placement behind one mutex.

Errors

Same errors as VirtualBlock::new_with_callbacks.

Safety

The complete VirtualBlock::new_with_callbacks contract applies. Callback code and user data additionally must support calls on any participating worker thread, not only the constructing thread, through final cleanup.

new_from_block

Method

pub unsafe fn new_from_block(block: VirtualBlock<'callbacks>) -> Self

Adopt an existing block for serialized access from any host thread.

Safety

If the block borrows allocation callbacks, their records/code/user data must satisfy VirtualBlock::new_with_callbacks’s contract and support calls on any participating worker thread through final cleanup.

allocate

Method

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

Run VirtualBlock::allocate under this block’s lock.

Errors

Same errors as VirtualBlock::allocate, plus SynchronizationPoisoned.

allocate_upper

Method

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

Run VirtualBlock::allocate_upper under this block’s lock.

Errors

Same errors as VirtualBlock::allocate_upper, plus SynchronizationPoisoned.

free

Method

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

Run VirtualBlock::free under this block’s lock.

Errors

Same errors as VirtualBlock::free, plus SynchronizationPoisoned.

allocation_info

Method

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

Run VirtualBlock::allocation_info under this block’s lock.

Errors

Same errors as VirtualBlock::allocation_info, plus SynchronizationPoisoned.

set_user_data

Method

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

Run VirtualBlock::set_user_data under this block’s lock.

Errors

Same errors as VirtualBlock::set_user_data, plus SynchronizationPoisoned.

is_empty

Method

pub fn is_empty(&self) -> Result<bool, AllocError>

Run VirtualBlock::is_empty under this block’s lock.

Errors

Returns SynchronizationPoisoned after a closure panic.

clear

Method

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

Run VirtualBlock::clear under this block’s lock. Users of previously returned offsets must stop using them before reuse.

Errors

Returns SynchronizationPoisoned after a closure panic.

statistics

Method

pub fn statistics(&self) -> Result<VirtualBlockStats, AllocError>

Run VirtualBlock::statistics under this block’s lock.

Errors

Returns SynchronizationPoisoned after a closure panic.

detailed_statistics

Method

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

Run VirtualBlock::detailed_statistics under this block’s lock.

Errors

Returns SynchronizationPoisoned after a closure panic.

write_statistics_json

Method

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

Run VirtualBlock::write_statistics_json under this block’s lock.

Errors

Same errors as VirtualBlock::write_statistics_json, plus SynchronizationPoisoned.

Panics

A writer panic propagates and poisons subsequent operations. Writers must not reenter the block while this method holds its lock.

into_inner

Method

pub fn into_inner( self, ) -> Result<VirtualBlock<'callbacks>, PoisonError<VirtualBlock<'callbacks>>>

Recover the exclusive block without native cleanup.

Errors

PoisonError retains the block for explicit inspection/cleanup after a panic.