From a739420039b8b5fe0212209540f91677932eeefd Mon Sep 17 00:00:00 2001 From: Alan Wu Date: Fri, 22 Apr 2022 18:58:45 -0400 Subject: [PATCH] Attempt to explain that &mut cannot alias This is a clumsy attempt at making the "`&mut` is an exclusive reference" part of the aliasing rule more discoverable. I feel like this is an inherent property of the type so I was surprised to not find that information here. This is echoing parts of the docs for [UnsafeCell] and [ptr::as_mut], so another place where a newcomer could potentially get this info. I think it's easy for learners to assume that `&mut` can alias since many popular languages have comparatively lax aliasing rules. [UnsafeCell]: https://doc.rust-lang.org/stable/std/cell/struct.UnsafeCell.html [ptr::as_mut]: https://doc.rust-lang.org/std/primitive.pointer.html#method.as_mut-1 --- src/types/pointer.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/types/pointer.md b/src/types/pointer.md index 47bda4f82..6790b432e 100644 --- a/src/types/pointer.md +++ b/src/types/pointer.md @@ -26,6 +26,11 @@ These also point to memory owned by some other value. A mutable reference type is written `&mut type` or `&'a mut type`. A mutable reference (that hasn't been borrowed) is the only way to access the value it points to, so is not `Copy`. +While a mutable reference is alive, it is the only reference pointing to the referent; no other reference, +mutable or shared, point to the same value. For the safe subset of the language, this constraint is +verified by the compiler. For code that use `unsafe`, it's up to the programmer to follow this constraint to avoid +[undefined behavior] for correctness. + ## Raw pointers (`*const` and `*mut`) > **Syntax**\ @@ -58,3 +63,4 @@ The standard library contains additional 'smart pointer' types beyond references [`unsafe` operation]: ../unsafety.md [dynamically sized types]: ../dynamically-sized-types.md [temporary value]: ../expressions.md#temporaries +[undefined behavior]: ../behavior-considered-undefined.md