From 871397342c9da1cdcee3c851a2c93b84aa512fba Mon Sep 17 00:00:00 2001 From: xizheyin Date: Wed, 4 Jun 2025 01:39:02 +0800 Subject: [PATCH] std: simplify `NonNull` variance documentation Streamlined the explanation of covariance for `NonNull`, focusing on practical usage and reducing scary explanation. Added a concise example for cases where invariance is required, showing how to use `PhantomData> Signed-off-by: xizheyin --- library/core/src/ptr/non_null.rs | 27 ++++++++++++++++----------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/library/core/src/ptr/non_null.rs b/library/core/src/ptr/non_null.rs index 91b8d1bf9a707..f9089ae5239b0 100644 --- a/library/core/src/ptr/non_null.rs +++ b/library/core/src/ptr/non_null.rs @@ -20,19 +20,24 @@ use crate::{fmt, hash, intrinsics, mem, ptr}; /// as a discriminant -- `Option>` has the same size as `*mut T`. /// However the pointer may still dangle if it isn't dereferenced. /// -/// Unlike `*mut T`, `NonNull` was chosen to be covariant over `T`. This makes it -/// possible to use `NonNull` when building covariant types, but introduces the -/// risk of unsoundness if used in a type that shouldn't actually be covariant. -/// (The opposite choice was made for `*mut T` even though technically the unsoundness -/// could only be caused by calling unsafe functions.) +/// Unlike `*mut T`, `NonNull` is covariant over `T`. This is usually the correct +/// choice for most data structures and safe abstractions, such as `Box`, `Rc`, `Arc`, `Vec`, +/// and `LinkedList`. /// -/// Covariance is correct for most safe abstractions, such as `Box`, `Rc`, `Arc`, `Vec`, -/// and `LinkedList`. This is the case because they provide a public API that follows the -/// normal shared XOR mutable rules of Rust. +/// In rare cases, if your type exposes a way to mutate the value of `T` through a `NonNull`, +/// and you need to prevent unsoundness from variance (for example, if `T` could be a reference +/// with a shorter lifetime), you should add a field to make your type invariant, such as +/// `PhantomData>` or `PhantomData<&'a mut T>`. /// -/// If your type cannot safely be covariant, you must ensure it contains some -/// additional field to provide invariance. Often this field will be a [`PhantomData`] -/// type like `PhantomData>` or `PhantomData<&'a mut T>`. +/// Example of a type that must be invariant: +/// ```rust +/// use std::cell::Cell; +/// use std::marker::PhantomData; +/// struct Invariant { +/// ptr: std::ptr::NonNull, +/// _invariant: PhantomData>, +/// } +/// ``` /// /// Notice that `NonNull` has a `From` instance for `&T`. However, this does /// not change the fact that mutating through a (pointer derived from a) shared