From aed88e18049f6be7d3c3b37683d05d777adb3c86 Mon Sep 17 00:00:00 2001
From: CAD97 <cad97@cad97.com>
Date: Tue, 30 Jun 2020 12:47:23 -0400
Subject: [PATCH] Clarify when rc::data_offset is safe

---
 src/liballoc/rc.rs   | 10 ++++++++++
 src/liballoc/sync.rs | 11 ++++++++++-
 2 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/src/liballoc/rc.rs b/src/liballoc/rc.rs
index ab64d5330874f..24e7d5da7a684 100644
--- a/src/liballoc/rc.rs
+++ b/src/liballoc/rc.rs
@@ -2116,6 +2116,16 @@ impl<T: ?Sized> AsRef<T> for Rc<T> {
 #[stable(feature = "pin", since = "1.33.0")]
 impl<T: ?Sized> Unpin for Rc<T> {}
 
+/// Get the offset within an `ArcInner` for
+/// a payload of type described by a pointer.
+///
+/// # Safety
+///
+/// This has the same safety requirements as `align_of_val_raw`. In effect:
+///
+/// - This function is safe for any argument if `T` is sized, and
+/// - if `T` is unsized, the pointer must have appropriate pointer metadata
+///   aquired from the real instance that you are getting this offset for.
 unsafe fn data_offset<T: ?Sized>(ptr: *const T) -> isize {
     // Align the unsized value to the end of the `RcBox`.
     // Because it is ?Sized, it will always be the last field in memory.
diff --git a/src/liballoc/sync.rs b/src/liballoc/sync.rs
index e9af80d326f44..53ce47d023b47 100644
--- a/src/liballoc/sync.rs
+++ b/src/liballoc/sync.rs
@@ -2273,7 +2273,16 @@ impl<T: ?Sized> AsRef<T> for Arc<T> {
 #[stable(feature = "pin", since = "1.33.0")]
 impl<T: ?Sized> Unpin for Arc<T> {}
 
-/// Computes the offset of the data field within `ArcInner`.
+/// Get the offset within an `ArcInner` for
+/// a payload of type described by a pointer.
+///
+/// # Safety
+///
+/// This has the same safety requirements as `align_of_val_raw`. In effect:
+///
+/// - This function is safe for any argument if `T` is sized, and
+/// - if `T` is unsized, the pointer must have appropriate pointer metadata
+///   aquired from the real instance that you are getting this offset for.
 unsafe fn data_offset<T: ?Sized>(ptr: *const T) -> isize {
     // Align the unsized value to the end of the `ArcInner`.
     // Because it is `?Sized`, it will always be the last field in memory.