diff --git a/library/core/src/ptr/mod.rs b/library/core/src/ptr/mod.rs index 859fad9e069ca..d7ed4edcc0041 100644 --- a/library/core/src/ptr/mod.rs +++ b/library/core/src/ptr/mod.rs @@ -57,50 +57,42 @@ //! [`NonNull::dangling`] in such cases. //! //! ## Pointer to reference conversion -//! When converting a pointer to a reference `&T` using `&*`, +//! +//! When converting a pointer to a reference (e.g. via `&*ptr` or `&mut *ptr`), //! there are several rules that must be followed: //! //! * The pointer must be properly aligned. //! -// some microprocessors may use address 0 for an interrupt vector. -// users of these microprocessors must always read/write address 0 through -// a raw pointer, not a reference. //! * It must be non-null. //! //! * It must be "dereferenceable" in the sense defined above. //! -//! * The pointer must point to a valid value of type `T`. -//! This means that the created reference can only refer to -//! uninitialized memory through careful use of `MaybeUninit`, -//! or if the uninitialized memory is entirely contained within -//! padding bytes, since -//! [padding has the same validity invariant as `MaybeUninit`][ucg-pad]. -//! -//! * You must enforce Rust's aliasing rules, since the lifetime of the -//! created reference is arbitrarily chosen, -//! and does not necessarily reflect the actual lifetime of the data. -//! In particular, while this reference exists, -//! the memory the pointer points to must -//! not get accessed (read or written) through any raw pointer, -//! except for data inside an `UnsafeCell`. -//! Note that aliased writes are always UB for mutable references, -//! even if they only modify `UnsafeCell` data. +//! * The pointer must point to a [valid value] of type `T`. +//! +//! * You must enforce Rust's aliasing rules. The exact aliasing rules are not decided yet, so we +//! only give a rough overview here. The rules also depend on whether a mutable or a shared +//! reference is being created. +//! * When creating a mutable reference, then while this reference exists, the memory it points to +//! must not get accessed (read or written) through any other pointer or reference not derived +//! from this reference. +//! * When creating a shared reference, then while this reference exists, the memory it points to +//! must not get mutated (except inside `UnsafeCell`). //! //! If a pointer follows all of these rules, it is said to be -//! *convertible to a reference*. +//! *convertible to a (mutable or shared) reference*. // ^ we use this term instead of saying that the produced reference must // be valid, as the validity of a reference is easily confused for the // validity of the thing it refers to, and while the two concepts are // closly related, they are not identical. //! -//! These apply even if the result is unused! +//! These rules apply even if the result is unused! //! (The part about being initialized is not yet fully decided, but until //! it is, the only safe approach is to ensure that they are indeed initialized.) //! //! An example of the implications of the above rules is that an expression such //! as `unsafe { &*(0 as *const u8) }` is Immediate Undefined Behavior. //! -//! [ucgpad]: https://rust-lang.github.io/unsafe-code-guidelines/glossary.html#padding +//! [valid value]: ../../reference/behavior-considered-undefined.html#invalid-values //! //! ## Allocated object //!