pub unsafe trait Allocator { // Required methods fnallocate(&self, layout:Layout) ->Result<NonNull<[u8]>,AllocError>; unsafe fndeallocate(&self, ptr:NonNull<u8>, layout:Layout); // Provided methods fnallocate_zeroed( &self, layout:Layout, ) ->Result<NonNull<[u8]>,AllocError> { ... } unsafe fngrow( &self, ptr:NonNull<u8>, old_layout:Layout, new_layout:Layout, ) ->Result<NonNull<[u8]>,AllocError> { ... } unsafe fngrow_zeroed( &self, ptr:NonNull<u8>, old_layout:Layout, new_layout:Layout, ) ->Result<NonNull<[u8]>,AllocError> { ... } unsafe fnshrink( &self, ptr:NonNull<u8>, old_layout:Layout, new_layout:Layout, ) ->Result<NonNull<[u8]>,AllocError> { ... } fnby_ref(&self) -> &Selfwhere Self:Sized { ... }}allocator_api #32838)Expand description
An implementation ofAllocator can allocate, grow, shrink, and deallocate arbitrary blocks ofdata described viaLayout.
Allocator is designed to be implemented on ZSTs, references, or smart pointers.An allocator forMyAlloc([u8; N]) cannot be moved, without updating the pointers to theallocated memory.
In contrast toGlobalAlloc,Allocator allows zero-sized allocations. If an underlyingallocator does not support this (like jemalloc) or responds by returning a null pointer(such aslibc::malloc), this must be caught by the implementation.
§Currently allocated memory
Some of the methods require that a memory block iscurrently allocated by an allocator.This means that:
- the starting address for that memory block was previouslyreturned by
allocate,grow, orshrink, and - the memory block has not subsequently been deallocated.
A memory block is deallocated by a call todeallocate,or by a call togrow orshrink that returnsOk.A call togrow orshrink that returnsErr,does not deallocate the memory block passed to it.
§Memory fitting
Some of the methods require that alayoutfit a memory block or vice versa. This means that thefollowing conditions must hold:
- the memory block must becurrently allocated with alignment of
layout.align(), and layout.size()must fall in the rangemin ..= max, where:
§Safety
Memory blocks that arecurrently allocated by an allocator,must point to valid memory, and retain their validity until either:
- the memory block is deallocated, or
- the allocator is dropped.
Copying, cloning, or moving the allocator must not invalidate memory blocks returned from it.A copied or cloned allocator must behave like the original allocator.
A memory block which iscurrently allocated may be passed toany method of the allocator that accepts such an argument.
Required Methods§
Sourcefnallocate(&self, layout:Layout) ->Result<NonNull<[u8]>,AllocError>
🔬This is a nightly-only experimental API. (allocator_api #32838)
fnallocate(&self, layout:Layout) ->Result<NonNull<[u8]>,AllocError>
allocator_api #32838)Attempts to allocate a block of memory.
On success, returns aNonNull<[u8]> meeting the size and alignment guarantees oflayout.
The returned block may have a larger size than specified bylayout.size(), and may or maynot have its contents initialized.
The returned block of memory remains valid as long as it iscurrently allocated and the shorter of:
- the borrow-checker lifetime of the allocator type itself.
- as long as the allocator and all its clones have not been dropped.
§Errors
ReturningErr indicates that either memory is exhausted orlayout does not meetallocator’s size or alignment constraints.
Implementations are encouraged to returnErr on memory exhaustion rather than panicking oraborting, but this is not a strict requirement. (Specifically: it islegal to implementthis trait atop an underlying native allocation library that aborts on memory exhaustion.)
Clients wishing to abort computation in response to an allocation error are encouraged tocall thehandle_alloc_error function, rather than directly invokingpanic! or similar.
Sourceunsafe fndeallocate(&self, ptr:NonNull<u8>, layout:Layout)
🔬This is a nightly-only experimental API. (allocator_api #32838)
unsafe fndeallocate(&self, ptr:NonNull<u8>, layout:Layout)
allocator_api #32838)Deallocates the memory referenced byptr.
§Safety
ptrmust denote a block of memorycurrently allocated via this allocator, andlayoutmustfit that block of memory.
Provided Methods§
Sourcefnallocate_zeroed(&self, layout:Layout) ->Result<NonNull<[u8]>,AllocError>
🔬This is a nightly-only experimental API. (allocator_api #32838)
fnallocate_zeroed(&self, layout:Layout) ->Result<NonNull<[u8]>,AllocError>
allocator_api #32838)Behaves likeallocate, but also ensures that the returned memory is zero-initialized.
§Errors
ReturningErr indicates that either memory is exhausted orlayout does not meetallocator’s size or alignment constraints.
Implementations are encouraged to returnErr on memory exhaustion rather than panicking oraborting, but this is not a strict requirement. (Specifically: it islegal to implementthis trait atop an underlying native allocation library that aborts on memory exhaustion.)
Clients wishing to abort computation in response to an allocation error are encouraged tocall thehandle_alloc_error function, rather than directly invokingpanic! or similar.
Sourceunsafe fngrow( &self, ptr:NonNull<u8>, old_layout:Layout, new_layout:Layout,) ->Result<NonNull<[u8]>,AllocError>
🔬This is a nightly-only experimental API. (allocator_api #32838)
unsafe fngrow( &self, ptr:NonNull<u8>, old_layout:Layout, new_layout:Layout,) ->Result<NonNull<[u8]>,AllocError>
allocator_api #32838)Attempts to extend the memory block.
Returns a newNonNull<[u8]> containing a pointer and the actual size of the allocatedmemory. The pointer is suitable for holding data described bynew_layout. To accomplishthis, the allocator may extend the allocation referenced byptr to fit the new layout.
If this returnsOk, then ownership of the memory block referenced byptr has beentransferred to this allocator. Any access to the oldptr is Undefined Behavior, even if theallocation was grown in-place. The newly returned pointer is the only valid pointerfor accessing this memory now.
If this method returnsErr, then ownership of the memory block has not been transferred tothis allocator, and the contents of the memory block are unaltered.
§Safety
ptrmust denote a block of memorycurrently allocated via this allocator.old_layoutmustfit that block of memory (Thenew_layoutargument need not fit it.).new_layout.size()must be greater than or equal toold_layout.size().
Note thatnew_layout.align() need not be the same asold_layout.align().
§Errors
ReturnsErr if the new layout does not meet the allocator’s size and alignmentconstraints of the allocator, or if growing otherwise fails.
Implementations are encouraged to returnErr on memory exhaustion rather than panicking oraborting, but this is not a strict requirement. (Specifically: it islegal to implementthis trait atop an underlying native allocation library that aborts on memory exhaustion.)
Clients wishing to abort computation in response to an allocation error are encouraged tocall thehandle_alloc_error function, rather than directly invokingpanic! or similar.
Sourceunsafe fngrow_zeroed( &self, ptr:NonNull<u8>, old_layout:Layout, new_layout:Layout,) ->Result<NonNull<[u8]>,AllocError>
🔬This is a nightly-only experimental API. (allocator_api #32838)
unsafe fngrow_zeroed( &self, ptr:NonNull<u8>, old_layout:Layout, new_layout:Layout,) ->Result<NonNull<[u8]>,AllocError>
allocator_api #32838)Behaves likegrow, but also ensures that the new contents are set to zero before beingreturned.
The memory block will contain the following contents after a successful call togrow_zeroed:
- Bytes
0..old_layout.size()are preserved from the original allocation. - Bytes
old_layout.size()..old_sizewill either be preserved or zeroed, depending onthe allocator implementation.old_sizerefers to the size of the memory block priorto thegrow_zeroedcall, which may be larger than the size that was originallyrequested when it was allocated. - Bytes
old_size..new_sizeare zeroed.new_sizerefers to the size of the memoryblock returned by thegrow_zeroedcall.
§Safety
ptrmust denote a block of memorycurrently allocated via this allocator.old_layoutmustfit that block of memory (Thenew_layoutargument need not fit it.).new_layout.size()must be greater than or equal toold_layout.size().
Note thatnew_layout.align() need not be the same asold_layout.align().
§Errors
ReturnsErr if the new layout does not meet the allocator’s size and alignmentconstraints of the allocator, or if growing otherwise fails.
Implementations are encouraged to returnErr on memory exhaustion rather than panicking oraborting, but this is not a strict requirement. (Specifically: it islegal to implementthis trait atop an underlying native allocation library that aborts on memory exhaustion.)
Clients wishing to abort computation in response to an allocation error are encouraged tocall thehandle_alloc_error function, rather than directly invokingpanic! or similar.
Sourceunsafe fnshrink( &self, ptr:NonNull<u8>, old_layout:Layout, new_layout:Layout,) ->Result<NonNull<[u8]>,AllocError>
🔬This is a nightly-only experimental API. (allocator_api #32838)
unsafe fnshrink( &self, ptr:NonNull<u8>, old_layout:Layout, new_layout:Layout,) ->Result<NonNull<[u8]>,AllocError>
allocator_api #32838)Attempts to shrink the memory block.
Returns a newNonNull<[u8]> containing a pointer and the actual size of the allocatedmemory. The pointer is suitable for holding data described bynew_layout. To accomplishthis, the allocator may shrink the allocation referenced byptr to fit the new layout.
If this returnsOk, then ownership of the memory block referenced byptr has beentransferred to this allocator. Any access to the oldptr is Undefined Behavior, even if theallocation was shrunk in-place. The newly returned pointer is the only valid pointerfor accessing this memory now.
If this method returnsErr, then ownership of the memory block has not been transferred tothis allocator, and the contents of the memory block are unaltered.
§Safety
ptrmust denote a block of memorycurrently allocated via this allocator.old_layoutmustfit that block of memory (Thenew_layoutargument need not fit it.).new_layout.size()must be smaller than or equal toold_layout.size().
Note thatnew_layout.align() need not be the same asold_layout.align().
§Errors
ReturnsErr if the new layout does not meet the allocator’s size and alignmentconstraints of the allocator, or if shrinking otherwise fails.
Implementations are encouraged to returnErr on memory exhaustion rather than panicking oraborting, but this is not a strict requirement. (Specifically: it islegal to implementthis trait atop an underlying native allocation library that aborts on memory exhaustion.)
Clients wishing to abort computation in response to an allocation error are encouraged tocall thehandle_alloc_error function, rather than directly invokingpanic! or similar.