Rollup merge of rust-lang#139164 - xizheyin:issue-139034, r=joboet

std: improve documentation for get_mut() methods regarding forgotten guards

Fixes rust-lang#139034

This PR improves the documentation for `get_mut()` methods in `Mutex`, `RefCell`, and `RwLock` to clarify their behavior when lock guards are forgotten (e.g., via std::mem::forget).

The current documentation for these methods states that a mutable borrow "statically guarantees no locks exist", which is not entirely accurate. While a mutable borrow prevents new locks from being created, it does not clear or detect previously abandoned locks through `forget()`. This can lead to counterintuitive behavior:

https://play.rust-lang.org/?version=stable&mode=debug&edition=2024&gist=e68cefec12dcd435daf2237c16824ed3
https://play.rust-lang.org/?version=nightly&mode=debug&edition=2024&gist=81263ad652c752afd63c903113d3082c
https://play.rust-lang.org/?version=stable&mode=debug&edition=2024&gist=311baa4edb3abf82a25c8d7bf21a4a52

r? libs

Author: matthiaskrgr

core/src/cell.rs

@@ -1156,7 +1156,9 @@ impl<T: ?Sized> RefCell<T> {
     /// Since this method borrows `RefCell` mutably, it is statically guaranteed
     /// that no borrows to the underlying data exist. The dynamic checks inherent
     /// in [`borrow_mut`] and most other methods of `RefCell` are therefore
-    /// unnecessary.
+    /// unnecessary. Note that this method does not reset the borrowing state if borrows were previously leaked
+    /// (e.g., via [`forget()`] on a [`Ref`] or [`RefMut`]). For that purpose,
+    /// consider using the unstable [`undo_leak`] method.
     ///
     /// This method can only be called if `RefCell` can be mutably borrowed,
     /// which in general is only the case directly after the `RefCell` has
@@ -1167,6 +1169,8 @@ impl<T: ?Sized> RefCell<T> {
     /// Use [`borrow_mut`] to get mutable access to the underlying data then.
     ///
     /// [`borrow_mut`]: RefCell::borrow_mut()
+    /// [`forget()`]: mem::forget
+    /// [`undo_leak`]: RefCell::undo_leak()
     ///
     /// # Examples
     ///

std/src/sync/poison/mutex.rs

@@ -582,7 +582,9 @@ impl<T: ?Sized> Mutex<T> {
     /// Returns a mutable reference to the underlying data.
     ///
     /// Since this call borrows the `Mutex` mutably, no actual locking needs to
-    /// take place -- the mutable borrow statically guarantees no locks exist.
+    /// take place -- the mutable borrow statically guarantees no new locks can be acquired
+    /// while this reference exists. Note that this method does not clear any previous abandoned locks
+    /// (e.g., via [`forget()`] on a [`MutexGuard`]).
     ///
     /// # Errors
     ///
@@ -599,6 +601,8 @@ impl<T: ?Sized> Mutex<T> {
     /// *mutex.get_mut().unwrap() = 10;
     /// assert_eq!(*mutex.lock().unwrap(), 10);
     /// ```
+    ///
+    /// [`forget()`]: mem::forget
     #[stable(feature = "mutex_get_mut", since = "1.6.0")]
     pub fn get_mut(&mut self) -> LockResult<&mut T> {
         let data = self.data.get_mut();

std/src/sync/poison/rwlock.rs

@@ -608,7 +608,9 @@ impl<T: ?Sized> RwLock<T> {
     /// Returns a mutable reference to the underlying data.
     ///
     /// Since this call borrows the `RwLock` mutably, no actual locking needs to
-    /// take place -- the mutable borrow statically guarantees no locks exist.
+    /// take place -- the mutable borrow statically guarantees no new locks can be acquired
+    /// while this reference exists. Note that this method does not clear any previously abandoned locks
+    /// (e.g., via [`forget()`] on a [`RwLockReadGuard`] or [`RwLockWriteGuard`]).
     ///
     /// # Errors
     ///