Struct core::alloc::Layout

#[lang = "alloc_layout"]
pub struct Layout { /* fields omitted */ }

Layout of a block of memory.

An instance of Layout describes a particular layout of memory. You build a Layout up as an input to give to an allocator.

All layouts have an associated non-negative size and a power-of-two alignment.

(Note however that layouts are not required to have positive size, even though many allocators require that all memory requests have positive size. A caller to the Alloc::alloc method must either ensure that conditions like this are met, or use specific allocators with looser requirements.)

Methods

impl Layout

pub fn from_size_align(size: usize, align: usize) -> Result<Self, LayoutErr>

Constructs a Layout from a given size and align, or returns LayoutErr if either of the following conditions are not met:

• align must not be zero,

• align must be a power of two,

• size, when rounded up to the nearest multiple of align, must not overflow (i.e., the rounded value must be less than usize::MAX).

pub const unsafe fn from_size_align_unchecked(size: usize, align: usize) -> Self

Creates a layout, bypassing all checks.

Safety

This function is unsafe as it does not verify the preconditions from Layout::from_size_align.

pub fn size(&self) -> usize

The minimum size in bytes for a memory block of this layout.

pub fn align(&self) -> usize

The minimum byte alignment for a memory block of this layout.

pub fn new<T>() -> Self

Constructs a Layout suitable for holding a value of type T.

pub fn for_value<T: ?Sized>(t: &T) -> Self

Produces layout describing a record that could be used to allocate backing structure for T (which could be a trait or other unsized type like a slice).

pub fn align_to(&self, align: usize) -> Result<Self, LayoutErr>

🔬 This is a nightly-only experimental API. (alloc_layout_extra #55724)

Creates a layout describing the record that can hold a value of the same layout as self, but that also is aligned to alignment align (measured in bytes).

If self already meets the prescribed alignment, then returns self.

Note that this method does not add any padding to the overall size, regardless of whether the returned layout has a different alignment. In other words, if K has size 16, K.align_to(32) will still have size 16.

Returns an error if the combination of self.size() and the given align violates the conditions listed in Layout::from_size_align.

pub fn padding_needed_for(&self, align: usize) -> usize

🔬 This is a nightly-only experimental API. (alloc_layout_extra #55724)

Returns the amount of padding we must insert after self to ensure that the following address will satisfy align (measured in bytes).

e.g., if self.size() is 9, then self.padding_needed_for(4) returns 3, because that is the minimum number of bytes of padding required to get a 4-aligned address (assuming that the corresponding memory block starts at a 4-aligned address).

The return value of this function has no meaning if align is not a power-of-two.

Note that the utility of the returned value requires align to be less than or equal to the alignment of the starting address for the whole allocated block of memory. One way to satisfy this constraint is to ensure align <= self.align().

pub fn pad_to_align(&self) -> Result<Layout, LayoutErr>

🔬 This is a nightly-only experimental API. (alloc_layout_extra #55724)

Creates a layout by rounding the size of this layout up to a multiple of the layout's alignment.

Returns Err if the padded size would overflow.

This is equivalent to adding the result of padding_needed_for to the layout's current size.

pub fn repeat(&self, n: usize) -> Result<(Self, usize), LayoutErr>

🔬 This is a nightly-only experimental API. (alloc_layout_extra #55724)

Creates a layout describing the record for n instances of self, with a suitable amount of padding between each to ensure that each instance is given its requested size and alignment. On success, returns (k, offs) where k is the layout of the array and offs is the distance between the start of each element in the array.

On arithmetic overflow, returns LayoutErr.

pub fn extend(&self, next: Self) -> Result<(Self, usize), LayoutErr>

🔬 This is a nightly-only experimental API. (alloc_layout_extra #55724)

Creates a layout describing the record for self followed by next, including any necessary padding to ensure that next will be properly aligned. Note that the result layout will satisfy the alignment properties of both self and next.

The resulting layout will be the same as that of a C struct containing two fields with the layouts of self and next, in that order.

Returns Some((k, offset)), where k is layout of the concatenated record and offset is the relative location, in bytes, of the start of the next embedded within the concatenated record (assuming that the record itself starts at offset 0).

On arithmetic overflow, returns LayoutErr.

pub fn repeat_packed(&self, n: usize) -> Result<Self, LayoutErr>

🔬 This is a nightly-only experimental API. (alloc_layout_extra #55724)

Creates a layout describing the record for n instances of self, with no padding between each instance.

Note that, unlike repeat, repeat_packed does not guarantee that the repeated instances of self will be properly aligned, even if a given instance of self is properly aligned. In other words, if the layout returned by repeat_packed is used to allocate an array, it is not guaranteed that all elements in the array will be properly aligned.

On arithmetic overflow, returns LayoutErr.

pub fn extend_packed(&self, next: Self) -> Result<Self, LayoutErr>

🔬 This is a nightly-only experimental API. (alloc_layout_extra #55724)

Creates a layout describing the record for self followed by next with no additional padding between the two. Since no padding is inserted, the alignment of next is irrelevant, and is not incorporated at all into the resulting layout.

On arithmetic overflow, returns LayoutErr.

pub fn array<T>(n: usize) -> Result<Self, LayoutErr>

🔬 This is a nightly-only experimental API. (alloc_layout_extra #55724)

Creates a layout describing the record for a [T; n].

On arithmetic overflow, returns LayoutErr.

Trait Implementations

impl Copy for Layout

impl PartialEq<Layout> for Layout

fn eq(&self, other: &Layout) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Layout) -> bool

This method tests for !=.

impl Eq for Layout

impl Clone for Layout

fn clone(&self) -> Layout

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Layout

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.