1 | use crate::num::NonZero; |
2 | #[cfg (debug_assertions)] |
3 | use crate::ub_checks::assert_unsafe_precondition; |
4 | use crate::{cmp, fmt, hash, mem, num}; |
5 | |
6 | /// A type storing a `usize` which is a power of two, and thus |
7 | /// represents a possible alignment in the Rust abstract machine. |
8 | /// |
9 | /// Note that particularly large alignments, while representable in this type, |
10 | /// are likely not to be supported by actual allocators and linkers. |
11 | #[unstable (feature = "ptr_alignment_type" , issue = "102070" )] |
12 | #[derive (Copy, Clone, PartialEq, Eq)] |
13 | #[repr (transparent)] |
14 | pub struct Alignment(AlignmentEnum); |
15 | |
16 | // Alignment is `repr(usize)`, but via extra steps. |
17 | const _: () = assert!(mem::size_of::<Alignment>() == mem::size_of::<usize>()); |
18 | const _: () = assert!(mem::align_of::<Alignment>() == mem::align_of::<usize>()); |
19 | |
20 | fn _alignment_can_be_structurally_matched(a: Alignment) -> bool { |
21 | matches!(a, Alignment::MIN) |
22 | } |
23 | |
24 | impl Alignment { |
25 | /// The smallest possible alignment, 1. |
26 | /// |
27 | /// All addresses are always aligned at least this much. |
28 | /// |
29 | /// # Examples |
30 | /// |
31 | /// ``` |
32 | /// #![feature(ptr_alignment_type)] |
33 | /// use std::ptr::Alignment; |
34 | /// |
35 | /// assert_eq!(Alignment::MIN.as_usize(), 1); |
36 | /// ``` |
37 | #[unstable (feature = "ptr_alignment_type" , issue = "102070" )] |
38 | pub const MIN: Self = Self(AlignmentEnum::_Align1Shl0); |
39 | |
40 | /// Returns the alignment for a type. |
41 | /// |
42 | /// This provides the same numerical value as [`mem::align_of`], |
43 | /// but in an `Alignment` instead of a `usize`. |
44 | #[unstable (feature = "ptr_alignment_type" , issue = "102070" )] |
45 | #[rustc_const_unstable (feature = "ptr_alignment_type" , issue = "102070" )] |
46 | #[inline ] |
47 | pub const fn of<T>() -> Self { |
48 | // SAFETY: rustc ensures that type alignment is always a power of two. |
49 | unsafe { Alignment::new_unchecked(mem::align_of::<T>()) } |
50 | } |
51 | |
52 | /// Creates an `Alignment` from a `usize`, or returns `None` if it's |
53 | /// not a power of two. |
54 | /// |
55 | /// Note that `0` is not a power of two, nor a valid alignment. |
56 | #[unstable (feature = "ptr_alignment_type" , issue = "102070" )] |
57 | #[rustc_const_unstable (feature = "ptr_alignment_type" , issue = "102070" )] |
58 | #[inline ] |
59 | pub const fn new(align: usize) -> Option<Self> { |
60 | if align.is_power_of_two() { |
61 | // SAFETY: Just checked it only has one bit set |
62 | Some(unsafe { Self::new_unchecked(align) }) |
63 | } else { |
64 | None |
65 | } |
66 | } |
67 | |
68 | /// Creates an `Alignment` from a power-of-two `usize`. |
69 | /// |
70 | /// # Safety |
71 | /// |
72 | /// `align` must be a power of two. |
73 | /// |
74 | /// Equivalently, it must be `1 << exp` for some `exp` in `0..usize::BITS`. |
75 | /// It must *not* be zero. |
76 | #[unstable (feature = "ptr_alignment_type" , issue = "102070" )] |
77 | #[rustc_const_unstable (feature = "ptr_alignment_type" , issue = "102070" )] |
78 | #[inline ] |
79 | pub const unsafe fn new_unchecked(align: usize) -> Self { |
80 | #[cfg (debug_assertions)] |
81 | assert_unsafe_precondition!( |
82 | check_language_ub, |
83 | "Alignment::new_unchecked requires a power of two" , |
84 | (align: usize = align) => align.is_power_of_two() |
85 | ); |
86 | |
87 | // SAFETY: By precondition, this must be a power of two, and |
88 | // our variants encompass all possible powers of two. |
89 | unsafe { mem::transmute::<usize, Alignment>(align) } |
90 | } |
91 | |
92 | /// Returns the alignment as a [`usize`]. |
93 | #[unstable (feature = "ptr_alignment_type" , issue = "102070" )] |
94 | #[rustc_const_unstable (feature = "ptr_alignment_type" , issue = "102070" )] |
95 | #[inline ] |
96 | pub const fn as_usize(self) -> usize { |
97 | self.0 as usize |
98 | } |
99 | |
100 | /// Returns the alignment as a <code>[NonZero]<[usize]></code>. |
101 | #[unstable (feature = "ptr_alignment_type" , issue = "102070" )] |
102 | #[rustc_const_unstable (feature = "ptr_alignment_type" , issue = "102070" )] |
103 | #[inline ] |
104 | pub const fn as_nonzero(self) -> NonZero<usize> { |
105 | // SAFETY: All the discriminants are non-zero. |
106 | unsafe { NonZero::new_unchecked(self.as_usize()) } |
107 | } |
108 | |
109 | /// Returns the base-2 logarithm of the alignment. |
110 | /// |
111 | /// This is always exact, as `self` represents a power of two. |
112 | /// |
113 | /// # Examples |
114 | /// |
115 | /// ``` |
116 | /// #![feature(ptr_alignment_type)] |
117 | /// use std::ptr::Alignment; |
118 | /// |
119 | /// assert_eq!(Alignment::of::<u8>().log2(), 0); |
120 | /// assert_eq!(Alignment::new(1024).unwrap().log2(), 10); |
121 | /// ``` |
122 | #[unstable (feature = "ptr_alignment_type" , issue = "102070" )] |
123 | #[rustc_const_unstable (feature = "ptr_alignment_type" , issue = "102070" )] |
124 | #[inline ] |
125 | pub const fn log2(self) -> u32 { |
126 | self.as_nonzero().trailing_zeros() |
127 | } |
128 | |
129 | /// Returns a bit mask that can be used to match this alignment. |
130 | /// |
131 | /// This is equivalent to `!(self.as_usize() - 1)`. |
132 | /// |
133 | /// # Examples |
134 | /// |
135 | /// ``` |
136 | /// #![feature(ptr_alignment_type)] |
137 | /// #![feature(ptr_mask)] |
138 | /// use std::ptr::{Alignment, NonNull}; |
139 | /// |
140 | /// #[repr(align(1))] struct Align1(u8); |
141 | /// #[repr(align(2))] struct Align2(u16); |
142 | /// #[repr(align(4))] struct Align4(u32); |
143 | /// let one = <NonNull<Align1>>::dangling().as_ptr(); |
144 | /// let two = <NonNull<Align2>>::dangling().as_ptr(); |
145 | /// let four = <NonNull<Align4>>::dangling().as_ptr(); |
146 | /// |
147 | /// assert_eq!(four.mask(Alignment::of::<Align1>().mask()), four); |
148 | /// assert_eq!(four.mask(Alignment::of::<Align2>().mask()), four); |
149 | /// assert_eq!(four.mask(Alignment::of::<Align4>().mask()), four); |
150 | /// assert_ne!(one.mask(Alignment::of::<Align4>().mask()), one); |
151 | /// ``` |
152 | #[unstable (feature = "ptr_alignment_type" , issue = "102070" )] |
153 | #[rustc_const_unstable (feature = "ptr_alignment_type" , issue = "102070" )] |
154 | #[inline ] |
155 | pub const fn mask(self) -> usize { |
156 | // SAFETY: The alignment is always nonzero, and therefore decrementing won't overflow. |
157 | !(unsafe { self.as_usize().unchecked_sub(1) }) |
158 | } |
159 | } |
160 | |
161 | #[unstable (feature = "ptr_alignment_type" , issue = "102070" )] |
162 | impl fmt::Debug for Alignment { |
163 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
164 | write!(f, " {:?} (1 << {:?})" , self.as_nonzero(), self.log2()) |
165 | } |
166 | } |
167 | |
168 | #[unstable (feature = "ptr_alignment_type" , issue = "102070" )] |
169 | impl TryFrom<NonZero<usize>> for Alignment { |
170 | type Error = num::TryFromIntError; |
171 | |
172 | #[inline ] |
173 | fn try_from(align: NonZero<usize>) -> Result<Alignment, Self::Error> { |
174 | align.get().try_into() |
175 | } |
176 | } |
177 | |
178 | #[unstable (feature = "ptr_alignment_type" , issue = "102070" )] |
179 | impl TryFrom<usize> for Alignment { |
180 | type Error = num::TryFromIntError; |
181 | |
182 | #[inline ] |
183 | fn try_from(align: usize) -> Result<Alignment, Self::Error> { |
184 | Self::new(align).ok_or(err:num::TryFromIntError(())) |
185 | } |
186 | } |
187 | |
188 | #[unstable (feature = "ptr_alignment_type" , issue = "102070" )] |
189 | impl From<Alignment> for NonZero<usize> { |
190 | #[inline ] |
191 | fn from(align: Alignment) -> NonZero<usize> { |
192 | align.as_nonzero() |
193 | } |
194 | } |
195 | |
196 | #[unstable (feature = "ptr_alignment_type" , issue = "102070" )] |
197 | impl From<Alignment> for usize { |
198 | #[inline ] |
199 | fn from(align: Alignment) -> usize { |
200 | align.as_usize() |
201 | } |
202 | } |
203 | |
204 | #[rustc_const_unstable (feature = "const_alloc_layout" , issue = "67521" )] |
205 | #[unstable (feature = "ptr_alignment_type" , issue = "102070" )] |
206 | impl cmp::Ord for Alignment { |
207 | #[inline ] |
208 | fn cmp(&self, other: &Self) -> cmp::Ordering { |
209 | self.as_nonzero().get().cmp(&other.as_nonzero().get()) |
210 | } |
211 | } |
212 | |
213 | #[rustc_const_unstable (feature = "const_alloc_layout" , issue = "67521" )] |
214 | #[unstable (feature = "ptr_alignment_type" , issue = "102070" )] |
215 | impl cmp::PartialOrd for Alignment { |
216 | #[inline ] |
217 | fn partial_cmp(&self, other: &Self) -> Option<cmp::Ordering> { |
218 | Some(self.cmp(other)) |
219 | } |
220 | } |
221 | |
222 | #[unstable (feature = "ptr_alignment_type" , issue = "102070" )] |
223 | impl hash::Hash for Alignment { |
224 | #[inline ] |
225 | fn hash<H: hash::Hasher>(&self, state: &mut H) { |
226 | self.as_nonzero().hash(state) |
227 | } |
228 | } |
229 | |
230 | /// Returns [`Alignment::MIN`], which is valid for any type. |
231 | #[unstable (feature = "ptr_alignment_type" , issue = "102070" )] |
232 | impl Default for Alignment { |
233 | fn default() -> Alignment { |
234 | Alignment::MIN |
235 | } |
236 | } |
237 | |
238 | #[cfg (target_pointer_width = "16" )] |
239 | #[derive (Copy, Clone, PartialEq, Eq)] |
240 | #[repr (u16)] |
241 | enum AlignmentEnum { |
242 | _Align1Shl0 = 1 << 0, |
243 | _Align1Shl1 = 1 << 1, |
244 | _Align1Shl2 = 1 << 2, |
245 | _Align1Shl3 = 1 << 3, |
246 | _Align1Shl4 = 1 << 4, |
247 | _Align1Shl5 = 1 << 5, |
248 | _Align1Shl6 = 1 << 6, |
249 | _Align1Shl7 = 1 << 7, |
250 | _Align1Shl8 = 1 << 8, |
251 | _Align1Shl9 = 1 << 9, |
252 | _Align1Shl10 = 1 << 10, |
253 | _Align1Shl11 = 1 << 11, |
254 | _Align1Shl12 = 1 << 12, |
255 | _Align1Shl13 = 1 << 13, |
256 | _Align1Shl14 = 1 << 14, |
257 | _Align1Shl15 = 1 << 15, |
258 | } |
259 | |
260 | #[cfg (target_pointer_width = "32" )] |
261 | #[derive (Copy, Clone, PartialEq, Eq)] |
262 | #[repr (u32)] |
263 | enum AlignmentEnum { |
264 | _Align1Shl0 = 1 << 0, |
265 | _Align1Shl1 = 1 << 1, |
266 | _Align1Shl2 = 1 << 2, |
267 | _Align1Shl3 = 1 << 3, |
268 | _Align1Shl4 = 1 << 4, |
269 | _Align1Shl5 = 1 << 5, |
270 | _Align1Shl6 = 1 << 6, |
271 | _Align1Shl7 = 1 << 7, |
272 | _Align1Shl8 = 1 << 8, |
273 | _Align1Shl9 = 1 << 9, |
274 | _Align1Shl10 = 1 << 10, |
275 | _Align1Shl11 = 1 << 11, |
276 | _Align1Shl12 = 1 << 12, |
277 | _Align1Shl13 = 1 << 13, |
278 | _Align1Shl14 = 1 << 14, |
279 | _Align1Shl15 = 1 << 15, |
280 | _Align1Shl16 = 1 << 16, |
281 | _Align1Shl17 = 1 << 17, |
282 | _Align1Shl18 = 1 << 18, |
283 | _Align1Shl19 = 1 << 19, |
284 | _Align1Shl20 = 1 << 20, |
285 | _Align1Shl21 = 1 << 21, |
286 | _Align1Shl22 = 1 << 22, |
287 | _Align1Shl23 = 1 << 23, |
288 | _Align1Shl24 = 1 << 24, |
289 | _Align1Shl25 = 1 << 25, |
290 | _Align1Shl26 = 1 << 26, |
291 | _Align1Shl27 = 1 << 27, |
292 | _Align1Shl28 = 1 << 28, |
293 | _Align1Shl29 = 1 << 29, |
294 | _Align1Shl30 = 1 << 30, |
295 | _Align1Shl31 = 1 << 31, |
296 | } |
297 | |
298 | #[cfg (target_pointer_width = "64" )] |
299 | #[derive (Copy, Clone, PartialEq, Eq)] |
300 | #[repr (u64)] |
301 | enum AlignmentEnum { |
302 | _Align1Shl0 = 1 << 0, |
303 | _Align1Shl1 = 1 << 1, |
304 | _Align1Shl2 = 1 << 2, |
305 | _Align1Shl3 = 1 << 3, |
306 | _Align1Shl4 = 1 << 4, |
307 | _Align1Shl5 = 1 << 5, |
308 | _Align1Shl6 = 1 << 6, |
309 | _Align1Shl7 = 1 << 7, |
310 | _Align1Shl8 = 1 << 8, |
311 | _Align1Shl9 = 1 << 9, |
312 | _Align1Shl10 = 1 << 10, |
313 | _Align1Shl11 = 1 << 11, |
314 | _Align1Shl12 = 1 << 12, |
315 | _Align1Shl13 = 1 << 13, |
316 | _Align1Shl14 = 1 << 14, |
317 | _Align1Shl15 = 1 << 15, |
318 | _Align1Shl16 = 1 << 16, |
319 | _Align1Shl17 = 1 << 17, |
320 | _Align1Shl18 = 1 << 18, |
321 | _Align1Shl19 = 1 << 19, |
322 | _Align1Shl20 = 1 << 20, |
323 | _Align1Shl21 = 1 << 21, |
324 | _Align1Shl22 = 1 << 22, |
325 | _Align1Shl23 = 1 << 23, |
326 | _Align1Shl24 = 1 << 24, |
327 | _Align1Shl25 = 1 << 25, |
328 | _Align1Shl26 = 1 << 26, |
329 | _Align1Shl27 = 1 << 27, |
330 | _Align1Shl28 = 1 << 28, |
331 | _Align1Shl29 = 1 << 29, |
332 | _Align1Shl30 = 1 << 30, |
333 | _Align1Shl31 = 1 << 31, |
334 | _Align1Shl32 = 1 << 32, |
335 | _Align1Shl33 = 1 << 33, |
336 | _Align1Shl34 = 1 << 34, |
337 | _Align1Shl35 = 1 << 35, |
338 | _Align1Shl36 = 1 << 36, |
339 | _Align1Shl37 = 1 << 37, |
340 | _Align1Shl38 = 1 << 38, |
341 | _Align1Shl39 = 1 << 39, |
342 | _Align1Shl40 = 1 << 40, |
343 | _Align1Shl41 = 1 << 41, |
344 | _Align1Shl42 = 1 << 42, |
345 | _Align1Shl43 = 1 << 43, |
346 | _Align1Shl44 = 1 << 44, |
347 | _Align1Shl45 = 1 << 45, |
348 | _Align1Shl46 = 1 << 46, |
349 | _Align1Shl47 = 1 << 47, |
350 | _Align1Shl48 = 1 << 48, |
351 | _Align1Shl49 = 1 << 49, |
352 | _Align1Shl50 = 1 << 50, |
353 | _Align1Shl51 = 1 << 51, |
354 | _Align1Shl52 = 1 << 52, |
355 | _Align1Shl53 = 1 << 53, |
356 | _Align1Shl54 = 1 << 54, |
357 | _Align1Shl55 = 1 << 55, |
358 | _Align1Shl56 = 1 << 56, |
359 | _Align1Shl57 = 1 << 57, |
360 | _Align1Shl58 = 1 << 58, |
361 | _Align1Shl59 = 1 << 59, |
362 | _Align1Shl60 = 1 << 60, |
363 | _Align1Shl61 = 1 << 61, |
364 | _Align1Shl62 = 1 << 62, |
365 | _Align1Shl63 = 1 << 63, |
366 | } |
367 | |