From 389333a21c6a0ed51952c6d5d0b339e7d274ef2e Mon Sep 17 00:00:00 2001
From: Julian Frimmel <julian.frimmel@gmail.com>
Date: Sat, 27 Mar 2021 11:44:39 +0100
Subject: [PATCH] Update `ptr` docs with regards to `ptr::addr_of!`
This updates the documentation since `ptr::addr_of!` and
`ptr::addr_of_mut!` are now stable. One might remove the distinction
between the sections `# On packed structs` and `# Examples`, as the old
section on packed structs was primarily to prevent users of doing unde-
fined behavior, which is not necessary anymore.
There is also a new section in "how to obtain a pointer", which referen-
ces the `ptr::addr_of!` macros.
This commit contains squashed commits from code review.
Co-authored-by: Joshua Nelson <joshua@yottadb.com>
Co-authored-by: Mara Bos <m-ou.se@m-ou.se>
Co-authored-by: Soveu <marx.tomasz@gmail.com>
Co-authored-by: Ralf Jung <post@ralfj.de>
---
library/core/src/ptr/mod.rs | 61 ++++++++++++-------------------
library/std/src/primitive_docs.rs | 22 ++++++++++-
2 files changed, 44 insertions(+), 39 deletions(-)
diff --git a/library/core/src/ptr/mod.rs b/library/core/src/ptr/mod.rs
index 2392f0174b6f0..66d3626fe5d74 100644
--- a/library/core/src/ptr/mod.rs
+++ b/library/core/src/ptr/mod.rs
@@ -742,9 +742,6 @@ pub const unsafe fn read<T>(src: *const T) -> T {
///
/// ## On `packed` structs
///
-/// It is currently impossible to create raw pointers to unaligned fields
-/// of a packed struct.
-///
/// Attempting to create a raw pointer to an `unaligned` struct field with
/// an expression such as `&packed.unaligned as *const FieldType` creates an
/// intermediate unaligned reference before converting that to a raw pointer.
@@ -753,9 +750,13 @@ pub const unsafe fn read<T>(src: *const T) -> T {
/// As a result, using `&packed.unaligned as *const FieldType` causes immediate
/// *undefined behavior* in your program.
///
+/// Instead you must use the [`ptr::addr_of!`](addr_of) macro to
+/// create the pointer. You may use that returned pointer together with this
+/// function.
+///
/// An example of what not to do and how this relates to `read_unaligned` is:
///
-/// ```no_run
+/// ```
/// #[repr(packed, C)]
/// struct Packed {
/// _padding: u8,
@@ -767,24 +768,15 @@ pub const unsafe fn read<T>(src: *const T) -> T {
/// unaligned: 0x01020304,
/// };
///
-/// #[allow(unaligned_references)]
-/// let v = unsafe {
-/// // Here we attempt to take the address of a 32-bit integer which is not aligned.
-/// let unaligned =
-/// // A temporary unaligned reference is created here which results in
-/// // undefined behavior regardless of whether the reference is used or not.
-/// &packed.unaligned
-/// // Casting to a raw pointer doesn't help; the mistake already happened.
-/// as *const u32;
+/// // Take the address of a 32-bit integer which is not aligned.
+/// // In contrast to `&packed.unaligned as *const _`, this has no undefined behavior.
+/// let unaligned = std::ptr::addr_of!(packed.unaligned);
///
-/// let v = std::ptr::read_unaligned(unaligned);
-///
-/// v
-/// };
+/// let v = unsafe { std::ptr::read_unaligned(unaligned) };
+/// assert_eq!(v, 0x01020304);
/// ```
///
/// Accessing unaligned fields directly with e.g. `packed.unaligned` is safe however.
-// FIXME: Update docs based on outcome of RFC #2582 and friends.
///
/// # Examples
///
@@ -938,9 +930,6 @@ pub const unsafe fn write<T>(dst: *mut T, src: T) {
///
/// ## On `packed` structs
///
-/// It is currently impossible to create raw pointers to unaligned fields
-/// of a packed struct.
-///
/// Attempting to create a raw pointer to an `unaligned` struct field with
/// an expression such as `&packed.unaligned as *const FieldType` creates an
/// intermediate unaligned reference before converting that to a raw pointer.
@@ -949,36 +938,32 @@ pub const unsafe fn write<T>(dst: *mut T, src: T) {
/// As a result, using `&packed.unaligned as *const FieldType` causes immediate
/// *undefined behavior* in your program.
///
-/// An example of what not to do and how this relates to `write_unaligned` is:
+/// Instead you must use the [`ptr::addr_of_mut!`](addr_of_mut)
+/// macro to create the pointer. You may use that returned pointer together with
+/// this function.
+///
+/// An example of how to do it and how this relates to `write_unaligned` is:
///
-/// ```no_run
+/// ```
/// #[repr(packed, C)]
/// struct Packed {
/// _padding: u8,
/// unaligned: u32,
/// }
///
-/// let v = 0x01020304;
/// let mut packed: Packed = unsafe { std::mem::zeroed() };
///
-/// #[allow(unaligned_references)]
-/// let v = unsafe {
-/// // Here we attempt to take the address of a 32-bit integer which is not aligned.
-/// let unaligned =
-/// // A temporary unaligned reference is created here which results in
-/// // undefined behavior regardless of whether the reference is used or not.
-/// &mut packed.unaligned
-/// // Casting to a raw pointer doesn't help; the mistake already happened.
-/// as *mut u32;
+/// // Take the address of a 32-bit integer which is not aligned.
+/// // In contrast to `&packed.unaligned as *mut _`, this has no undefined behavior.
+/// let unaligned = std::ptr::addr_of_mut!(packed.unaligned);
///
-/// std::ptr::write_unaligned(unaligned, v);
+/// unsafe { std::ptr::write_unaligned(unaligned, 42) };
///
-/// v
-/// };
+/// assert_eq!({packed.unaligned}, 42); // `{...}` forces copying the field instead of creating a reference.
/// ```
///
-/// Accessing unaligned fields directly with e.g. `packed.unaligned` is safe however.
-// FIXME: Update docs based on outcome of RFC #2582 and friends.
+/// Accessing unaligned fields directly with e.g. `packed.unaligned` is safe however
+/// (as can be seen in the `assert_eq!` above).
///
/// # Examples
///
diff --git a/library/std/src/primitive_docs.rs b/library/std/src/primitive_docs.rs
index 64b22b64f4bf1..a37c92e92fe42 100644
--- a/library/std/src/primitive_docs.rs
+++ b/library/std/src/primitive_docs.rs
@@ -445,7 +445,27 @@ mod prim_unit {}
/// Note that here the call to [`drop`] is for clarity - it indicates
/// that we are done with the given value and it should be destroyed.
///
-/// ## 3. Get it from C.
+/// ## 3. Create it using `ptr::addr_of!`
+///
+/// Instead of coercing a reference to a raw pointer, you can use the macros
+/// [`ptr::addr_of!`] (for `*const T`) and [`ptr::addr_of_mut!`] (for `*mut T`).
+/// These macros allow you to create raw pointers to fields to which you cannot
+/// create a reference (without causing undefined behaviour), such as an
+/// unaligned field. This might be necessary if packed structs or uninitialized
+/// memory is involved.
+///
+/// ```
+/// #[derive(Debug, Default, Copy, Clone)]
+/// #[repr(C, packed)]
+/// struct S {
+/// aligned: u8,
+/// unaligned: u32,
+/// }
+/// let s = S::default();
+/// let p = std::ptr::addr_of!(s.unaligned); // not allowed with coercion
+/// ```
+///
+/// ## 4. Get it from C.
///
/// ```
/// # #![feature(rustc_private)]