Struct Allocation 

pub struct Allocation<A: Allocator = Global> { /* private fields */ }

An allocation is management representation of some allocated memory.

For the most part, this behaves like a lower-level (untyped) cousin of a Box. The memory backing this allocation is deallocated when the allocation is dropped. In contrast, no validity or initialization state of the memory is implied by existance of an Allocation.

Implementations

impl Allocation

Methods for the global allocator

pub fn new(layout: Layout) -> Self

Allocate new memory for the given layout.

The pointer backing the allocation is valid for reads and writes of layout.size() bytes and this memory region does not alias any other existing allocation.

The pointer is guaranteed to be aligned to layout.align() but several systems align memory more lax when a small alignment is requested.

Memory is not initialized or zeroed, try Self::zeroed instead.

Panics

This calls alloc::alloc::handle_alloc_error when no memory could be allocated, which can panic. See Self::try_new_in for a version that returns an error instead.

pub fn try_new(layout: Layout) -> Result<Self, AllocError>

Allocate new memory for the given layout.

Same as Self::new but returns an error when memory could not be allocated.

pub fn zeroed(layout: Layout) -> Self

Allocate new zeroed-out memory for the given layout.

Panics

This calls alloc::alloc::handle_alloc_error when no memory could be allocated, which can panic. See Self::try_zeroed_in for a version that returns an error instead.

pub fn try_zeroed(layout: Layout) -> Result<Self, AllocError>

Allocate new zeroed-out memory for the given layout.

Same as Self::zeroed but returns an error when memory could not be allocated.

pub fn into_parts(self) -> (NonNull<u8>, Layout)

Split the allocation into its raw parts.

Deallocating the allocation is the responsibility of the caller. The returned pointer can be passed to alloc::alloc::dealloc if the returned layout indicates size() > 0. If the allocated memory is 0 sized, the pointer does not need to be deallocated.

See also Self::into_parts_with_alloc for an allocator-aware version.

pub unsafe fn from_parts(ptr: NonNull<u8>, layout: Layout) -> Self

Constructs an Allocation from a pointer and layout information.

Safety

The pointer must point to currently-allocated memory from the global allocator, and layout was used to allocate that memory.

impl<A: Allocator> Allocation<A>

Common methods

pub fn as_ptr<T>(&self) -> NonNull<T>

Gets a pointer to the allocation.

The pointer is always aligned to the alignment of the layout indicated by Self::layout or the requested layout indicated on allocation, whichever is more strict.

The pointer can be used to read and write memory in this allocation until it is reallocated, dropped or the memory is reclaimed manually (e.g. after converting into_parts).

In particular, the pointer does not in itself materialize a reference to the underlying storage for the purpose of the aliasing model.

pub fn as_uninit_ref<T>(&self) -> &MaybeUninit<T>

View the underlying storage as a possibly uninitialized T.

Panics

If the allocation is too small, or not aligned enough to contain a T.

pub fn as_uninit_mut<T>(&mut self) -> &mut MaybeUninit<T>

View the underlying storage as a possibly uninitialized T.

Panics

If the allocation is too small, or not aligned enough to contain a T.

pub fn as_slice(&self) -> NonNull<[MaybeUninit<u8>]>

View the allocation as a pointer to a slice of possibly uninitialized bytes.

The caller is responsible for checking lifetimes when convert to a reference.

The pointer can be used to read and write memory in this allocation until it is reallocated, dropped or the memory is reclaimed manually (e.g. after converting into_parts).

Like as_ptr, this does not materialize a reference to the underlying storage for the purpose of the aliasing model. Hence, these two methods can be intermixed.

pub fn realloc(&mut self, new_layout: Layout)

Reallocates memory to a new layout.

If the newly requested layout is larger than the currently allocated layout, existing (possibly uninitialized) bytes are preserved. Newly allocated bytes are uninitialized.

Any pointers to the managed memory are invalidated on return.

Panics

This calls alloc::alloc::handle_alloc_error when no memory could be allocated, which can panic. In this case, pointers are still valid. See Self::try_realloc for a version that returns an error instead.

pub fn realloc_zeroed(&mut self, new_layout: Layout)

Reallocates memory to a new layout.

If the newly requested layout is larger than the currently allocated layout, existing (possibly uninitialized) bytes are preserved. Newly allocated bytes are zeroed.

Any pointers to the managed memory are invalidated on return.

Panics

This calls alloc::alloc::handle_alloc_error when no memory could be allocated, which can panic. In this case, pointers are still valid. See Self::try_realloc_zeroed for a version that returns an error instead.

pub fn layout(&self) -> Layout

Get the layout of the underlying allocation.

This layout is guaranteed to be at least as large as previously requested from new or realloc and at least as strictly aligned, but might indicate more available memory.

impl<A: Allocator> Allocation<A>

Methods using the allocator-api or shim

