align_offset, align_to: no longer allow implementations to spuriously… · model-checking/verify-rust-std@507583a (original) (raw)
3 files changed
lines changed
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1322,9 +1322,7 @@ impl<T: ?Sized> *const T { | ||
1322 | 1322 | /// `align`. |
1323 | 1323 | /// |
1324 | 1324 | /// If it is not possible to align the pointer, the implementation returns |
1325 | - /// `usize::MAX`. It is permissible for the implementation to *always* | |
1326 | - /// return `usize::MAX`. Only your algorithm's performance can depend | |
1327 | - /// on getting a usable offset here, not its correctness. | |
1325 | + /// `usize::MAX`. | |
1328 | 1326 | /// |
1329 | 1327 | /// The offset is expressed in number of `T` elements, and not bytes. The value returned can be |
1330 | 1328 | /// used with the `wrapping_add` method. |
@@ -1333,6 +1331,15 @@ impl<T: ?Sized> *const T { | ||
1333 | 1331 | /// beyond the allocation that the pointer points into. It is up to the caller to ensure that |
1334 | 1332 | /// the returned offset is correct in all terms other than alignment. |
1335 | 1333 | /// |
1334 | + /// When this is called during compile-time evaluation (which is unstable), the implementation | |
1335 | + /// may return `usize::MAX` in cases where that can never happen at runtime. This is because the | |
1336 | + /// actual alignment of pointers is not known yet during compile-time, so an offset with | |
1337 | + /// guaranteed alignment can sometimes not be computed. For example, a buffer declared as `[u8; | |
1338 | + /// N]` might be allocated at an odd or an even address, but at compile-time this is not yet | |
1339 | + /// known, so the execution has to be correct for either choice. It is therefore impossible to | |
1340 | + /// find an offset that is guaranteed to be 2-aligned. (This behavior is subject to change, as usual | |
1341 | + /// for unstable APIs.) | |
1342 | + /// | |
1336 | 1343 | /// # Panics |
1337 | 1344 | /// |
1338 | 1345 | /// The function panics if `align` is not a power-of-two. |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1585,9 +1585,7 @@ impl<T: ?Sized> *mut T { | ||
1585 | 1585 | /// `align`. |
1586 | 1586 | /// |
1587 | 1587 | /// If it is not possible to align the pointer, the implementation returns |
1588 | - /// `usize::MAX`. It is permissible for the implementation to *always* | |
1589 | - /// return `usize::MAX`. Only your algorithm's performance can depend | |
1590 | - /// on getting a usable offset here, not its correctness. | |
1588 | + /// `usize::MAX`. | |
1591 | 1589 | /// |
1592 | 1590 | /// The offset is expressed in number of `T` elements, and not bytes. The value returned can be |
1593 | 1591 | /// used with the `wrapping_add` method. |
@@ -1596,6 +1594,15 @@ impl<T: ?Sized> *mut T { | ||
1596 | 1594 | /// beyond the allocation that the pointer points into. It is up to the caller to ensure that |
1597 | 1595 | /// the returned offset is correct in all terms other than alignment. |
1598 | 1596 | /// |
1597 | + /// When this is called during compile-time evaluation (which is unstable), the implementation | |
1598 | + /// may return `usize::MAX` in cases where that can never happen at runtime. This is because the | |
1599 | + /// actual alignment of pointers is not known yet during compile-time, so an offset with | |
1600 | + /// guaranteed alignment can sometimes not be computed. For example, a buffer declared as `[u8; | |
1601 | + /// N]` might be allocated at an odd or an even address, but at compile-time this is not yet | |
1602 | + /// known, so the execution has to be correct for either choice. It is therefore impossible to | |
1603 | + /// find an offset that is guaranteed to be 2-aligned. (This behavior is subject to change, as usual | |
1604 | + /// for unstable APIs.) | |
1605 | + /// | |
1599 | 1606 | /// # Panics |
1600 | 1607 | /// |
1601 | 1608 | /// The function panics if `align` is not a power-of-two. |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -3756,11 +3756,8 @@ impl [T] { | ||
3756 | 3756 | /// maintained. |
3757 | 3757 | /// |
3758 | 3758 | /// This method splits the slice into three distinct slices: prefix, correctly aligned middle |
3759 | - /// slice of a new type, and the suffix slice. How exactly the slice is split up is not | |
3760 | - /// specified; the middle part may be smaller than necessary. However, if this fails to return a | |
3761 | - /// maximal middle part, that is because code is running in a context where performance does not | |
3762 | - /// matter, such as a sanitizer attempting to find alignment bugs. Regular code running | |
3763 | - /// in a default (debug or release) execution *will* return a maximal middle part. | |
3759 | + /// slice of a new type, and the suffix slice. The middle part will be as big as possible under | |
3760 | + /// the given alignment constraint and element size. | |
3764 | 3761 | /// |
3765 | 3762 | /// This method has no purpose when either input element `T` or output element `U` are |
3766 | 3763 | /// zero-sized and will return the original slice without splitting anything. |
@@ -3824,11 +3821,8 @@ impl [T] { | ||
3824 | 3821 | /// types is maintained. |
3825 | 3822 | /// |
3826 | 3823 | /// This method splits the slice into three distinct slices: prefix, correctly aligned middle |
3827 | - /// slice of a new type, and the suffix slice. How exactly the slice is split up is not | |
3828 | - /// specified; the middle part may be smaller than necessary. However, if this fails to return a | |
3829 | - /// maximal middle part, that is because code is running in a context where performance does not | |
3830 | - /// matter, such as a sanitizer attempting to find alignment bugs. Regular code running | |
3831 | - /// in a default (debug or release) execution *will* return a maximal middle part. | |
3824 | + /// slice of a new type, and the suffix slice. The middle part will be as big as possible under | |
3825 | + /// the given alignment constraint and element size. | |
3832 | 3826 | /// |
3833 | 3827 | /// This method has no purpose when either input element `T` or output element `U` are |
3834 | 3828 | /// zero-sized and will return the original slice without splitting anything. |