refactor 'valid for read/write' definition: exclude null

Author: RalfJung

library/core/src/ptr/mod.rs

@@ -15,22 +15,19 @@
 //! The precise rules for validity are not determined yet. The guarantees that are
 //! provided at this point are very minimal:
 //!
-//! * For memory accesses of [size zero][zst], *every* pointer is valid, including the [null]
-//!   pointer. The following points are only concerned with non-zero-sized accesses.
-//! * A [null] pointer is *never* valid.
-//! * For a pointer to be valid, 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
+//! * 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. Notice that this explicitly
-//!   includes [`read_volatile`] and [`write_volatile`]: Volatile accesses cannot
-//!   be used for inter-thread synchronization, regardless of whether they are acting on
-//!   Rust memory or not.
-//! * The result of casting a reference to a pointer is valid for as long as the
+//!   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.
@@ -41,6 +38,13 @@
 //! 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`] 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,
+//! and the specific operations that permit null pointers mention that as an exception.
+//! Furthermore, [`read_volatile`] and [`write_volatile`] can be used in even more situations;
+//! see their documentation for details.
+//!
 //! 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.
@@ -450,9 +454,9 @@ mod mut_ptr;
 ///
 /// Behavior is undefined if any of the following conditions are violated:
 ///
-/// * `src` must be [valid] for reads of `count * size_of::<T>()` bytes.
+/// * `src` must be [valid] for reads of `count * size_of::<T>()` bytes or that number must be 0.
 ///
-/// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes.
+/// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes or that number must be 0.
 ///
 /// * Both `src` and `dst` must be properly aligned.
 ///
@@ -568,11 +572,11 @@ pub const unsafe fn copy_nonoverlapping<T>(src: *const T, dst: *mut T, count: us
 ///
 /// Behavior is undefined if any of the following conditions are violated:
 ///
-/// * `src` must be [valid] for reads of `count * size_of::<T>()` bytes.
+/// * `src` must be [valid] for reads of `count * size_of::<T>()` bytes or that number must be 0.
 ///
-/// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes, and must remain valid even
-///   when `src` is read for `count * size_of::<T>()` bytes. (This means if the memory ranges
-///   overlap, the `dst` pointer must not be invalidated by `src` reads.)
+/// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes or that number must be 0,
+///   and `dst` must remain valid even when `src` is read for `count * size_of::<T>()` bytes. (This
+///   means if the memory ranges overlap, the `dst` pointer must not be invalidated by `src` reads.)
 ///
 /// * Both `src` and `dst` must be properly aligned.
 ///
@@ -1565,7 +1569,7 @@ pub const unsafe fn replace<T>(dst: *mut T, src: T) -> T {
 ///
 /// Behavior is undefined if any of the following conditions are violated:
 ///
-/// * `src` must be [valid] for reads.
+/// * `src` must be [valid] for reads or `T` must be a ZST.
 ///
 /// * `src` must be properly aligned. Use [`read_unaligned`] if this is not the
 ///   case.
@@ -1817,7 +1821,7 @@ pub const unsafe fn read_unaligned<T>(src: *const T) -> T {
 ///
 /// Behavior is undefined if any of the following conditions are violated:
 ///
-/// * `dst` must be [valid] for writes.
+/// * `dst` must be [valid] for writes or `T` must be a ZST.
 ///
 /// * `dst` must be properly aligned. Use [`write_unaligned`] if this is not the
 ///   case.
@@ -2040,8 +2044,8 @@ pub const unsafe fn write_unaligned<T>(dst: *mut T, src: T) {
 ///
 /// Behavior is undefined if any of the following conditions are violated:
 ///
-/// * `src` must be either [valid] for reads, or it must point to memory outside of all Rust
-///   allocations and reading from that memory must:
+/// * `src` must be either [valid] for reads, or `T` must be a ZST, or `src` must point to memory
+///   outside of all Rust allocations and reading from that memory must:
 ///   - not trap, and
 ///   - not cause any memory inside a Rust allocation to be modified.
 ///
@@ -2128,8 +2132,8 @@ pub unsafe fn read_volatile<T>(src: *const T) -> T {
 ///
 /// Behavior is undefined if any of the following conditions are violated:
 ///
-/// * `dst` must be either [valid] for writes, or it must point to memory outside of all Rust
-///   allocations and writing to that memory must:
+/// * `dst` must be either [valid] for writes, or `T` must be a ZST, or `dst` must point to memory
+///   outside of all Rust allocations and writing to that memory must:
 ///   - not trap, and
 ///   - not cause any memory inside a Rust allocation to be modified.
 ///