@@ -1165,11 +1165,15 @@ impl<'a, T: ?Sized + fmt::Display> fmt::Display for RefMut<'a, T> {
11651165/// mutated, and that `&mut T` is unique. When building abstractions like `Cell`, `RefCell`,
11661166/// `Mutex`, etc, you need to turn these optimizations off. `UnsafeCell` is the only legal way
11671167/// to do this. When `UnsafeCell<T>` itself is immutably aliased, it is still safe to obtain
1168- /// a mutable reference to its interior and/or to mutate the interior. However, it is up to
1169- /// the abstraction designer to ensure that no two mutable references obtained this way are active
1170- /// at the same time, there are no active immutable reference when a mutable reference is obtained
1171- /// from the cell, and that there are no active mutable references or mutations when an immutable
1172- /// reference is obtained. This is often done via runtime checks.
1168+ /// a mutable reference to its interior and/or to mutate the interior. However, the abstraction
1169+ /// designer must ensure that any active mutable references to the interior obtained this way does
1170+ /// not co-exist with other active references to the interior, either mutable or not. This is often
1171+ /// done via runtime checks. Naturally, several active immutable references to the interior can
1172+ /// co-exits with each other (but not with a mutable reference).
1173+ ///
1174+ /// To put it in other words, if a mutable reference to the contents is active, no other references
1175+ /// can be active at the same time, and if an immutable reference to the contents is active, then
1176+ /// only other immutable reference may be active.
11731177///
11741178/// Note that while mutating or mutably aliasing the contents of an `& UnsafeCell<T>` is
11751179/// okay (provided you enforce the invariants some other way), it is still undefined behavior
0 commit comments