Skip to content

Commit

Permalink
align_offset, align_to: no longer allow implementations to spuriously…
Browse files Browse the repository at this point in the history
… fail to align
  • Loading branch information
RalfJung committed Mar 8, 2024
1 parent d2e8ecd commit 507583a
Show file tree
Hide file tree
Showing 3 changed files with 24 additions and 16 deletions.
13 changes: 10 additions & 3 deletions library/core/src/ptr/const_ptr.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1322,9 +1322,7 @@ impl<T: ?Sized> *const T {
/// `align`.
///
/// If it is not possible to align the pointer, the implementation returns
/// `usize::MAX`. It is permissible for the implementation to *always*
/// return `usize::MAX`. Only your algorithm's performance can depend
/// on getting a usable offset here, not its correctness.
/// `usize::MAX`.
///
/// The offset is expressed in number of `T` elements, and not bytes. The value returned can be
/// used with the `wrapping_add` method.
Expand All @@ -1333,6 +1331,15 @@ impl<T: ?Sized> *const T {
/// beyond the allocation that the pointer points into. It is up to the caller to ensure that
/// the returned offset is correct in all terms other than alignment.
///
/// When this is called during compile-time evaluation (which is unstable), the implementation
/// may return `usize::MAX` in cases where that can never happen at runtime. This is because the
/// actual alignment of pointers is not known yet during compile-time, so an offset with
/// guaranteed alignment can sometimes not be computed. For example, a buffer declared as `[u8;
/// N]` might be allocated at an odd or an even address, but at compile-time this is not yet
/// known, so the execution has to be correct for either choice. It is therefore impossible to
/// find an offset that is guaranteed to be 2-aligned. (This behavior is subject to change, as usual
/// for unstable APIs.)
///
/// # Panics
///
/// The function panics if `align` is not a power-of-two.
Expand Down
13 changes: 10 additions & 3 deletions library/core/src/ptr/mut_ptr.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1585,9 +1585,7 @@ impl<T: ?Sized> *mut T {
/// `align`.
///
/// If it is not possible to align the pointer, the implementation returns
/// `usize::MAX`. It is permissible for the implementation to *always*
/// return `usize::MAX`. Only your algorithm's performance can depend
/// on getting a usable offset here, not its correctness.
/// `usize::MAX`.
///
/// The offset is expressed in number of `T` elements, and not bytes. The value returned can be
/// used with the `wrapping_add` method.
Expand All @@ -1596,6 +1594,15 @@ impl<T: ?Sized> *mut T {
/// beyond the allocation that the pointer points into. It is up to the caller to ensure that
/// the returned offset is correct in all terms other than alignment.
///
/// When this is called during compile-time evaluation (which is unstable), the implementation
/// may return `usize::MAX` in cases where that can never happen at runtime. This is because the
/// actual alignment of pointers is not known yet during compile-time, so an offset with
/// guaranteed alignment can sometimes not be computed. For example, a buffer declared as `[u8;
/// N]` might be allocated at an odd or an even address, but at compile-time this is not yet
/// known, so the execution has to be correct for either choice. It is therefore impossible to
/// find an offset that is guaranteed to be 2-aligned. (This behavior is subject to change, as usual
/// for unstable APIs.)
///
/// # Panics
///
/// The function panics if `align` is not a power-of-two.
Expand Down
14 changes: 4 additions & 10 deletions library/core/src/slice/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -3756,11 +3756,8 @@ impl<T> [T] {
/// maintained.
///
/// This method splits the slice into three distinct slices: prefix, correctly aligned middle
/// slice of a new type, and the suffix slice. How exactly the slice is split up is not
/// specified; the middle part may be smaller than necessary. However, if this fails to return a
/// maximal middle part, that is because code is running in a context where performance does not
/// matter, such as a sanitizer attempting to find alignment bugs. Regular code running
/// in a default (debug or release) execution *will* return a maximal middle part.
/// slice of a new type, and the suffix slice. The middle part will be as big as possible under
/// the given alignment constraint and element size.
///
/// This method has no purpose when either input element `T` or output element `U` are
/// zero-sized and will return the original slice without splitting anything.
Expand Down Expand Up @@ -3824,11 +3821,8 @@ impl<T> [T] {
/// types is maintained.
///
/// This method splits the slice into three distinct slices: prefix, correctly aligned middle
/// slice of a new type, and the suffix slice. How exactly the slice is split up is not
/// specified; the middle part may be smaller than necessary. However, if this fails to return a
/// maximal middle part, that is because code is running in a context where performance does not
/// matter, such as a sanitizer attempting to find alignment bugs. Regular code running
/// in a default (debug or release) execution *will* return a maximal middle part.
/// slice of a new type, and the suffix slice. The middle part will be as big as possible under
/// the given alignment constraint and element size.
///
/// This method has no purpose when either input element `T` or output element `U` are
/// zero-sized and will return the original slice without splitting anything.
Expand Down

0 comments on commit 507583a

Please sign in to comment.