Skip to content

Commit

Permalink
Rollup merge of rust-lang#129652 - RalfJung:ptr-to-ref, r=traviscross
Browse files Browse the repository at this point in the history
fix Pointer to reference conversion docs

The aliasing rules documented in rust-lang#128157 are wrong, this fixes them.
  • Loading branch information
matthiaskrgr authored Aug 27, 2024
2 parents 92a4bb7 + ab4a743 commit 8d6aafa
Showing 1 changed file with 15 additions and 23 deletions.
38 changes: 15 additions & 23 deletions library/core/src/ptr/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
//!
Expand Down

0 comments on commit 8d6aafa

Please sign in to comment.