/// * `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
+ /// must not overflow (i.e., the rounded value must be less than
/// `usize::MAX`).
#[stable(feature = "alloc_layout", since = "1.28.0")]
#[inline]
/// 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)`
+ /// 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).
len_rounded_up.wrapping_sub(len)
}
+ /// 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.
+ #[unstable(feature = "alloc_layout_extra", issue = "55724")]
+ #[inline]
+ pub fn pad_to_align(&self) -> Result<Layout, LayoutErr> {
+ let pad = self.padding_needed_for(self.align());
+ let new_size = self.size().checked_add(pad)
+ .ok_or(LayoutErr { private: () })?;
+
+ Layout::from_size_align(new_size, self.align())
+ }
+
/// 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
/// if the caller does not ensure that `layout` has non-zero size.
///
/// (Extension subtraits might provide more specific bounds on
- /// behavior, e.g. guarantee a sentinel address or a null pointer
+ /// behavior, e.g., guarantee a sentinel address or a null pointer
/// in response to a zero-size allocation request.)
///
/// The allocated block of memory may or may not be initialized.
ptr
}
- /// Shink or grow a block of memory to the given `new_size`.
+ /// Shrink or grow a block of memory to the given `new_size`.
/// The block is described by the given `ptr` pointer and `layout`.
///
/// If this returns a non-null pointer, then ownership of the memory block
/// * `new_size` must be greater than zero.
///
/// * `new_size`, when rounded up to the nearest multiple of `layout.align()`,
- /// must not overflow (i.e. the rounded value must be less than `usize::MAX`).
+ /// must not overflow (i.e., the rounded value must be less than `usize::MAX`).
///
/// (Extension subtraits might provide more specific bounds on
- /// behavior, e.g. guarantee a sentinel address or a null pointer
+ /// behavior, e.g., guarantee a sentinel address or a null pointer
/// in response to a zero-size allocation request.)
///
/// # Errors
/// whether to return `Err`, or to return `Ok` with some pointer.
///
/// * If an `Alloc` implementation chooses to return `Ok` in this
-/// case (i.e. the pointer denotes a zero-sized inaccessible block)
+/// case (i.e., the pointer denotes a zero-sized inaccessible block)
/// then that returned pointer must be considered "currently
/// allocated". On such an allocator, *all* methods that take
/// currently-allocated pointers as inputs must accept these
///
/// * if a layout `k` fits a memory block (denoted by `ptr`)
/// currently allocated via an allocator `a`, then it is legal to
-/// use that layout to deallocate it, i.e. `a.dealloc(ptr, k);`.
+/// use that layout to deallocate it, i.e., `a.dealloc(ptr, k);`.
///
/// # Unsafety
///
// (Note: some existing allocators have unspecified but well-defined
// behavior in response to a zero size allocation request ;
- // e.g. in C, `malloc` of 0 will either return a null pointer or a
+ // e.g., in C, `malloc` of 0 will either return a null pointer or a
// unique pointer, but will not have arbitrary undefined
// behavior.
// However in jemalloc for example,
///
/// The returned block of storage may or may not have its contents
/// initialized. (Extension subtraits might restrict this
- /// behavior, e.g. to ensure initialization to particular sets of
+ /// behavior, e.g., to ensure initialization to particular sets of
/// bit patterns.)
///
/// # Safety
/// if the caller does not ensure that `layout` has non-zero size.
///
/// (Extension subtraits might provide more specific bounds on
- /// behavior, e.g. guarantee a sentinel address or a null pointer
+ /// behavior, e.g., guarantee a sentinel address or a null pointer
/// in response to a zero-size allocation request.)
///
/// # Errors
// realloc. alloc_excess, realloc_excess
/// Returns a pointer suitable for holding data described by
- /// a new layout with `layout`’s alginment and a size given
+ /// a new layout with `layout`’s alignment and a size given
/// by `new_size`. To
/// accomplish this, this may extend or shrink the allocation
/// referenced by `ptr` to fit the new layout.
/// * `new_size` must be greater than zero.
///
/// * `new_size`, when rounded up to the nearest multiple of `layout.align()`,
- /// must not overflow (i.e. the rounded value must be less than `usize::MAX`).
+ /// must not overflow (i.e., the rounded value must be less than `usize::MAX`).
///
/// (Extension subtraits might provide more specific bounds on
- /// behavior, e.g. guarantee a sentinel address or a null pointer
+ /// behavior, e.g., guarantee a sentinel address or a null pointer
/// in response to a zero-size allocation request.)
///
/// # Errors
projects / rust.git / blobdiff