rust-lang/rust
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

remove duplicate explanations of the ptr to ref conversion rules

Browse Source
This commit is contained in:
binarycat
2024-07-24 16:36:33 -04:00
parent 7643ea5b9c
commit 1073f97ed8
4 changed files with 50 additions and 183 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
library/core/src/ptr/mod.rs
View File

@@ -57,21 +57,39 @@
//! [`NonNull::dangling`] in such cases.
//!
//! ## Pointer to reference conversion
//! When converting a pointer to a reference using `&*`, there are several
//! rules that must be followed:
//! When converting a pointer to a reference `&T` using `&*`,
//! there are several rules that must be followed:
//!
//! * The pointer must be properly aligned.
//!
//! * It must be "dereferenceable" in the sense defined above
// 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.
//!
//! * The pointer must point to an initialized instance of `T`.
//! * It must be "dereferenceable" in the sense defined above.
//!
//! * You must enforce Rust's aliasing rules, since the returned lifetime `'a` 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 other pointer.
//! * The pointer must point to a valid instance of `T`.
//! This means that the created reference can only refer to
//! uninitialized memory through careful use of `MaybeUninit`.
//!
//! * 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`
// ^ previous documentation was somewhat unclear on if modifications through
// an UnsafeCell are safe even if they would seemingly violate the exclusivity
// of a mut ref.
//!
//! If a pointer follows all of these rules, it is said to be
//! *convertable to a 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!
//! (The part about being initialized is not yet fully decided, but until