|
| 1 | +// ignore-tidy-undocumented-unsafe |
| 2 | + |
| 3 | +use crate::cmp; |
| 4 | +use crate::fmt; |
| 5 | +use crate::mem; |
| 6 | +use crate::num::NonZeroUsize; |
| 7 | +use crate::ptr::NonNull; |
| 8 | + |
| 9 | +const fn size_align<T>() -> (usize, usize) { |
| 10 | + (mem::size_of::<T>(), mem::align_of::<T>()) |
| 11 | +} |
| 12 | + |
| 13 | +/// Layout of a block of memory. |
| 14 | +/// |
| 15 | +/// An instance of `Layout` describes a particular layout of memory. |
| 16 | +/// You build a `Layout` up as an input to give to an allocator. |
| 17 | +/// |
| 18 | +/// All layouts have an associated size and a power-of-two alignment. |
| 19 | +/// |
| 20 | +/// (Note that layouts are *not* required to have non-zero size, |
| 21 | +/// even though `GlobalAlloc` requires that all memory requests |
| 22 | +/// be non-zero in size. A caller must either ensure that conditions |
| 23 | +/// like this are met, use specific allocators with looser |
| 24 | +/// requirements, or use the more lenient `AllocRef` interface.) |
| 25 | +#[stable(feature = "alloc_layout", since = "1.28.0")] |
| 26 | +#[derive(Copy, Clone, Debug, PartialEq, Eq)] |
| 27 | +#[lang = "alloc_layout"] |
| 28 | +pub struct Layout { |
| 29 | + // size of the requested block of memory, measured in bytes. |
| 30 | + size_: usize, |
| 31 | + |
| 32 | + // alignment of the requested block of memory, measured in bytes. |
| 33 | + // we ensure that this is always a power-of-two, because API's |
| 34 | + // like `posix_memalign` require it and it is a reasonable |
| 35 | + // constraint to impose on Layout constructors. |
| 36 | + // |
| 37 | + // (However, we do not analogously require `align >= sizeof(void*)`, |
| 38 | + // even though that is *also* a requirement of `posix_memalign`.) |
| 39 | + align_: NonZeroUsize, |
| 40 | +} |
| 41 | + |
| 42 | +impl Layout { |
| 43 | + /// Constructs a `Layout` from a given `size` and `align`, |
| 44 | + /// or returns `LayoutErr` if any of the following conditions |
| 45 | + /// are not met: |
| 46 | + /// |
| 47 | + /// * `align` must not be zero, |
| 48 | + /// |
| 49 | + /// * `align` must be a power of two, |
| 50 | + /// |
| 51 | + /// * `size`, when rounded up to the nearest multiple of `align`, |
| 52 | + /// must not overflow (i.e., the rounded value must be less than |
| 53 | + /// or equal to `usize::MAX`). |
| 54 | + #[stable(feature = "alloc_layout", since = "1.28.0")] |
| 55 | + #[rustc_const_unstable(feature = "const_alloc_layout", issue = "67521")] |
| 56 | + #[inline] |
| 57 | + pub const fn from_size_align(size: usize, align: usize) -> Result<Self, LayoutErr> { |
| 58 | + if !align.is_power_of_two() { |
| 59 | + return Err(LayoutErr { private: () }); |
| 60 | + } |
| 61 | + |
| 62 | + // (power-of-two implies align != 0.) |
| 63 | + |
| 64 | + // Rounded up size is: |
| 65 | + // size_rounded_up = (size + align - 1) & !(align - 1); |
| 66 | + // |
| 67 | + // We know from above that align != 0. If adding (align - 1) |
| 68 | + // does not overflow, then rounding up will be fine. |
| 69 | + // |
| 70 | + // Conversely, &-masking with !(align - 1) will subtract off |
| 71 | + // only low-order-bits. Thus if overflow occurs with the sum, |
| 72 | + // the &-mask cannot subtract enough to undo that overflow. |
| 73 | + // |
| 74 | + // Above implies that checking for summation overflow is both |
| 75 | + // necessary and sufficient. |
| 76 | + if size > usize::MAX - (align - 1) { |
| 77 | + return Err(LayoutErr { private: () }); |
| 78 | + } |
| 79 | + |
| 80 | + unsafe { Ok(Layout::from_size_align_unchecked(size, align)) } |
| 81 | + } |
| 82 | + |
| 83 | + /// Creates a layout, bypassing all checks. |
| 84 | + /// |
| 85 | + /// # Safety |
| 86 | + /// |
| 87 | + /// This function is unsafe as it does not verify the preconditions from |
| 88 | + /// [`Layout::from_size_align`](#method.from_size_align). |
| 89 | + #[stable(feature = "alloc_layout", since = "1.28.0")] |
| 90 | + #[rustc_const_stable(feature = "alloc_layout", since = "1.28.0")] |
| 91 | + #[inline] |
| 92 | + pub const unsafe fn from_size_align_unchecked(size: usize, align: usize) -> Self { |
| 93 | + Layout { size_: size, align_: NonZeroUsize::new_unchecked(align) } |
| 94 | + } |
| 95 | + |
| 96 | + /// The minimum size in bytes for a memory block of this layout. |
| 97 | + #[stable(feature = "alloc_layout", since = "1.28.0")] |
| 98 | + #[rustc_const_unstable(feature = "const_alloc_layout", issue = "67521")] |
| 99 | + #[inline] |
| 100 | + pub const fn size(&self) -> usize { |
| 101 | + self.size_ |
| 102 | + } |
| 103 | + |
| 104 | + /// The minimum byte alignment for a memory block of this layout. |
| 105 | + #[stable(feature = "alloc_layout", since = "1.28.0")] |
| 106 | + #[rustc_const_unstable(feature = "const_alloc_layout", issue = "67521")] |
| 107 | + #[inline] |
| 108 | + pub const fn align(&self) -> usize { |
| 109 | + self.align_.get() |
| 110 | + } |
| 111 | + |
| 112 | + /// Constructs a `Layout` suitable for holding a value of type `T`. |
| 113 | + #[stable(feature = "alloc_layout", since = "1.28.0")] |
| 114 | + #[rustc_const_stable(feature = "alloc_layout_const_new", since = "1.42.0")] |
| 115 | + #[inline] |
| 116 | + pub const fn new<T>() -> Self { |
| 117 | + let (size, align) = size_align::<T>(); |
| 118 | + // Note that the align is guaranteed by rustc to be a power of two and |
| 119 | + // the size+align combo is guaranteed to fit in our address space. As a |
| 120 | + // result use the unchecked constructor here to avoid inserting code |
| 121 | + // that panics if it isn't optimized well enough. |
| 122 | + unsafe { Layout::from_size_align_unchecked(size, align) } |
| 123 | + } |
| 124 | + |
| 125 | + /// Produces layout describing a record that could be used to |
| 126 | + /// allocate backing structure for `T` (which could be a trait |
| 127 | + /// or other unsized type like a slice). |
| 128 | + #[stable(feature = "alloc_layout", since = "1.28.0")] |
| 129 | + #[inline] |
| 130 | + pub fn for_value<T: ?Sized>(t: &T) -> Self { |
| 131 | + let (size, align) = (mem::size_of_val(t), mem::align_of_val(t)); |
| 132 | + // See rationale in `new` for why this is using an unsafe variant below |
| 133 | + debug_assert!(Layout::from_size_align(size, align).is_ok()); |
| 134 | + unsafe { Layout::from_size_align_unchecked(size, align) } |
| 135 | + } |
| 136 | + |
| 137 | + /// Creates a `NonNull` that is dangling, but well-aligned for this Layout. |
| 138 | + /// |
| 139 | + /// Note that the pointer value may potentially represent a valid pointer, |
| 140 | + /// which means this must not be used as a "not yet initialized" |
| 141 | + /// sentinel value. Types that lazily allocate must track initialization by |
| 142 | + /// some other means. |
| 143 | + #[unstable(feature = "alloc_layout_extra", issue = "55724")] |
| 144 | + #[inline] |
| 145 | + pub const fn dangling(&self) -> NonNull<u8> { |
| 146 | + // align is non-zero and a power of two |
| 147 | + unsafe { NonNull::new_unchecked(self.align() as *mut u8) } |
| 148 | + } |
| 149 | + |
| 150 | + /// Creates a layout describing the record that can hold a value |
| 151 | + /// of the same layout as `self`, but that also is aligned to |
| 152 | + /// alignment `align` (measured in bytes). |
| 153 | + /// |
| 154 | + /// If `self` already meets the prescribed alignment, then returns |
| 155 | + /// `self`. |
| 156 | + /// |
| 157 | + /// Note that this method does not add any padding to the overall |
| 158 | + /// size, regardless of whether the returned layout has a different |
| 159 | + /// alignment. In other words, if `K` has size 16, `K.align_to(32)` |
| 160 | + /// will *still* have size 16. |
| 161 | + /// |
| 162 | + /// Returns an error if the combination of `self.size()` and the given |
| 163 | + /// `align` violates the conditions listed in |
| 164 | + /// [`Layout::from_size_align`](#method.from_size_align). |
| 165 | + #[unstable(feature = "alloc_layout_extra", issue = "55724")] |
| 166 | + #[inline] |
| 167 | + pub fn align_to(&self, align: usize) -> Result<Self, LayoutErr> { |
| 168 | + Layout::from_size_align(self.size(), cmp::max(self.align(), align)) |
| 169 | + } |
| 170 | + |
| 171 | + /// Returns the amount of padding we must insert after `self` |
| 172 | + /// to ensure that the following address will satisfy `align` |
| 173 | + /// (measured in bytes). |
| 174 | + /// |
| 175 | + /// e.g., if `self.size()` is 9, then `self.padding_needed_for(4)` |
| 176 | + /// returns 3, because that is the minimum number of bytes of |
| 177 | + /// padding required to get a 4-aligned address (assuming that the |
| 178 | + /// corresponding memory block starts at a 4-aligned address). |
| 179 | + /// |
| 180 | + /// The return value of this function has no meaning if `align` is |
| 181 | + /// not a power-of-two. |
| 182 | + /// |
| 183 | + /// Note that the utility of the returned value requires `align` |
| 184 | + /// to be less than or equal to the alignment of the starting |
| 185 | + /// address for the whole allocated block of memory. One way to |
| 186 | + /// satisfy this constraint is to ensure `align <= self.align()`. |
| 187 | + #[unstable(feature = "alloc_layout_extra", issue = "55724")] |
| 188 | + #[rustc_const_unstable(feature = "const_alloc_layout", issue = "67521")] |
| 189 | + #[inline] |
| 190 | + pub const fn padding_needed_for(&self, align: usize) -> usize { |
| 191 | + let len = self.size(); |
| 192 | + |
| 193 | + // Rounded up value is: |
| 194 | + // len_rounded_up = (len + align - 1) & !(align - 1); |
| 195 | + // and then we return the padding difference: `len_rounded_up - len`. |
| 196 | + // |
| 197 | + // We use modular arithmetic throughout: |
| 198 | + // |
| 199 | + // 1. align is guaranteed to be > 0, so align - 1 is always |
| 200 | + // valid. |
| 201 | + // |
| 202 | + // 2. `len + align - 1` can overflow by at most `align - 1`, |
| 203 | + // so the &-mask with `!(align - 1)` will ensure that in the |
| 204 | + // case of overflow, `len_rounded_up` will itself be 0. |
| 205 | + // Thus the returned padding, when added to `len`, yields 0, |
| 206 | + // which trivially satisfies the alignment `align`. |
| 207 | + // |
| 208 | + // (Of course, attempts to allocate blocks of memory whose |
| 209 | + // size and padding overflow in the above manner should cause |
| 210 | + // the allocator to yield an error anyway.) |
| 211 | + |
| 212 | + let len_rounded_up = len.wrapping_add(align).wrapping_sub(1) & !align.wrapping_sub(1); |
| 213 | + len_rounded_up.wrapping_sub(len) |
| 214 | + } |
| 215 | + |
| 216 | + /// Creates a layout by rounding the size of this layout up to a multiple |
| 217 | + /// of the layout's alignment. |
| 218 | + /// |
| 219 | + /// This is equivalent to adding the result of `padding_needed_for` |
| 220 | + /// to the layout's current size. |
| 221 | + #[unstable(feature = "alloc_layout_extra", issue = "55724")] |
| 222 | + #[inline] |
| 223 | + pub fn pad_to_align(&self) -> Layout { |
| 224 | + let pad = self.padding_needed_for(self.align()); |
| 225 | + // This cannot overflow. Quoting from the invariant of Layout: |
| 226 | + // > `size`, when rounded up to the nearest multiple of `align`, |
| 227 | + // > must not overflow (i.e., the rounded value must be less than |
| 228 | + // > `usize::MAX`) |
| 229 | + let new_size = self.size() + pad; |
| 230 | + |
| 231 | + Layout::from_size_align(new_size, self.align()).unwrap() |
| 232 | + } |
| 233 | + |
| 234 | + /// Creates a layout describing the record for `n` instances of |
| 235 | + /// `self`, with a suitable amount of padding between each to |
| 236 | + /// ensure that each instance is given its requested size and |
| 237 | + /// alignment. On success, returns `(k, offs)` where `k` is the |
| 238 | + /// layout of the array and `offs` is the distance between the start |
| 239 | + /// of each element in the array. |
| 240 | + /// |
| 241 | + /// On arithmetic overflow, returns `LayoutErr`. |
| 242 | + #[unstable(feature = "alloc_layout_extra", issue = "55724")] |
| 243 | + #[inline] |
| 244 | + pub fn repeat(&self, n: usize) -> Result<(Self, usize), LayoutErr> { |
| 245 | + // This cannot overflow. Quoting from the invariant of Layout: |
| 246 | + // > `size`, when rounded up to the nearest multiple of `align`, |
| 247 | + // > must not overflow (i.e., the rounded value must be less than |
| 248 | + // > `usize::MAX`) |
| 249 | + let padded_size = self.size() + self.padding_needed_for(self.align()); |
| 250 | + let alloc_size = padded_size.checked_mul(n).ok_or(LayoutErr { private: () })?; |
| 251 | + |
| 252 | + unsafe { |
| 253 | + // self.align is already known to be valid and alloc_size has been |
| 254 | + // padded already. |
| 255 | + Ok((Layout::from_size_align_unchecked(alloc_size, self.align()), padded_size)) |
| 256 | + } |
| 257 | + } |
| 258 | + |
| 259 | + /// Creates a layout describing the record for `self` followed by |
| 260 | + /// `next`, including any necessary padding to ensure that `next` |
| 261 | + /// will be properly aligned. Note that the resulting layout will |
| 262 | + /// satisfy the alignment properties of both `self` and `next`. |
| 263 | + /// |
| 264 | + /// The resulting layout will be the same as that of a C struct containing |
| 265 | + /// two fields with the layouts of `self` and `next`, in that order. |
| 266 | + /// |
| 267 | + /// Returns `Some((k, offset))`, where `k` is layout of the concatenated |
| 268 | + /// record and `offset` is the relative location, in bytes, of the |
| 269 | + /// start of the `next` embedded within the concatenated record |
| 270 | + /// (assuming that the record itself starts at offset 0). |
| 271 | + /// |
| 272 | + /// On arithmetic overflow, returns `LayoutErr`. |
| 273 | + #[unstable(feature = "alloc_layout_extra", issue = "55724")] |
| 274 | + #[inline] |
| 275 | + pub fn extend(&self, next: Self) -> Result<(Self, usize), LayoutErr> { |
| 276 | + let new_align = cmp::max(self.align(), next.align()); |
| 277 | + let pad = self.padding_needed_for(next.align()); |
| 278 | + |
| 279 | + let offset = self.size().checked_add(pad).ok_or(LayoutErr { private: () })?; |
| 280 | + let new_size = offset.checked_add(next.size()).ok_or(LayoutErr { private: () })?; |
| 281 | + |
| 282 | + let layout = Layout::from_size_align(new_size, new_align)?; |
| 283 | + Ok((layout, offset)) |
| 284 | + } |
| 285 | + |
| 286 | + /// Creates a layout describing the record for `n` instances of |
| 287 | + /// `self`, with no padding between each instance. |
| 288 | + /// |
| 289 | + /// Note that, unlike `repeat`, `repeat_packed` does not guarantee |
| 290 | + /// that the repeated instances of `self` will be properly |
| 291 | + /// aligned, even if a given instance of `self` is properly |
| 292 | + /// aligned. In other words, if the layout returned by |
| 293 | + /// `repeat_packed` is used to allocate an array, it is not |
| 294 | + /// guaranteed that all elements in the array will be properly |
| 295 | + /// aligned. |
| 296 | + /// |
| 297 | + /// On arithmetic overflow, returns `LayoutErr`. |
| 298 | + #[unstable(feature = "alloc_layout_extra", issue = "55724")] |
| 299 | + #[inline] |
| 300 | + pub fn repeat_packed(&self, n: usize) -> Result<Self, LayoutErr> { |
| 301 | + let size = self.size().checked_mul(n).ok_or(LayoutErr { private: () })?; |
| 302 | + Layout::from_size_align(size, self.align()) |
| 303 | + } |
| 304 | + |
| 305 | + /// Creates a layout describing the record for `self` followed by |
| 306 | + /// `next` with no additional padding between the two. Since no |
| 307 | + /// padding is inserted, the alignment of `next` is irrelevant, |
| 308 | + /// and is not incorporated *at all* into the resulting layout. |
| 309 | + /// |
| 310 | + /// On arithmetic overflow, returns `LayoutErr`. |
| 311 | + #[unstable(feature = "alloc_layout_extra", issue = "55724")] |
| 312 | + #[inline] |
| 313 | + pub fn extend_packed(&self, next: Self) -> Result<Self, LayoutErr> { |
| 314 | + let new_size = self.size().checked_add(next.size()).ok_or(LayoutErr { private: () })?; |
| 315 | + Layout::from_size_align(new_size, self.align()) |
| 316 | + } |
| 317 | + |
| 318 | + /// Creates a layout describing the record for a `[T; n]`. |
| 319 | + /// |
| 320 | + /// On arithmetic overflow, returns `LayoutErr`. |
| 321 | + #[unstable(feature = "alloc_layout_extra", issue = "55724")] |
| 322 | + #[inline] |
| 323 | + pub fn array<T>(n: usize) -> Result<Self, LayoutErr> { |
| 324 | + Layout::new::<T>().repeat(n).map(|(k, offs)| { |
| 325 | + debug_assert!(offs == mem::size_of::<T>()); |
| 326 | + k |
| 327 | + }) |
| 328 | + } |
| 329 | +} |
| 330 | + |
| 331 | +/// The parameters given to `Layout::from_size_align` |
| 332 | +/// or some other `Layout` constructor |
| 333 | +/// do not satisfy its documented constraints. |
| 334 | +#[stable(feature = "alloc_layout", since = "1.28.0")] |
| 335 | +#[derive(Clone, PartialEq, Eq, Debug)] |
| 336 | +pub struct LayoutErr { |
| 337 | + private: (), |
| 338 | +} |
| 339 | + |
| 340 | +// (we need this for downstream impl of trait Error) |
| 341 | +#[stable(feature = "alloc_layout", since = "1.28.0")] |
| 342 | +impl fmt::Display for LayoutErr { |
| 343 | + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| 344 | + f.write_str("invalid parameters to Layout::from_size_align") |
| 345 | + } |
| 346 | +} |
0 commit comments