]>
Commit | Line | Data |
---|---|---|
ba9703b0 XL |
1 | use crate::cmp; |
2 | use crate::fmt; | |
3 | use crate::mem; | |
4 | use crate::num::NonZeroUsize; | |
5 | use crate::ptr::NonNull; | |
6 | ||
7 | const fn size_align<T>() -> (usize, usize) { | |
8 | (mem::size_of::<T>(), mem::align_of::<T>()) | |
9 | } | |
10 | ||
11 | /// Layout of a block of memory. | |
12 | /// | |
13 | /// An instance of `Layout` describes a particular layout of memory. | |
14 | /// You build a `Layout` up as an input to give to an allocator. | |
15 | /// | |
16 | /// All layouts have an associated size and a power-of-two alignment. | |
17 | /// | |
18 | /// (Note that layouts are *not* required to have non-zero size, | |
19 | /// even though `GlobalAlloc` requires that all memory requests | |
20 | /// be non-zero in size. A caller must either ensure that conditions | |
21 | /// like this are met, use specific allocators with looser | |
22 | /// requirements, or use the more lenient `AllocRef` interface.) | |
23 | #[stable(feature = "alloc_layout", since = "1.28.0")] | |
24 | #[derive(Copy, Clone, Debug, PartialEq, Eq)] | |
25 | #[lang = "alloc_layout"] | |
26 | pub struct Layout { | |
27 | // size of the requested block of memory, measured in bytes. | |
28 | size_: usize, | |
29 | ||
30 | // alignment of the requested block of memory, measured in bytes. | |
31 | // we ensure that this is always a power-of-two, because API's | |
32 | // like `posix_memalign` require it and it is a reasonable | |
33 | // constraint to impose on Layout constructors. | |
34 | // | |
35 | // (However, we do not analogously require `align >= sizeof(void*)`, | |
36 | // even though that is *also* a requirement of `posix_memalign`.) | |
37 | align_: NonZeroUsize, | |
38 | } | |
39 | ||
40 | impl Layout { | |
41 | /// Constructs a `Layout` from a given `size` and `align`, | |
42 | /// or returns `LayoutErr` if any of the following conditions | |
43 | /// are not met: | |
44 | /// | |
45 | /// * `align` must not be zero, | |
46 | /// | |
47 | /// * `align` must be a power of two, | |
48 | /// | |
49 | /// * `size`, when rounded up to the nearest multiple of `align`, | |
50 | /// must not overflow (i.e., the rounded value must be less than | |
51 | /// or equal to `usize::MAX`). | |
52 | #[stable(feature = "alloc_layout", since = "1.28.0")] | |
53 | #[rustc_const_unstable(feature = "const_alloc_layout", issue = "67521")] | |
54 | #[inline] | |
55 | pub const fn from_size_align(size: usize, align: usize) -> Result<Self, LayoutErr> { | |
56 | if !align.is_power_of_two() { | |
57 | return Err(LayoutErr { private: () }); | |
58 | } | |
59 | ||
60 | // (power-of-two implies align != 0.) | |
61 | ||
62 | // Rounded up size is: | |
63 | // size_rounded_up = (size + align - 1) & !(align - 1); | |
64 | // | |
65 | // We know from above that align != 0. If adding (align - 1) | |
66 | // does not overflow, then rounding up will be fine. | |
67 | // | |
68 | // Conversely, &-masking with !(align - 1) will subtract off | |
69 | // only low-order-bits. Thus if overflow occurs with the sum, | |
70 | // the &-mask cannot subtract enough to undo that overflow. | |
71 | // | |
72 | // Above implies that checking for summation overflow is both | |
73 | // necessary and sufficient. | |
74 | if size > usize::MAX - (align - 1) { | |
75 | return Err(LayoutErr { private: () }); | |
76 | } | |
77 | ||
f9f354fc XL |
78 | // SAFETY: the conditions for `from_size_align_unchecked` have been |
79 | // checked above. | |
ba9703b0 XL |
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 | |
3dfed10e | 88 | /// [`Layout::from_size_align`]. |
ba9703b0 XL |
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 { | |
f035d41b XL |
93 | // SAFETY: the caller must ensure that `align` is greater than zero. |
94 | Layout { size_: size, align_: unsafe { NonZeroUsize::new_unchecked(align) } } | |
ba9703b0 XL |
95 | } |
96 | ||
97 | /// The minimum size in bytes for a memory block of this layout. | |
98 | #[stable(feature = "alloc_layout", since = "1.28.0")] | |
99 | #[rustc_const_unstable(feature = "const_alloc_layout", issue = "67521")] | |
100 | #[inline] | |
101 | pub const fn size(&self) -> usize { | |
102 | self.size_ | |
103 | } | |
104 | ||
105 | /// The minimum byte alignment for a memory block of this layout. | |
106 | #[stable(feature = "alloc_layout", since = "1.28.0")] | |
107 | #[rustc_const_unstable(feature = "const_alloc_layout", issue = "67521")] | |
108 | #[inline] | |
109 | pub const fn align(&self) -> usize { | |
110 | self.align_.get() | |
111 | } | |
112 | ||
113 | /// Constructs a `Layout` suitable for holding a value of type `T`. | |
114 | #[stable(feature = "alloc_layout", since = "1.28.0")] | |
115 | #[rustc_const_stable(feature = "alloc_layout_const_new", since = "1.42.0")] | |
116 | #[inline] | |
117 | pub const fn new<T>() -> Self { | |
118 | let (size, align) = size_align::<T>(); | |
f9f354fc | 119 | // SAFETY: the align is guaranteed by Rust to be a power of two and |
ba9703b0 XL |
120 | // the size+align combo is guaranteed to fit in our address space. As a |
121 | // result use the unchecked constructor here to avoid inserting code | |
122 | // that panics if it isn't optimized well enough. | |
123 | unsafe { Layout::from_size_align_unchecked(size, align) } | |
124 | } | |
125 | ||
126 | /// Produces layout describing a record that could be used to | |
127 | /// allocate backing structure for `T` (which could be a trait | |
128 | /// or other unsized type like a slice). | |
129 | #[stable(feature = "alloc_layout", since = "1.28.0")] | |
130 | #[inline] | |
131 | pub fn for_value<T: ?Sized>(t: &T) -> Self { | |
132 | let (size, align) = (mem::size_of_val(t), mem::align_of_val(t)); | |
ba9703b0 | 133 | debug_assert!(Layout::from_size_align(size, align).is_ok()); |
3dfed10e XL |
134 | // SAFETY: see rationale in `new` for why this is using the unsafe variant |
135 | unsafe { Layout::from_size_align_unchecked(size, align) } | |
136 | } | |
137 | ||
138 | /// Produces layout describing a record that could be used to | |
139 | /// allocate backing structure for `T` (which could be a trait | |
140 | /// or other unsized type like a slice). | |
141 | /// | |
142 | /// # Safety | |
143 | /// | |
144 | /// This function is only safe to call if the following conditions hold: | |
145 | /// | |
146 | /// - If `T` is `Sized`, this function is always safe to call. | |
147 | /// - If the unsized tail of `T` is: | |
148 | /// - a [slice], then the length of the slice tail must be an intialized | |
149 | /// integer, and the size of the *entire value* | |
150 | /// (dynamic tail length + statically sized prefix) must fit in `isize`. | |
151 | /// - a [trait object], then the vtable part of the pointer must point | |
152 | /// to a valid vtable for the type `T` acquired by an unsizing coersion, | |
153 | /// and the size of the *entire value* | |
154 | /// (dynamic tail length + statically sized prefix) must fit in `isize`. | |
155 | /// - an (unstable) [extern type], then this function is always safe to | |
156 | /// call, but may panic or otherwise return the wrong value, as the | |
157 | /// extern type's layout is not known. This is the same behavior as | |
158 | /// [`Layout::for_value`] on a reference to an extern type tail. | |
159 | /// - otherwise, it is conservatively not allowed to call this function. | |
160 | /// | |
161 | /// [slice]: ../../std/primitive.slice.html | |
162 | /// [trait object]: ../../book/ch17-02-trait-objects.html | |
163 | /// [extern type]: ../../unstable-book/language-features/extern-types.html | |
164 | #[unstable(feature = "layout_for_ptr", issue = "69835")] | |
165 | pub unsafe fn for_value_raw<T: ?Sized>(t: *const T) -> Self { | |
166 | // SAFETY: we pass along the prerequisites of these functions to the caller | |
167 | let (size, align) = unsafe { (mem::size_of_val_raw(t), mem::align_of_val_raw(t)) }; | |
168 | debug_assert!(Layout::from_size_align(size, align).is_ok()); | |
169 | // SAFETY: see rationale in `new` for why this is using the unsafe variant | |
ba9703b0 XL |
170 | unsafe { Layout::from_size_align_unchecked(size, align) } |
171 | } | |
172 | ||
173 | /// Creates a `NonNull` that is dangling, but well-aligned for this Layout. | |
174 | /// | |
175 | /// Note that the pointer value may potentially represent a valid pointer, | |
176 | /// which means this must not be used as a "not yet initialized" | |
177 | /// sentinel value. Types that lazily allocate must track initialization by | |
178 | /// some other means. | |
179 | #[unstable(feature = "alloc_layout_extra", issue = "55724")] | |
1b1a35ee | 180 | #[rustc_const_unstable(feature = "alloc_layout_extra", issue = "55724")] |
ba9703b0 XL |
181 | #[inline] |
182 | pub const fn dangling(&self) -> NonNull<u8> { | |
f9f354fc | 183 | // SAFETY: align is guaranteed to be non-zero |
ba9703b0 XL |
184 | unsafe { NonNull::new_unchecked(self.align() as *mut u8) } |
185 | } | |
186 | ||
187 | /// Creates a layout describing the record that can hold a value | |
188 | /// of the same layout as `self`, but that also is aligned to | |
189 | /// alignment `align` (measured in bytes). | |
190 | /// | |
191 | /// If `self` already meets the prescribed alignment, then returns | |
192 | /// `self`. | |
193 | /// | |
194 | /// Note that this method does not add any padding to the overall | |
195 | /// size, regardless of whether the returned layout has a different | |
196 | /// alignment. In other words, if `K` has size 16, `K.align_to(32)` | |
197 | /// will *still* have size 16. | |
198 | /// | |
199 | /// Returns an error if the combination of `self.size()` and the given | |
3dfed10e | 200 | /// `align` violates the conditions listed in [`Layout::from_size_align`]. |
ba9703b0 XL |
201 | #[stable(feature = "alloc_layout_manipulation", since = "1.44.0")] |
202 | #[inline] | |
203 | pub fn align_to(&self, align: usize) -> Result<Self, LayoutErr> { | |
204 | Layout::from_size_align(self.size(), cmp::max(self.align(), align)) | |
205 | } | |
206 | ||
207 | /// Returns the amount of padding we must insert after `self` | |
208 | /// to ensure that the following address will satisfy `align` | |
209 | /// (measured in bytes). | |
210 | /// | |
211 | /// e.g., if `self.size()` is 9, then `self.padding_needed_for(4)` | |
212 | /// returns 3, because that is the minimum number of bytes of | |
213 | /// padding required to get a 4-aligned address (assuming that the | |
214 | /// corresponding memory block starts at a 4-aligned address). | |
215 | /// | |
216 | /// The return value of this function has no meaning if `align` is | |
217 | /// not a power-of-two. | |
218 | /// | |
219 | /// Note that the utility of the returned value requires `align` | |
220 | /// to be less than or equal to the alignment of the starting | |
221 | /// address for the whole allocated block of memory. One way to | |
222 | /// satisfy this constraint is to ensure `align <= self.align()`. | |
223 | #[unstable(feature = "alloc_layout_extra", issue = "55724")] | |
224 | #[rustc_const_unstable(feature = "const_alloc_layout", issue = "67521")] | |
225 | #[inline] | |
226 | pub const fn padding_needed_for(&self, align: usize) -> usize { | |
227 | let len = self.size(); | |
228 | ||
229 | // Rounded up value is: | |
230 | // len_rounded_up = (len + align - 1) & !(align - 1); | |
231 | // and then we return the padding difference: `len_rounded_up - len`. | |
232 | // | |
233 | // We use modular arithmetic throughout: | |
234 | // | |
235 | // 1. align is guaranteed to be > 0, so align - 1 is always | |
236 | // valid. | |
237 | // | |
238 | // 2. `len + align - 1` can overflow by at most `align - 1`, | |
239 | // so the &-mask with `!(align - 1)` will ensure that in the | |
240 | // case of overflow, `len_rounded_up` will itself be 0. | |
241 | // Thus the returned padding, when added to `len`, yields 0, | |
242 | // which trivially satisfies the alignment `align`. | |
243 | // | |
244 | // (Of course, attempts to allocate blocks of memory whose | |
245 | // size and padding overflow in the above manner should cause | |
246 | // the allocator to yield an error anyway.) | |
247 | ||
248 | let len_rounded_up = len.wrapping_add(align).wrapping_sub(1) & !align.wrapping_sub(1); | |
249 | len_rounded_up.wrapping_sub(len) | |
250 | } | |
251 | ||
252 | /// Creates a layout by rounding the size of this layout up to a multiple | |
253 | /// of the layout's alignment. | |
254 | /// | |
255 | /// This is equivalent to adding the result of `padding_needed_for` | |
256 | /// to the layout's current size. | |
257 | #[stable(feature = "alloc_layout_manipulation", since = "1.44.0")] | |
258 | #[inline] | |
259 | pub fn pad_to_align(&self) -> Layout { | |
260 | let pad = self.padding_needed_for(self.align()); | |
261 | // This cannot overflow. Quoting from the invariant of Layout: | |
262 | // > `size`, when rounded up to the nearest multiple of `align`, | |
263 | // > must not overflow (i.e., the rounded value must be less than | |
264 | // > `usize::MAX`) | |
265 | let new_size = self.size() + pad; | |
266 | ||
267 | Layout::from_size_align(new_size, self.align()).unwrap() | |
268 | } | |
269 | ||
270 | /// Creates a layout describing the record for `n` instances of | |
271 | /// `self`, with a suitable amount of padding between each to | |
272 | /// ensure that each instance is given its requested size and | |
273 | /// alignment. On success, returns `(k, offs)` where `k` is the | |
274 | /// layout of the array and `offs` is the distance between the start | |
275 | /// of each element in the array. | |
276 | /// | |
277 | /// On arithmetic overflow, returns `LayoutErr`. | |
278 | #[unstable(feature = "alloc_layout_extra", issue = "55724")] | |
279 | #[inline] | |
280 | pub fn repeat(&self, n: usize) -> Result<(Self, usize), LayoutErr> { | |
281 | // This cannot overflow. Quoting from the invariant of Layout: | |
282 | // > `size`, when rounded up to the nearest multiple of `align`, | |
283 | // > must not overflow (i.e., the rounded value must be less than | |
284 | // > `usize::MAX`) | |
285 | let padded_size = self.size() + self.padding_needed_for(self.align()); | |
286 | let alloc_size = padded_size.checked_mul(n).ok_or(LayoutErr { private: () })?; | |
287 | ||
f9f354fc XL |
288 | // SAFETY: self.align is already known to be valid and alloc_size has been |
289 | // padded already. | |
290 | unsafe { Ok((Layout::from_size_align_unchecked(alloc_size, self.align()), padded_size)) } | |
ba9703b0 XL |
291 | } |
292 | ||
293 | /// Creates a layout describing the record for `self` followed by | |
294 | /// `next`, including any necessary padding to ensure that `next` | |
295 | /// will be properly aligned, but *no trailing padding*. | |
296 | /// | |
297 | /// In order to match C representation layout `repr(C)`, you should | |
298 | /// call `pad_to_align` after extending the layout with all fields. | |
299 | /// (There is no way to match the default Rust representation | |
300 | /// layout `repr(Rust)`, as it is unspecified.) | |
301 | /// | |
302 | /// Note that the alignment of the resulting layout will be the maximum of | |
303 | /// those of `self` and `next`, in order to ensure alignment of both parts. | |
304 | /// | |
305 | /// Returns `Ok((k, offset))`, where `k` is layout of the concatenated | |
306 | /// record and `offset` is the relative location, in bytes, of the | |
307 | /// start of the `next` embedded within the concatenated record | |
308 | /// (assuming that the record itself starts at offset 0). | |
309 | /// | |
310 | /// On arithmetic overflow, returns `LayoutErr`. | |
311 | /// | |
312 | /// # Examples | |
313 | /// | |
314 | /// To calculate the layout of a `#[repr(C)]` structure and the offsets of | |
315 | /// the fields from its fields' layouts: | |
316 | /// | |
317 | /// ```rust | |
318 | /// # use std::alloc::{Layout, LayoutErr}; | |
319 | /// pub fn repr_c(fields: &[Layout]) -> Result<(Layout, Vec<usize>), LayoutErr> { | |
320 | /// let mut offsets = Vec::new(); | |
321 | /// let mut layout = Layout::from_size_align(0, 1)?; | |
322 | /// for &field in fields { | |
323 | /// let (new_layout, offset) = layout.extend(field)?; | |
324 | /// layout = new_layout; | |
325 | /// offsets.push(offset); | |
326 | /// } | |
327 | /// // Remember to finalize with `pad_to_align`! | |
328 | /// Ok((layout.pad_to_align(), offsets)) | |
329 | /// } | |
330 | /// # // test that it works | |
331 | /// # #[repr(C)] struct S { a: u64, b: u32, c: u16, d: u32 } | |
332 | /// # let s = Layout::new::<S>(); | |
333 | /// # let u16 = Layout::new::<u16>(); | |
334 | /// # let u32 = Layout::new::<u32>(); | |
335 | /// # let u64 = Layout::new::<u64>(); | |
336 | /// # assert_eq!(repr_c(&[u64, u32, u16, u32]), Ok((s, vec![0, 8, 12, 16]))); | |
337 | /// ``` | |
338 | #[stable(feature = "alloc_layout_manipulation", since = "1.44.0")] | |
339 | #[inline] | |
340 | pub fn extend(&self, next: Self) -> Result<(Self, usize), LayoutErr> { | |
341 | let new_align = cmp::max(self.align(), next.align()); | |
342 | let pad = self.padding_needed_for(next.align()); | |
343 | ||
344 | let offset = self.size().checked_add(pad).ok_or(LayoutErr { private: () })?; | |
345 | let new_size = offset.checked_add(next.size()).ok_or(LayoutErr { private: () })?; | |
346 | ||
347 | let layout = Layout::from_size_align(new_size, new_align)?; | |
348 | Ok((layout, offset)) | |
349 | } | |
350 | ||
351 | /// Creates a layout describing the record for `n` instances of | |
352 | /// `self`, with no padding between each instance. | |
353 | /// | |
354 | /// Note that, unlike `repeat`, `repeat_packed` does not guarantee | |
355 | /// that the repeated instances of `self` will be properly | |
356 | /// aligned, even if a given instance of `self` is properly | |
357 | /// aligned. In other words, if the layout returned by | |
358 | /// `repeat_packed` is used to allocate an array, it is not | |
359 | /// guaranteed that all elements in the array will be properly | |
360 | /// aligned. | |
361 | /// | |
362 | /// On arithmetic overflow, returns `LayoutErr`. | |
363 | #[unstable(feature = "alloc_layout_extra", issue = "55724")] | |
364 | #[inline] | |
365 | pub fn repeat_packed(&self, n: usize) -> Result<Self, LayoutErr> { | |
366 | let size = self.size().checked_mul(n).ok_or(LayoutErr { private: () })?; | |
367 | Layout::from_size_align(size, self.align()) | |
368 | } | |
369 | ||
370 | /// Creates a layout describing the record for `self` followed by | |
371 | /// `next` with no additional padding between the two. Since no | |
372 | /// padding is inserted, the alignment of `next` is irrelevant, | |
373 | /// and is not incorporated *at all* into the resulting layout. | |
374 | /// | |
375 | /// On arithmetic overflow, returns `LayoutErr`. | |
376 | #[unstable(feature = "alloc_layout_extra", issue = "55724")] | |
377 | #[inline] | |
378 | pub fn extend_packed(&self, next: Self) -> Result<Self, LayoutErr> { | |
379 | let new_size = self.size().checked_add(next.size()).ok_or(LayoutErr { private: () })?; | |
380 | Layout::from_size_align(new_size, self.align()) | |
381 | } | |
382 | ||
383 | /// Creates a layout describing the record for a `[T; n]`. | |
384 | /// | |
385 | /// On arithmetic overflow, returns `LayoutErr`. | |
386 | #[stable(feature = "alloc_layout_manipulation", since = "1.44.0")] | |
387 | #[inline] | |
388 | pub fn array<T>(n: usize) -> Result<Self, LayoutErr> { | |
389 | let (layout, offset) = Layout::new::<T>().repeat(n)?; | |
390 | debug_assert_eq!(offset, mem::size_of::<T>()); | |
391 | Ok(layout.pad_to_align()) | |
392 | } | |
393 | } | |
394 | ||
395 | /// The parameters given to `Layout::from_size_align` | |
396 | /// or some other `Layout` constructor | |
397 | /// do not satisfy its documented constraints. | |
398 | #[stable(feature = "alloc_layout", since = "1.28.0")] | |
399 | #[derive(Clone, PartialEq, Eq, Debug)] | |
400 | pub struct LayoutErr { | |
401 | private: (), | |
402 | } | |
403 | ||
404 | // (we need this for downstream impl of trait Error) | |
405 | #[stable(feature = "alloc_layout", since = "1.28.0")] | |
406 | impl fmt::Display for LayoutErr { | |
407 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { | |
408 | f.write_str("invalid parameters to Layout::from_size_align") | |
409 | } | |
410 | } |