Skip to content

Commit

Permalink
create a new section on pointer to reference conversion
Browse files Browse the repository at this point in the history
also start deduplicating the docs that are getting moved to this
section.
  • Loading branch information
lolbinarycat committed Jul 28, 2024
1 parent 0bb6fec commit 5555e98
Show file tree
Hide file tree
Showing 2 changed files with 28 additions and 36 deletions.
24 changes: 24 additions & 0 deletions library/core/src/ptr/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,30 @@
//! has size 0, i.e., even if memory is not actually touched. Consider using
//! [`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:
//! * The pointer must be properly aligned.
//!
//! * It must be "dereferenceable" in the sense defined above
//!
//! * 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.
//!
//! If a pointer follows all of these rules, it is said to be
//! *convertable to a reference*.
//!
//! These 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.
//!
//! ## Allocated object
//!
//! An *allocated object* is a subset of program memory which is addressable
Expand Down
40 changes: 4 additions & 36 deletions library/core/src/ptr/mut_ptr.rs
Original file line number Diff line number Diff line change
Expand Up @@ -247,24 +247,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].
///
/// * 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 @@ -609,25 +592,10 @@ 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].
///
/// * 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.
/// 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)
///
/// 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
///
/// # Examples
///
Expand Down

0 comments on commit 5555e98

Please sign in to comment.