From 65c6173bfe14b4fcf950805a552be0f98db7e050 Mon Sep 17 00:00:00 2001
From: Wiktor Przetacznik <85874198+WiktorPrzetacznik@users.noreply.github.com>
Date: Sun, 28 Jul 2024 16:08:08 +0200
Subject: [PATCH] Update NonNull::align_offset quarantees

Update NonNull::align_offset quarantees, keeping it in sync with ptr::align_offset
---
 core/src/ptr/non_null.rs | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/core/src/ptr/non_null.rs b/core/src/ptr/non_null.rs
index 796c85d0cacc7..7c87f462c5793 100644
--- a/core/src/ptr/non_null.rs
+++ b/core/src/ptr/non_null.rs
@@ -1171,9 +1171,7 @@ 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.
     ///
@@ -1181,6 +1179,15 @@ impl<T: ?Sized> NonNull<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.