Stabilize rwlock_downgrade library feature

[connortsui20]

Tracking Issue: #128203

Method to be stabilized:

impl<'a, T: ?Sized> RwLockWriteGuard<'a, T> {
    pub fn downgrade(s: Self) -> RwLockReadGuard<'a, T> {}
}

I would like to point out that my documentation comment is longer than ideal, but at the same time I don't really know how else to show why downgrade is actually necessary (instead of just unlocking and relocking). If anyone has ideas for making this more concise that would be great!

Current doc comment

Downgrades a write-locked RwLockWriteGuard into a read-locked [RwLockReadGuard].

This method will atomically change the state of the [RwLock] from exclusive mode into
shared mode. This means that it is impossible for a writing thread to get in between a
thread calling downgrade and the same thread reading whatever it wrote while it had the
[RwLock] in write mode.

Note that since we have the RwLockWriteGuard, we know that the [RwLock] is already
locked for writing, so this method cannot fail.

Example

use std::sync::{Arc, RwLock, RwLockWriteGuard};

// The inner value starts as 0.
let rw = Arc::new(RwLock::new(0));

// Put the lock in write mode.
let mut main_write_guard = rw.write().unwrap();

let evil = rw.clone();
let handle = std::thread::spawn(move || {
    // This will not return until the main thread drops the `main_read_guard`.
    let mut evil_guard = evil.write().unwrap();

    assert_eq!(*evil_guard, 1);
    *evil_guard = 2;
});

// After spawning the writer thread, set the inner value to 1.
*main_write_guard = 1;

// Atomically downgrade the write guard into a read guard.
let main_read_guard = RwLockWriteGuard::downgrade(main_write_guard);

// Since `downgrade` is atomic, the writer thread cannot have set the inner value to 2.
assert_eq!(*main_read_guard, 1, "`downgrade` was not atomic");

// Clean up everything now
drop(main_read_guard);
handle.join().unwrap();

let final_check = rw.read().unwrap();
assert_eq!(*final_check, 2);

Stabilization report: #128203 (comment)

[rustbot]

r? @tgross35

rustbot has assigned @tgross35.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer