clarify that realloc refreshes pointer provenance even when the alloc…

…ation remains in-place

library/core/src/alloc/global.rs

@@ -208,9 +208,11 @@ pub unsafe trait GlobalAlloc {
     ///
     /// If this returns a non-null pointer, then ownership of the memory block
     /// referenced by `ptr` has been transferred to this allocator.
-    /// The memory may or may not have been deallocated, and should be
-    /// considered unusable. The new memory block is allocated with `layout`,
-    /// but with the `size` updated to `new_size`. This new layout should be
+    /// Any access to the old `ptr` is Undefined Behavior, even if the
+    /// allocation remained in-place. The newly returned pointer is the only valid pointer
+    /// for accessing this memory now.
+    /// The new memory block is allocated with `layout`,
+    /// but with the `size` updated to `new_size`. This new layout must be
     /// used when deallocating the new memory block with `dealloc`. The range
     /// `0..min(layout.size(), new_size)` of the new memory block is
     /// guaranteed to have the same values as the original block.

library/core/src/alloc/mod.rs

@@ -169,8 +169,9 @@ pub unsafe trait Allocator {
     /// this, the allocator may extend the allocation referenced by `ptr` to fit the new layout.
     ///
     /// If this returns `Ok`, then ownership of the memory block referenced by `ptr` has been
-    /// transferred to this allocator. The memory may or may not have been freed, and should be
-    /// considered unusable.
+    /// transferred to this allocator. Any access to the old `ptr` is Undefined Behavior, even if the
+    /// allocation was grown in-place. The newly returned pointer is the only valid pointer
+    /// for accessing this memory now.
     ///
     /// If this method returns `Err`, then ownership of the memory block has not been transferred to
     /// this allocator, and the contents of the memory block are unaltered.
@@ -295,8 +296,9 @@ pub unsafe trait Allocator {
     /// this, the allocator may shrink the allocation referenced by `ptr` to fit the new layout.
     ///
     /// If this returns `Ok`, then ownership of the memory block referenced by `ptr` has been
-    /// transferred to this allocator. The memory may or may not have been freed, and should be
-    /// considered unusable.
+    /// transferred to this allocator. Any access to the old `ptr` is Undefined Behavior, even if the
+    /// allocation was shrunk in-place. The newly returned pointer is the only valid pointer
+    /// for accessing this memory now.
     ///
     /// If this method returns `Err`, then ownership of the memory block has not been transferred to
     /// this allocator, and the contents of the memory block are unaltered.