languages/rust
languages/rust
1
0
Fork 0
mirror of https://github.com/rust-lang/rust synced 2024-10-01 22:34:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

create a new section on pointer to reference conversion

Browse source 
also start deduplicating the docs that are getting moved to this
section.
This commit is contained in:
binarycat 2024-07-24 15:14:41 -04:00
parent 54be9ad5eb
commit 7643ea5b9c
2 changed files with 28 additions and 36 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

24
library/core/src/ptr/mod.rs
View file

@ -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

40
library/core/src/ptr/mut_ptr.rs
View file

@ -247,24 +247,7 @@ pub const fn to_raw_parts(self) -> (*mut (), <T as super::Pointee>::Metadata) {
/// # 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
///
@ -609,25 +592,10 @@ pub fn mask(self, mask: usize) -> *mut T {
///
/// # Safety
///
/// When calling this method, you have to ensure that *either* the pointer is null *or*
/// all of the following is true:
/// 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 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.)
///
/// [the module documentation]: crate::ptr#safety
///
/// # Examples
///