pub fn new_in(layout: Layout, alloc: A) -> Self

Allocate new memory for the given layout in a given allocator.

The pointer backing the allocation is valid for reads and writes of layout.size() bytes and this memory region does not alias any other existing allocation.

The pointer is guaranteed to be aligned to layout.align() but several systems align memory more lax when a small alignment is requested.

Memory is not initialized or zeroed, try Self::zeroed_in instead.

Panics

This calls alloc::alloc::handle_alloc_error when no memory could be allocated, which can panic. See Self::try_new_in for a version that returns an error instead.

pub fn try_new_in(layout: Layout, alloc: A) -> Result<Self, AllocError>

Allocate new memory for the given layout in a given allocator.

Returns an error when no memory could be allocated.

pub fn zeroed_in(layout: Layout, alloc: A) -> Self

Allocate new zeroed-out memory for the given layout in a given allocator.

Panics

This calls alloc::alloc::handle_alloc_error when no memory could be allocated, which can panic. See Self::try_zeroed_in for a version that returns an error instead.

pub fn try_zeroed_in(layout: Layout, alloc: A) -> Result<Self, AllocError>

Allocate new zeroed-out memory for the given layout in a given allocator.

Returns an error when no memory could be allocated.

pub fn into_parts_with_alloc(self) -> (NonNull<u8>, Layout, A)

Split the allocation into its raw parts including the allocator.

Deallocating the allocation is the responsibility of the caller. The returned pointer can be passed to alloc.deallocate().

pub unsafe fn from_parts_in(ptr: NonNull<u8>, layout: Layout, alloc: A) -> Self

Constructs an Allocation from a pointer and layout information in the given allocator.

Safety

The pointer must point to currently-allocated memory from the given allocator, and layout fits that memory.

pub fn try_realloc(&mut self, new_layout: Layout) -> Result<(), AllocError>

Reallocates memory to a new layout.

Returns an error when the memory could not be reallocated. In this case, any previously derived pointers remain valid and no memory is deallocated.

See also

Self::realloc for more disuccion about the memory contents after reallocation.

pub fn try_realloc_zeroed( &mut self, new_layout: Layout, ) -> Result<(), AllocError>

Reallocates memory to a new layout.

Returns an error when the memory could not be reallocated. In this case, any previously derived pointers remain valid and no memory is deallocated.

See also

Self::realloc_zeroed for more disuccion about the memory contents after reallocation.

impl<A: Allocator> Allocation<A>

pub fn try_into_box<T>( self, ) -> Result<Box<MaybeUninit<T>, A>, BoxConversionError>

Convert the allocation into a box.

This fails if the allocated layout does not match the requested type. The value might not be initialized, use Box::assume_init in case you have initialized the memory of this allocation correctly.

See also the opposite conversion Allocation as From<Box<_>>.

pub fn try_into_vec<T>(self) -> Result<Vec<T, A>, VecConversionError>

Convert the allocation into a Vec.

This fails if the allocated size is not a multiple of the requested element size, or if the element type is zero-sized. For the latter case, the capacity of the Vec would be ambiguous.

The length of the returned vec is always set to 0 and has to be resized manually with Vec::set_len.

See also the opposite conversion Allocation as From<Vec<_>>.

Trait Implementations

impl<A: Allocator> Drop for Allocation<A>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: ?Sized, A: Allocator> From<Box<T, A>> for Allocation<A>

The value in the box will not be dropped, as if passed to forget. Use the inverse (fallible) conversion to recover the value.

let boxed = Box::new(42);
let alloc: Allocation = boxed.into();
let boxed = alloc.try_into_box::<u32>().unwrap();
let boxed = unsafe { boxed.assume_init() };
assert_eq!(*boxed, 42);

fn from(value: Box<T, A>) -> Self

Converts to this type from the input type.

impl<T, A: Allocator> From<Vec<T, A>> for Allocation<A>

The values in the Vec will not be dropped, as if by a call to vec.set_len(0).

let values = vec![42];
let alloc: Allocation = values.into();
let mut values = alloc.try_into_vec::<u32>().unwrap();
unsafe { values.set_len(1) };
assert_eq!(values, [42]);

fn from(value: Vec<T, A>) -> Self

Converts to this type from the input type.

impl<T> TryFrom<Allocation> for Box<MaybeUninit<T>>

type Error = BoxConversionError

The type returned in the event of a conversion error.

fn try_from(alloc: Allocation) -> Result<Self, Self::Error>

Performs the conversion.

impl<T> TryFrom<Allocation> for Vec<T>

type Error = VecConversionError

The type returned in the event of a conversion error.

fn try_from(value: Allocation) -> Result<Self, Self::Error>

Performs the conversion.

impl<A: Allocator + Send> Send for Allocation<A>

impl<A: Allocator + Sync> Sync for Allocation<A>