Skip to content

Commit

Permalink
remove duplicate explanations of the ptr to ref conversion rules
Browse files Browse the repository at this point in the history
  • Loading branch information
@lolbinarycat
lolbinarycat committed Jul 25, 2024
1 parent 571348b commit 394c864
Show file tree
Hide file tree
Showing 4 changed files with 50 additions and 183 deletions.
54 changes: 4 additions & 50 deletions core/src/ptr/const_ptr.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
///
Expand Down Expand Up @@ -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
///
Expand Down Expand Up @@ -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
///
Expand Down
34 changes: 26 additions & 8 deletions core/src/ptr/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
//!
//! * It must be "dereferenceable" in the sense defined above.
//!
//! * The pointer must point to an initialized instance of `T`.
//! * 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 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.
//! * 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
Expand Down
73 changes: 8 additions & 65 deletions core/src/ptr/mut_ptr.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
///
Expand Down Expand Up @@ -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
///
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
///
Expand Down Expand Up @@ -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")]
Expand Down
72 changes: 12 additions & 60 deletions core/src/ptr/non_null.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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")]
Expand All @@ -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")]
Expand Down Expand Up @@ -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
///
Expand Down Expand Up @@ -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
///
/// ```
Expand Down

0 comments on commit 394c864

Please sign in to comment.