Rollup merge of rust-lang#128306 - WiktorPrzetacznik:WiktorPrzetaczni…

…k-nonnull-alignoffset-update, r=Amanieu

Update NonNull::align_offset quarantees

This PR proposes to update [`NonNull::align_offset`](https://doc.rust-lang.org/stable/std/ptr/struct.NonNull.html#method.align_offset) guarantees, which should to be matched with [`ptr::align_offset`](https://doc.rust-lang.org/stable/std/primitive.pointer.html#method.align_offset-1)
(as `NonNull::align_offset` delegates to `ptr::align_offset`).

[PR rust-lang#121201](rust-lang#121201) updated only `ptr::align_offset` docs.

library/core/src/ptr/non_null.rs

@@ -1169,16 +1169,23 @@ impl<T: ?Sized> NonNull<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.
  ///
  /// There are no guarantees whatsoever that offsetting the pointer will not overflow or go
  /// 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.