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

54
library/core/src/ptr/const_ptr.rs
View File

@@ -239,24 +239,7 @@ impl<T: ?Sized> *const T {
/// # Safety
///
/// When calling this method, you have to ensure that *either* the pointer is null *or*
/// all of the following is true:
///
/// * The pointer must be properly aligned.
///
/// * It must be "dereferenceable" in the sense defined in [the module documentation].
///
/// * The pointer must point to an initialized instance of `T`.
///
/// * 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 mutated (except inside `UnsafeCell`).
///
/// This applies even if the result of this method 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.)
///
/// [the module documentation]: crate::ptr#safety
/// the pointer is [convirtible to a reference](crate::ptr#pointer-to-reference-conversion)
///
/// # Examples
///
@@ -302,24 +285,8 @@ impl<T: ?Sized> *const T {
///
/// # Safety
///
/// When calling this method, you have to ensure that all of the following is true:
///
/// * The pointer must be properly aligned.
///
/// * It must be "dereferenceable" in the sense defined in [the module documentation].
///
/// * The pointer must point to an initialized instance of `T`.
///
/// * 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 mutated (except inside `UnsafeCell`).
///
/// This applies even if the result of this method 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.)
///
/// [the module documentation]: crate::ptr#safety
/// When calling this method, you have to ensure that
/// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion)
///
/// # Examples
///
@@ -350,20 +317,7 @@ impl<T: ?Sized> *const T {
/// # Safety
///
/// When calling this method, you have to ensure that *either* the pointer is null *or*
/// all of the following is true:
///
/// * The pointer must be properly aligned.
///
/// * It must be "dereferenceable" in the sense defined in [the module documentation].
///
/// * 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 mutated (except inside `UnsafeCell`).
///
/// This applies even if the result of this method is unused!
///
/// [the module documentation]: crate::ptr#safety
/// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion)
///
/// # Examples
///

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

73
library/core/src/ptr/mut_ptr.rs
View File

@@ -296,24 +296,7 @@ impl<T: ?Sized> *mut T {
///
/// # Safety
///
/// When calling this method, you have to ensure that all of the following is true:
///
/// * The pointer must be properly aligned.
///
/// * It must be "dereferenceable" in the sense defined in [the module documentation].
///
/// * The pointer must point to an initialized instance of `T`.
///
/// * 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 mutated (except inside `UnsafeCell`).
///
/// This applies even if the result of this method 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.)
///
/// [the module documentation]: crate::ptr#safety
/// When calling this method, you have to ensure that the pointer is [convirtible to a reference](crate::ptr#pointer-to-reference-conversion)
///
/// # Examples
///
@@ -347,20 +330,9 @@ impl<T: ?Sized> *mut T {
/// # Safety
///
/// When calling this method, you have to ensure that *either* the pointer is null *or*
/// all of the following is true:
///
/// * The pointer must be properly aligned.
///
/// * It must be "dereferenceable" in the sense defined in [the module documentation].
///
/// * 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 mutated (except inside `UnsafeCell`).
///
/// This applies even if the result of this method is unused!
///
/// [the module documentation]: crate::ptr#safety
/// the pointer is [convirtible to a reference](crate::ptr#pointer-to-reference-conversion).
/// Note that because the created reference is to `MaybeUninit<T>`, the
/// source pointer can point to uninitialized memory.
///
/// # Examples
///
@@ -594,7 +566,7 @@ impl<T: ?Sized> *mut T {
///
/// When calling this method, you have to ensure that *either*
/// the pointer is null *or*
/// the pointer is [convirtible to a reference](crate::ptr#pointer-to-reference-conversion)
/// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion)
///
///
/// # Examples
@@ -643,24 +615,8 @@ impl<T: ?Sized> *mut T {
///
/// # Safety
///
/// When calling this method, you have to ensure that all of the following is true:
///
/// * The pointer must be properly aligned.
///
/// * It must be "dereferenceable" in the sense defined in [the module documentation].
///
/// * The pointer must point to an initialized instance of `T`.
///
/// * 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 mutated (except inside `UnsafeCell`).
///
/// This applies even if the result of this method 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.)
///
/// [the module documentation]: crate::ptr#safety
/// When calling this method, you have to ensure that
/// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion)
///
/// # Examples
///
@@ -695,20 +651,7 @@ impl<T: ?Sized> *mut T {
/// # Safety
///
/// When calling this method, you have to ensure that *either* the pointer is null *or*
/// all of the following is true:
///
/// * The pointer must be properly aligned.
///
/// * It must be "dereferenceable" in the sense defined in [the module documentation].
///
/// * 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.
///
/// This applies even if the result of this method is unused!
///
/// [the module documentation]: crate::ptr#safety
/// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion)
#[inline]
#[unstable(feature = "ptr_as_uninit", issue = "75402")]
#[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")]

72
library/core/src/ptr/non_null.rs
View File

@@ -128,20 +128,10 @@ impl<T: Sized> NonNull<T> {
///
/// # Safety
///
/// When calling this method, you have to ensure that all of the following is true:
///
/// * The pointer must be properly aligned.
///
/// * It must be "dereferenceable" in the sense defined in [the module documentation].
///
/// * 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 mutated (except inside `UnsafeCell`).
///
/// This applies even if the result of this method is unused!
///
/// [the module documentation]: crate::ptr#safety
/// When calling this method, you have to ensure that
/// the pointer is [convirtible to a reference](crate::ptr#pointer-to-reference-conversion).
/// Note that because the created reference is to `MaybeUninit<T>`, the
/// source pointer can point to uninitialized memory.
#[inline]
#[must_use]
#[unstable(feature = "ptr_as_uninit", issue = "75402")]
@@ -162,20 +152,10 @@ impl<T: Sized> NonNull<T> {
///
/// # Safety
///
/// When calling this method, you have to ensure that all of the following is true:
///
/// * The pointer must be properly aligned.
///
/// * It must be "dereferenceable" in the sense defined in [the module documentation].
///
/// * 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.
///
/// This applies even if the result of this method is unused!
///
/// [the module documentation]: crate::ptr#safety
/// When calling this method, you have to ensure that
/// the pointer is [convirtible to a reference](crate::ptr#pointer-to-reference-conversion).
/// Note that because the created reference is to `MaybeUninit<T>`, the
/// source pointer can point to uninitialized memory.
#[inline]
#[must_use]
#[unstable(feature = "ptr_as_uninit", issue = "75402")]
@@ -361,22 +341,8 @@ impl<T: ?Sized> NonNull<T> {
///
/// # Safety
///
/// When calling this method, you have to ensure that all of the following is true:
///
/// * The pointer must be properly aligned.
///
/// * It must be "dereferenceable" in the sense defined in [the module documentation].
///
/// * The pointer must point to an initialized instance of `T`.
///
/// * 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 mutated (except inside `UnsafeCell`).
///
/// This applies even if the result of this method 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.)
/// When calling this method, you have to ensure that
/// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion)
///
/// # Examples
///
@@ -412,22 +378,8 @@ impl<T: ?Sized> NonNull<T> {
///
/// # Safety
///
/// When calling this method, you have to ensure that all of the following is true:
///
/// * The pointer must be properly aligned.
///
/// * It must be "dereferenceable" in the sense defined in [the module documentation].
///
/// * The pointer must point to an initialized instance of `T`.
///
/// * 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.
///
/// This applies even if the result of this method 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.)
/// When calling this method, you have to ensure that
/// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion)
/// # Examples
///
/// ```