Repository: rust-lang/rust
File: library/core/src/ptr/mod.rs (Rust)

Code before:
//! Manually manage memory through raw pointers.
//!
//! *[See also the pointer primitive types](pointer).*
//!
//! # Safety
//!
//! Many functions in this module take raw pointers as arguments and read from or write to them. For
//! this to be safe, these pointers must be *valid* for the given access. Whether a pointer is valid
//! depends on the operation it is used for (read or write), and the extent of the memory that is
//! accessed (i.e., how many bytes are read/written) -- it makes no sense to ask "is this pointer
//! valid"; one has to ask "is this pointer valid for a given access". Most functions use `*mut T`
//! and `*const T` to access only a single value, in which case the documentation omits the size and
//! implicitly assumes it to be `size_of::<T>()` bytes.
//!
//! The precise rules for validity are not determined yet. The guarantees that are
//! provided at this point are very minimal:
//!
//! * A [null] pointer is *never* valid for reads/writes.
//! * For memory accesses of [size zero][zst], *every* non-null pointer is valid for reads/writes.
//!   The following points are only concerned with non-zero-sized accesses.
//! * For a pointer to be valid for reads/writes, it is necessary, but not always sufficient, that
//!   the pointer be *dereferenceable*. The [provenance] of the pointer is used to determine which
//!   [allocation] it is derived from; a pointer is dereferenceable if the memory range of the given
//!   size starting at the pointer is entirely contained within the bounds of that allocation. Note
//!   that in Rust, every (stack-allocated) variable is considered a separate allocation.
//! * All accesses performed by functions in this module are *non-atomic* in the sense
//!   of [atomic operations] used to synchronize between threads. This means it is
//!   undefined behavior to perform two concurrent accesses to the same location from different
//!   threads unless both accesses only read from memory.
//! * The result of casting a reference to a pointer is valid for reads/writes for as long as the
//!   underlying allocation is live and no reference (just raw pointers) is used to
//!   access the same memory. That is, reference and pointer accesses cannot be
//!   interleaved.
//!
//! These axioms, along with careful use of [`offset`] for pointer arithmetic,
//! are enough to correctly implement many useful things in unsafe code. Stronger guarantees
//! will be provided eventually, as the [aliasing] rules are being determined. For more
//! information, see the [book] as well as the section in the reference devoted
//! to [undefined behavior][ub].
//!
//! We say that a pointer is "dangling" if it is not valid for any non-zero-sized accesses. This
//! means out-of-bounds pointers, pointers to freed memory, null pointers, and pointers created with
//! [`NonNull::dangling`] are all dangling.

Review comment (suggestion):
Maybe we should keep linking to the volatile exceptions, it might not be obvious those 5 users who need it.

Code after:
//! Manually manage memory through raw pointers.
//!
//! *[See also the pointer primitive types](pointer).*
//!
//! # Safety
//!
//! Many functions in this module take raw pointers as arguments and read from or write to them. For
//! this to be safe, these pointers must be *valid* for the given access. Whether a pointer is valid
//! depends on the operation it is used for (read or write), and the extent of the memory that is
//! accessed (i.e., how many bytes are read/written) -- it makes no sense to ask "is this pointer
//! valid"; one has to ask "is this pointer valid for a given access". Most functions use `*mut T`
//! and `*const T` to access only a single value, in which case the documentation omits the size and
//! implicitly assumes it to be `size_of::<T>()` bytes.
//!
//! The precise rules for validity are not determined yet. The guarantees that are
//! provided at this point are very minimal:
//!
//! * A [null] pointer is *never* valid for reads/writes.
//! * For memory accesses of [size zero][zst], *every* non-null pointer is valid for reads/writes.
//!   The following points are only concerned with non-zero-sized accesses.
//! * For a pointer to be valid for reads/writes, it is necessary, but not always sufficient, that
//!   the pointer be *dereferenceable*. The [provenance] of the pointer is used to determine which
//!   [allocation] it is derived from; a pointer is dereferenceable if the memory range of the given
//!   size starting at the pointer is entirely contained within the bounds of that allocation. Note
//!   that in Rust, every (stack-allocated) variable is considered a separate allocation.
//! * All accesses performed by functions in this module are *non-atomic* in the sense
//!   of [atomic operations] used to synchronize between threads. This means it is
//!   undefined behavior to perform two concurrent accesses to the same location from different
//!   threads unless both accesses only read from memory.
//! * The result of casting a reference to a pointer is valid for reads/writes for as long as the
//!   underlying allocation is live and no reference (just raw pointers) is used to
//!   access the same memory. That is, reference and pointer accesses cannot be
//!   interleaved.
//!
//! These axioms, along with careful use of [`offset`] for pointer arithmetic,
//! are enough to correctly implement many useful things in unsafe code. Stronger guarantees
//! will be provided eventually, as the [aliasing] rules are being determined. For more
//! information, see the [book] as well as the section in the reference devoted
//! to [undefined behavior][ub].
//!
//! Note that some operations such as [`read`] and [`write`][`write()`] do allow null pointers if
//! the total size of the access is zero. However, other operations internally convert pointers into
//! references. Therefore, the general notion of "valid for reads/writes" excludes null pointers,