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.