pub unsafe trait AllocRef {
fn alloc(&mut self, layout: Layout) -> Result<NonNull<[u8]>, AllocErr>;
unsafe fn dealloc(&mut self, ptr: NonNull<u8>, layout: Layout);
fn alloc_zeroed( &mut self, layout: Layout ) -> Result<NonNull<[u8]>, AllocErr> { ... }
unsafe fn grow( &mut self, ptr: NonNull<u8>, layout: Layout, new_size: usize ) -> Result<NonNull<[u8]>, AllocErr> { ... }
unsafe fn grow_zeroed( &mut self, ptr: NonNull<u8>, layout: Layout, new_size: usize ) -> Result<NonNull<[u8]>, AllocErr> { ... }
unsafe fn shrink( &mut self, ptr: NonNull<u8>, layout: Layout, new_size: usize ) -> Result<NonNull<[u8]>, AllocErr> { ... }
fn by_ref(&mut self) -> &mut SelfⓘNotable traits for &'_ mut Fimpl<'_, F> Future for &'_ mut F where F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;impl<'_, I> Iterator for &'_ mut I where I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<R: Read + ?Sized, '_> Read for &'_ mut Rimpl<W: Write + ?Sized, '_> Write for &'_ mut W { ... }
}
An implementation of AllocRef can allocate, grow, shrink, and deallocate arbitrary blocks of data described via Layout.
AllocRef is designed to be implemented on ZSTs, references, or smart pointers because having an allocator like MyAlloc([u8; N]) cannot be moved, without updating the pointers to the allocated memory.
Unlike GlobalAlloc, zero-sized allocations are allowed in AllocRef. If an underlying allocator does not support this (like jemalloc) or return a null pointer (such as libc::malloc), this must be caught by the implementation.
Some of the methods require that a memory block be currently allocated via an allocator. This means that:
the starting address for that memory block was previously returned by alloc, grow, or shrink, and
the memory block has not been subsequently deallocated, where blocks are either deallocated directly by being passed to dealloc or were changed by being passed to grow or shrink that returns Ok. If grow or shrink have returned Err, the passed pointer remains valid.
Some of the methods require that a layout fit a memory block. What it means for a layout to "fit" a memory block means (or equivalently, for a memory block to "fit" a layout) is that the following conditions must hold:
The block must be allocated with the same alignment as layout.align(), and
The provided layout.size() must fall in the range min ..= max, where:
Memory blocks returned from an allocator must point to valid memory and retain their validity until the instance and all of its clones are dropped,
cloning or moving the allocator must not invalidate memory blocks returned from this allocator. A cloned allocator must behave like the same allocator, and
any pointer to a memory block which is currently allocated may be passed to any other method of the allocator.
fn alloc(&mut self, layout: Layout) -> Result<NonNull<[u8]>, AllocErr>Attempts to allocate a block of memory.
On success, returns a [NonNull<[u8]>] meeting the size and alignment guarantees of layout.
The returned block may have a larger size than specified by layout.size(), and may or may not have its contents initialized.
[NonNull<[u8]>]: NonNull
Returning Err indicates that either memory is exhausted or layout does not meet allocator's size or alignment constraints.
Implementations are encouraged to return Err on memory exhaustion rather than panicking or aborting, but this is not a strict requirement. (Specifically: it is legal to implement this 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 to call the handle_alloc_error function, rather than directly invoking panic! or similar.
unsafe fn dealloc(&mut self, ptr: NonNull<u8>, layout: Layout)Deallocates the memory referenced by ptr.
ptr must denote a block of memory currently allocated via this allocator, andlayout must fit that block of memory.fn alloc_zeroed(&mut self, layout: Layout) -> Result<NonNull<[u8]>, AllocErr>Behaves like alloc, but also ensures that the returned memory is zero-initialized.
Returning Err indicates that either memory is exhausted or layout does not meet allocator's size or alignment constraints.
Implementations are encouraged to return Err on memory exhaustion rather than panicking or aborting, but this is not a strict requirement. (Specifically: it is legal to implement this 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 to call the handle_alloc_error function, rather than directly invoking panic! or similar.
unsafe fn grow(
&mut self,
ptr: NonNull<u8>,
layout: Layout,
new_size: usize
) -> Result<NonNull<[u8]>, AllocErr>Attempts to extend the memory block.
Returns a new [NonNull<[u8]>] containing a pointer and the actual size of the allocated memory. The pointer is suitable for holding data described by a new layout with layout’s alignment and a size given by new_size. To accomplish this, the allocator may extend the allocation referenced by ptr to fit the new layout.
If this returns Ok, then ownership of the memory block referenced by ptr has been transferred to this allocator. The memory may or may not have been freed, and should be considered unusable unless it was transferred back to the caller again via the return value of this method.
If this method returns Err, then ownership of the memory block has not been transferred to this allocator, and the contents of the memory block are unaltered.
[NonNull<[u8]>]: NonNull
ptr must denote a block of memory currently allocated via this allocator,layout must fit that block of memory (The new_size argument need not fit it.),new_size must be greater than or equal to layout.size(), andnew_size, when rounded up to the nearest multiple of layout.align(), must not overflow (i.e., the rounded value must be less than or equal to usize::MAX).Returns Err if the new layout does not meet the allocator's size and alignment constraints of the allocator, or if growing otherwise fails.
Implementations are encouraged to return Err on memory exhaustion rather than panicking or aborting, but this is not a strict requirement. (Specifically: it is legal to implement this 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 to call the handle_alloc_error function, rather than directly invoking panic! or similar.
unsafe fn grow_zeroed(
&mut self,
ptr: NonNull<u8>,
layout: Layout,
new_size: usize
) -> Result<NonNull<[u8]>, AllocErr>Behaves like grow, but also ensures that the new contents are set to zero before being returned.
The memory block will contain the following contents after a successful call to grow_zeroed:
0..layout.size() are preserved from the original allocation.layout.size()..old_size will either be preserved or zeroed, depending on the allocator implementation. old_size refers to the size of the memory block prior to the grow_zeroed call, which may be larger than the size that was originally requested when it was allocated.old_size..new_size are zeroed. new_size refers to the size of the memory block returned by the grow call.ptr must denote a block of memory currently allocated via this allocator,layout must fit that block of memory (The new_size argument need not fit it.),new_size must be greater than or equal to layout.size(), andnew_size, when rounded up to the nearest multiple of layout.align(), must not overflow (i.e., the rounded value must be less than or equal to usize::MAX).Returns Err if the new layout does not meet the allocator's size and alignment constraints of the allocator, or if growing otherwise fails.
Implementations are encouraged to return Err on memory exhaustion rather than panicking or aborting, but this is not a strict requirement. (Specifically: it is legal to implement this 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 to call the handle_alloc_error function, rather than directly invoking panic! or similar.
unsafe fn shrink(
&mut self,
ptr: NonNull<u8>,
layout: Layout,
new_size: usize
) -> Result<NonNull<[u8]>, AllocErr>Attempts to shrink the memory block.
Returns a new [NonNull<[u8]>] containing a pointer and the actual size of the allocated memory. The pointer is suitable for holding data described by a new layout with layout’s alignment and a size given by new_size. To accomplish this, the allocator may shrink the allocation referenced by ptr to fit the new layout.
If this returns Ok, then ownership of the memory block referenced by ptr has been transferred to this allocator. The memory may or may not have been freed, and should be considered unusable unless it was transferred back to the caller again via the return value of this method.
If this method returns Err, then ownership of the memory block has not been transferred to this allocator, and the contents of the memory block are unaltered.
[NonNull<[u8]>]: NonNull
ptr must denote a block of memory currently allocated via this allocator,layout must fit that block of memory (The new_size argument need not fit it.), andnew_size must be smaller than or equal to layout.size().Returns Err if the new layout does not meet the allocator's size and alignment constraints of the allocator, or if shrinking otherwise fails.
Implementations are encouraged to return Err on memory exhaustion rather than panicking or aborting, but this is not a strict requirement. (Specifically: it is legal to implement this 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 to call the handle_alloc_error function, rather than directly invoking panic! or similar.
fn by_ref(&mut self) -> &mut SelfⓘNotable traits for &'_ mut F
impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized,
type Output = <F as Future>::Output;
impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized,
type Item = <I as Iterator>::Item;
impl<R: Read + ?Sized, '_> Read for &'_ mut R
impl<W: Write + ?Sized, '_> Write for &'_ mut W
Creates a "by reference" adaptor for this instance of AllocRef.
The returned adaptor also implements AllocRef and will simply borrow this.
impl AllocRef for Global[src]
fn alloc(&mut self, layout: Layout) -> Result<NonNull<[u8]>, AllocErr>[src]
fn alloc_zeroed(&mut self, layout: Layout) -> Result<NonNull<[u8]>, AllocErr>[src]
unsafe fn dealloc(&mut self, ptr: NonNull<u8>, layout: Layout)[src]
unsafe fn grow(
&mut self,
ptr: NonNull<u8>,
layout: Layout,
new_size: usize
) -> Result<NonNull<[u8]>, AllocErr>[src]
unsafe fn grow_zeroed(
&mut self,
ptr: NonNull<u8>,
layout: Layout,
new_size: usize
) -> Result<NonNull<[u8]>, AllocErr>[src]
unsafe fn shrink(
&mut self,
ptr: NonNull<u8>,
layout: Layout,
new_size: usize
) -> Result<NonNull<[u8]>, AllocErr>[src]
impl AllocRef for System[src]
fn alloc(&mut self, layout: Layout) -> Result<NonNull<[u8]>, AllocErr>[src]
fn alloc_zeroed(&mut self, layout: Layout) -> Result<NonNull<[u8]>, AllocErr>[src]
unsafe fn dealloc(&mut self, ptr: NonNull<u8>, layout: Layout)[src]
unsafe fn grow(
&mut self,
ptr: NonNull<u8>,
layout: Layout,
new_size: usize
) -> Result<NonNull<[u8]>, AllocErr>[src]
unsafe fn grow_zeroed(
&mut self,
ptr: NonNull<u8>,
layout: Layout,
new_size: usize
) -> Result<NonNull<[u8]>, AllocErr>[src]
unsafe fn shrink(
&mut self,
ptr: NonNull<u8>,
layout: Layout,
new_size: usize
) -> Result<NonNull<[u8]>, AllocErr>[src]
impl<'_, A> AllocRef for &'_ mut A where
A: AllocRef + ?Sized, [src]
fn alloc(&mut self, layout: Layout) -> Result<NonNull<[u8]>, AllocErr>[src]
fn alloc_zeroed(&mut self, layout: Layout) -> Result<NonNull<[u8]>, AllocErr>[src]
unsafe fn dealloc(&mut self, ptr: NonNull<u8>, layout: Layout)[src]
unsafe fn grow(
&mut self,
ptr: NonNull<u8>,
layout: Layout,
new_size: usize
) -> Result<NonNull<[u8]>, AllocErr>[src]
unsafe fn grow_zeroed(
&mut self,
ptr: NonNull<u8>,
layout: Layout,
new_size: usize
) -> Result<NonNull<[u8]>, AllocErr>[src]
unsafe fn shrink(
&mut self,
ptr: NonNull<u8>,
layout: Layout,
new_size: usize
) -> Result<NonNull<[u8]>, AllocErr>[src]
© 2010 The Rust Project Developers
Licensed under the Apache License, Version 2.0 or the MIT license, at your option.
https://doc.rust-lang.org/std/alloc/trait.AllocRef.html