Struct base::LayoutAllocation

pub struct LayoutAllocation {
    ptr: *mut u8,
    layout: Layout,
}

A contiguous memory allocation with a specified size and alignment, with a Drop impl to perform the deallocation.

Conceptually this is like a Box<u8> but for which we can select a minimum required alignment at the time of allocation.

Example

use std::alloc::Layout;
use std::mem;
use base::LayoutAllocation;

#[repr(C)]
struct Header {
    q: usize,
    entries: [Entry; 0], // flexible array member
}

#[repr(C)]
struct Entry {
    e: usize,
}

fn demo(num_entries: usize) {
    let size = mem::size_of::<Header>() + num_entries * mem::size_of::<Entry>();
    let layout = Layout::from_size_align(size, mem::align_of::<Header>()).unwrap();
    let mut allocation = LayoutAllocation::zeroed(layout);

    // SAFETY:
    // Safe to obtain an exclusive reference because there are no other
    // references to the allocation yet and all-zero is a valid bit pattern for
    // our header.
    let header = unsafe { allocation.as_mut::<Header>() };
}

Fields

ptr: *mut u8

layout: Layout

Implementations

impl LayoutAllocation

pub fn uninitialized(layout: Layout) -> Self

Allocates memory with the specified size and alignment. The content is not initialized.

Uninitialized data is not safe to read. Further, it is not safe to obtain a reference to data potentially holding a bit pattern incompatible with its type, for example an uninitialized bool or enum.

pub fn zeroed(layout: Layout) -> Self

Allocates memory with the specified size and alignment and initializes the content to all zero-bytes.

Note that zeroing the memory does not necessarily make it safe to obtain a reference to the allocation. Depending on the intended type T, all-zero may or may not be a legal bit pattern for that type. For example obtaining a reference would immediately be undefined behavior if one of the fields has type NonZeroUsize.

pub fn as_ptr<T>(&self) -> *mut T

Returns a raw pointer to the allocated data.

pub fn layout(&self) -> &Layout

Returns a reference to the Layout used to create this allocation.

pub unsafe fn as_ref<T>(&self) -> &T

Returns a shared reference to the allocated data.

Safety

Caller is responsible for ensuring that the data behind this pointer has been initialized as much as necessary and that there are no already existing mutable references to any part of the data.

pub unsafe fn as_mut<T>(&mut self) -> &mut T

Returns an exclusive reference to the allocated data.

Safety

Caller is responsible for ensuring that the data behind this pointer has been initialized as much as necessary and that there are no already existing references to any part of the data.

pub unsafe fn as_slice<T>(&self, num_elements: usize) -> &[T]

Returns a shared slice reference to the allocated data.

Arguments

num_elements - Number of T elements to include in the slice. The length of the slice will be capped to the allocation’s size. Caller must ensure that any sliced elements are initialized.

Safety

Caller is responsible for ensuring that the data behind this pointer has been initialized as much as necessary and that there are no already existing mutable references to any part of the data.

pub unsafe fn as_mut_slice<T>(&mut self, num_elements: usize) -> &mut [T]

Returns an exclusive slice reference to the allocated data.

Arguments

num_elements - Number of T elements to include in the slice. The length of the slice will be capped to the allocation’s size. Caller must ensure that any sliced elements are initialized.

Safety

Caller is responsible for ensuring that the data behind this pointer has been initialized as much as necessary and that there are no already existing references to any part of the data.

Trait Implementations

impl Drop for LayoutAllocation

fn drop(&mut self)

Executes the destructor for this type.