From aa112149ff06c05a83d945840bbf5bcf9b4e8076 Mon Sep 17 00:00:00 2001 From: Jules Bertholet Date: Fri, 21 Oct 2022 17:42:59 -0400 Subject: [PATCH 1/2] Clarify preconditions of raw size/align methods --- library/core/src/alloc/layout.rs | 4 +++- library/core/src/mem/mod.rs | 8 ++++++-- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/library/core/src/alloc/layout.rs b/library/core/src/alloc/layout.rs index 920e559cc4aa3..b3ffcbdc1def4 100644 --- a/library/core/src/alloc/layout.rs +++ b/library/core/src/alloc/layout.rs @@ -186,7 +186,9 @@ impl Layout { /// call, but may panic or otherwise return the wrong value, as the /// extern type's layout is not known. This is the same behavior as /// [`Layout::for_value`] on a reference to an extern type tail. - /// - otherwise, it is conservatively not allowed to call this function. + /// - otherwise, it is conservatively allowed to call this function + /// only when it would be safe to reborrow `t` as a shared reference + /// and pass it to [`Layout::for_value`]. /// /// [trait object]: ../../book/ch17-02-trait-objects.html /// [extern type]: ../../unstable-book/language-features/extern-types.html diff --git a/library/core/src/mem/mod.rs b/library/core/src/mem/mod.rs index 9195da5a44f42..ac881d82e6de6 100644 --- a/library/core/src/mem/mod.rs +++ b/library/core/src/mem/mod.rs @@ -366,7 +366,9 @@ pub const fn size_of_val(val: &T) -> usize { /// call, but may panic or otherwise return the wrong value, as the /// extern type's layout is not known. This is the same behavior as /// [`size_of_val`] on a reference to a type with an extern type tail. -/// - otherwise, it is conservatively not allowed to call this function. +/// - otherwise, it is conservatively allowed to call this function +/// only when it would be safe to reborrow `val` as a shared reference +/// and pass it to [`size_of_val`]. /// /// [trait object]: ../../book/ch17-02-trait-objects.html /// [extern type]: ../../unstable-book/language-features/extern-types.html @@ -512,7 +514,9 @@ pub const fn align_of_val(val: &T) -> usize { /// call, but may panic or otherwise return the wrong value, as the /// extern type's layout is not known. This is the same behavior as /// [`align_of_val`] on a reference to a type with an extern type tail. -/// - otherwise, it is conservatively not allowed to call this function. +/// - otherwise, it is conservatively allowed to call this function +/// only when it would be safe to reborrow `val` as a shared reference +/// and pass it to [`align_of_val`]. /// /// [trait object]: ../../book/ch17-02-trait-objects.html /// [extern type]: ../../unstable-book/language-features/extern-types.html From fcbf7c4c963d0804ee66e99e415468b306f67402 Mon Sep 17 00:00:00 2001 From: Jules Bertholet Date: Sat, 22 Oct 2022 11:50:17 -0400 Subject: [PATCH 2/2] Use @CAD97 's suggested wording --- library/core/src/alloc/layout.rs | 7 ++++--- library/core/src/mem/mod.rs | 14 ++++++++------ 2 files changed, 12 insertions(+), 9 deletions(-) diff --git a/library/core/src/alloc/layout.rs b/library/core/src/alloc/layout.rs index b3ffcbdc1def4..f1ca66f87a5a3 100644 --- a/library/core/src/alloc/layout.rs +++ b/library/core/src/alloc/layout.rs @@ -171,7 +171,9 @@ impl Layout { /// /// # Safety /// - /// This function is only safe to call if the following conditions hold: + /// This function is safe to call if the pointer is safe to reborrow as `&T` + /// (in which case you could also call [`Layout::for_value`]). Otherwise, + /// the following conditions must hold: /// /// - If `T` is `Sized`, this function is always safe to call. /// - If the unsized tail of `T` is: @@ -187,8 +189,7 @@ impl Layout { /// extern type's layout is not known. This is the same behavior as /// [`Layout::for_value`] on a reference to an extern type tail. /// - otherwise, it is conservatively allowed to call this function - /// only when it would be safe to reborrow `t` as a shared reference - /// and pass it to [`Layout::for_value`]. + /// only when it would be safe to reborrow `t` as a shared reference. /// /// [trait object]: ../../book/ch17-02-trait-objects.html /// [extern type]: ../../unstable-book/language-features/extern-types.html diff --git a/library/core/src/mem/mod.rs b/library/core/src/mem/mod.rs index ac881d82e6de6..473b578fcc839 100644 --- a/library/core/src/mem/mod.rs +++ b/library/core/src/mem/mod.rs @@ -351,7 +351,9 @@ pub const fn size_of_val(val: &T) -> usize { /// /// # Safety /// -/// This function is only safe to call if the following conditions hold: +/// This function is safe to call if the pointer is safe to reborrow as `&T` +/// (in which case you could also call [`size_of_val`]). Otherwise, the +/// following conditions must hold: /// /// - If `T` is `Sized`, this function is always safe to call. /// - If the unsized tail of `T` is: @@ -367,8 +369,7 @@ pub const fn size_of_val(val: &T) -> usize { /// extern type's layout is not known. This is the same behavior as /// [`size_of_val`] on a reference to a type with an extern type tail. /// - otherwise, it is conservatively allowed to call this function -/// only when it would be safe to reborrow `val` as a shared reference -/// and pass it to [`size_of_val`]. +/// only when it would be safe to reborrow `val` as a shared reference. /// /// [trait object]: ../../book/ch17-02-trait-objects.html /// [extern type]: ../../unstable-book/language-features/extern-types.html @@ -499,7 +500,9 @@ pub const fn align_of_val(val: &T) -> usize { /// /// # Safety /// -/// This function is only safe to call if the following conditions hold: +/// This function is safe to call if the pointer is safe to reborrow as `&T` +/// (in which case you could also call [`align_of_val`]). Otherwise, the +/// following conditions must hold: /// /// - If `T` is `Sized`, this function is always safe to call. /// - If the unsized tail of `T` is: @@ -515,8 +518,7 @@ pub const fn align_of_val(val: &T) -> usize { /// extern type's layout is not known. This is the same behavior as /// [`align_of_val`] on a reference to a type with an extern type tail. /// - otherwise, it is conservatively allowed to call this function -/// only when it would be safe to reborrow `val` as a shared reference -/// and pass it to [`align_of_val`]. +/// only when it would be safe to reborrow `val` as a shared reference. /// /// [trait object]: ../../book/ch17-02-trait-objects.html /// [extern type]: ../../unstable-book/language-features/extern-types.html