Auto merge of #147352 - matthiaskrgr:rollup-8i8s1n2, r=matthiaskrgr

Rollup of 6 pull requests

Successful merges:

 - #143900 ([rustdoc] Correctly handle `should_panic` doctest attribute and fix `--no-run` test flag on the 2024 edition)
 - #144908 (Fix doctest output json)
 - #147309 (Add documentation about unwinding to wasm targets)
 - #147328 (Implement non-poisoning `Mutex::with_mut`, `RwLock::with` and `RwLock::with_mut`)
 - #147337 (Make `fmt::Write` a diagnostic item)
 - #147349 (Improve the advice given by panic_immediate_abort)

r? `@ghost`
`@rustbot` modify labels: rollup

Author: bors

compiler/rustc_span/src/symbol.rs

@@ -236,6 +236,7 @@ symbols! {
         File,
         FileType,
         FmtArgumentsNew,
+        FmtWrite,
         Fn,
         FnMut,
         FnOnce,

library/core/src/fmt/mod.rs

@@ -115,6 +115,7 @@ pub struct Error;
 /// [`std::io::Write`]: ../../std/io/trait.Write.html
 /// [flushable]: ../../std/io/trait.Write.html#tymethod.flush
 #[stable(feature = "rust1", since = "1.0.0")]
+#[rustc_diagnostic_item = "FmtWrite"]
 pub trait Write {
     /// Writes a string slice into this writer, returning whether the write
     /// succeeded.

library/core/src/panicking.rs

@@ -35,7 +35,8 @@ use crate::panic::{Location, PanicInfo};
 #[cfg(feature = "panic_immediate_abort")]
 compile_error!(
     "panic_immediate_abort is now a real panic strategy! \
-    Enable it with the compiler flags `-Zunstable-options -Cpanic=immediate-abort`"
+    Enable it with `panic = \"immediate-abort\"` in Cargo.toml, \
+    or with the compiler flags `-Zunstable-options -Cpanic=immediate-abort`"
 );
 
 // First we define the two main entry points that all panics go through.

library/std/src/error.rs

@@ -123,7 +123,7 @@ use crate::fmt::{self, Write};
 /// the `Debug` output means `Report` is an ideal starting place for formatting errors returned
 /// from `main`.
 ///
-/// ```should_panic
+/// ```
 /// #![feature(error_reporter)]
 /// use std::error::Report;
 /// # use std::error::Error;
@@ -154,10 +154,14 @@ use crate::fmt::{self, Write};
 /// #     Err(SuperError { source: SuperErrorSideKick })
 /// # }
 ///
-/// fn main() -> Result<(), Report<SuperError>> {
+/// fn run() -> Result<(), Report<SuperError>> {
 ///     get_super_error()?;
 ///     Ok(())
 /// }
+///
+/// fn main() {
+///     assert!(run().is_err());
+/// }
 /// ```
 ///
 /// This example produces the following output:
@@ -170,7 +174,7 @@ use crate::fmt::{self, Write};
 /// output format. If you want to make sure your `Report`s are pretty printed and include backtrace
 /// you will need to manually convert and enable those flags.
 ///
-/// ```should_panic
+/// ```
 /// #![feature(error_reporter)]
 /// use std::error::Report;
 /// # use std::error::Error;
@@ -201,12 +205,16 @@ use crate::fmt::{self, Write};
 /// #     Err(SuperError { source: SuperErrorSideKick })
 /// # }
 ///
-/// fn main() -> Result<(), Report<SuperError>> {
+/// fn run() -> Result<(), Report<SuperError>> {
 ///     get_super_error()
 ///         .map_err(Report::from)
 ///         .map_err(|r| r.pretty(true).show_backtrace(true))?;
 ///     Ok(())
 /// }
+///
+/// fn main() {
+///     assert!(run().is_err());
+/// }
 /// ```
 ///
 /// This example produces the following output:

library/std/src/sync/nonpoison/mutex.rs

@@ -376,6 +376,40 @@ impl<T: ?Sized> Mutex<T> {
     pub const fn data_ptr(&self) -> *mut T {
         self.data.get()
     }
+
+    /// Acquires the mutex and provides mutable access to the underlying data by passing
+    /// a mutable reference to the given closure.
+    ///
+    /// This method acquires the lock, calls the provided closure with a mutable reference
+    /// to the data, and returns the result of the closure. The lock is released after
+    /// the closure completes, even if it panics.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(lock_value_accessors, nonpoison_mutex)]
+    ///
+    /// use std::sync::nonpoison::Mutex;
+    ///
+    /// let mutex = Mutex::new(2);
+    ///
+    /// let result = mutex.with_mut(|data| {
+    ///     *data += 3;
+    ///
+    ///     *data + 5
+    /// });
+    ///
+    /// assert_eq!(*mutex.lock(), 5);
+    /// assert_eq!(result, 10);
+    /// ```
+    #[unstable(feature = "lock_value_accessors", issue = "133407")]
+    // #[unstable(feature = "nonpoison_mutex", issue = "134645")]
+    pub fn with_mut<F, R>(&self, f: F) -> R
+    where
+        F: FnOnce(&mut T) -> R,
+    {
+        f(&mut self.lock())
+    }
 }
 
 #[unstable(feature = "nonpoison_mutex", issue = "134645")]

library/std/src/sync/nonpoison/rwlock.rs

@@ -498,6 +498,68 @@ impl<T: ?Sized> RwLock<T> {
     pub const fn data_ptr(&self) -> *mut T {
         self.data.get()
     }
+
+    /// Locks this `RwLock` with shared read access to the underlying data by passing
+    /// a reference to the given closure.
+    ///
+    /// This method acquires the lock, calls the provided closure with a reference
+    /// to the data, and returns the result of the closure. The lock is released after
+    /// the closure completes, even if it panics.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(lock_value_accessors, nonpoison_rwlock)]
+    ///
+    /// use std::sync::nonpoison::RwLock;
+    ///
+    /// let rwlock = RwLock::new(2);
+    /// let result = rwlock.with(|data| *data + 3);
+    ///
+    /// assert_eq!(result, 5);
+    /// ```
+    #[unstable(feature = "lock_value_accessors", issue = "133407")]
+    // #[unstable(feature = "nonpoison_rwlock", issue = "134645")]
+    pub fn with<F, R>(&self, f: F) -> R
+    where
+        F: FnOnce(&T) -> R,
+    {
+        f(&self.read())
+    }
+
+    /// Locks this `RwLock` with exclusive write access to the underlying data by passing
+    /// a mutable reference to the given closure.
+    ///
+    /// This method acquires the lock, calls the provided closure with a mutable reference
+    /// to the data, and returns the result of the closure. The lock is released after
+    /// the closure completes, even if it panics.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(lock_value_accessors, nonpoison_rwlock)]
+    ///
+    /// use std::sync::nonpoison::RwLock;
+    ///
+    /// let rwlock = RwLock::new(2);
+    ///
+    /// let result = rwlock.with_mut(|data| {
+    ///     *data += 3;
+    ///
+    ///     *data + 5
+    /// });
+    ///
+    /// assert_eq!(*rwlock.read(), 5);
+    /// assert_eq!(result, 10);
+    /// ```
+    #[unstable(feature = "lock_value_accessors", issue = "133407")]
+    // #[unstable(feature = "nonpoison_rwlock", issue = "134645")]
+    pub fn with_mut<F, R>(&self, f: F) -> R
+    where
+        F: FnOnce(&mut T) -> R,
+    {
+        f(&mut self.write())
+    }
 }
 
 #[unstable(feature = "nonpoison_rwlock", issue = "134645")]

library/std/tests/sync/mutex.rs

@@ -549,3 +549,17 @@ fn panic_while_mapping_unlocked_poison() {
 
     drop(lock);
 }
+
+#[test]
+fn test_mutex_with_mut() {
+    let mutex = std::sync::nonpoison::Mutex::new(2);
+
+    let result = mutex.with_mut(|value| {
+        *value += 3;
+
+        *value + 5
+    });
+
+    assert_eq!(*mutex.lock(), 5);
+    assert_eq!(result, 10);
+}

library/std/tests/sync/rwlock.rs

@@ -861,3 +861,25 @@ fn panic_while_mapping_write_unlocked_poison() {
 
     drop(lock);
 }
+
+#[test]
+fn test_rwlock_with() {
+    let rwlock = std::sync::nonpoison::RwLock::new(2);
+    let result = rwlock.with(|value| *value + 3);
+
+    assert_eq!(result, 5);
+}
+
+#[test]
+fn test_rwlock_with_mut() {
+    let rwlock = std::sync::nonpoison::RwLock::new(2);
+
+    let result = rwlock.with_mut(|value| {
+        *value += 3;
+
+        *value + 5
+    });
+
+    assert_eq!(*rwlock.read(), 5);
+    assert_eq!(result, 10);
+}

src/doc/rustc/src/platform-support/wasm32-unknown-unknown.md

@@ -157,7 +157,7 @@ $ cargo +nightly build -Zbuild-std=panic_abort,std --target wasm32-unknown-unkno
 ```
 
 Here the `mvp` "cpu" is a placeholder in LLVM for disabling all supported
-features by default. Cargo's `-Zbuild-std` feature, a Nightly Rust feature, is
+features by default. Cargo's [`-Zbuild-std`] feature, a Nightly Rust feature, is
 then used to recompile the standard library in addition to your own code. This
 will produce a binary that uses only the original WebAssembly features by
 default and no proposals since its inception.
@@ -207,3 +207,63 @@ conditionally compile code instead. This is notably different to the way native
 platforms such as x86\_64 work, and this is due to the fact that WebAssembly
 binaries must only contain code the engine understands. Native binaries work so
 long as the CPU doesn't execute unknown code dynamically at runtime.
+
+## Unwinding
+
+By default the `wasm32-unknown-unknown` target is compiled with `-Cpanic=abort`.
+Historically this was due to the fact that there was no way to catch panics in
+wasm, but since mid-2025 the WebAssembly [`exception-handling`
+proposal](https://github.com/WebAssembly/exception-handling) reached
+stabilization. LLVM has support for this proposal as well and when this is all
+combined together it's possible to enable `-Cpanic=unwind` on wasm targets.
+
+Compiling wasm targets with `-Cpanic=unwind` is not as easy as just passing
+`-Cpanic=unwind`, however:
+
+```sh
+$ rustc foo.rs -Cpanic=unwind --target wasm32-unknown-unknown
+error: the crate `panic_unwind` does not have the panic strategy `unwind`
+```
+
+Notably the precompiled standard library that is shipped through Rustup is
+compiled with `-Cpanic=abort`, not `-Cpanic=unwind`. While this is the case
+you're going to be required to use Cargo's [`-Zbuild-std`] feature to build with
+unwinding support:
+
+```sh
+$ RUSTFLAGS='-Cpanic=unwind' cargo +nightly build --target wasm32-unknown-unknown -Zbuild-std
+```
+
+Note, however, that as of 2025-10-03 LLVM is still using the "legacy exception
+instructions" by default, not the officially standard version of the
+exception-handling proposal:
+
+```sh
+$ wasm-tools validate target/wasm32-unknown-unknown/debug/foo.wasm
+error: <sysroot>/library/std/src/sys/backtrace.rs:161:5
+function `std::sys::backtrace::__rust_begin_short_backtrace` failed to validate
+
+Caused by:
+    0: func 2 failed to validate
+    1: legacy_exceptions feature required for try instruction (at offset 0x880)
+```
+
+Fixing this requires passing `-Cllvm-args=-wasm-use-legacy-eh=false` to the Rust
+compiler as well:
+
+```sh
+$ RUSTFLAGS='-Cpanic=unwind -Cllvm-args=-wasm-use-legacy-eh=false' cargo +nightly build --target wasm32-unknown-unknown -Zbuild-std
+$ wasm-tools validate target/wasm32-unknown-unknown/debug/foo.wasm
+```
+
+At this time there are no concrete plans for adding new targets to the Rust
+compiler which have `-Cpanic=unwind` enabled-by-default. The most likely route
+to having this enabled is that in a few years when the `exception-handling`
+target feature is enabled by default in LLVM (due to browsers/runtime support
+propagating widely enough) the targets will switch to using `-Cpanic=unwind` by
+default. This is not for certain, however, and will likely be accompanied with
+either an MCP or an RFC about changing all wasm targets in the same manner. In
+the meantime using `-Cpanic=unwind` will require using [`-Zbuild-std`] and
+passing the appropriate flags to rustc.
+
+[`-Zbuild-std`]: ../../cargo/reference/unstable.html#build-std

src/doc/rustc/src/platform-support/wasm32-wasip1.md

@@ -133,3 +133,9 @@ to Rust 1.80 the `target_env` condition was not set.
 The default set of WebAssembly features enabled for compilation is currently the
 same as [`wasm32-unknown-unknown`](./wasm32-unknown-unknown.md). See the
 documentation there for more information.
+
+## Unwinding
+
+This target is compiled with `-Cpanic=abort` by default. For information on
+using `-Cpanic=unwind` see the [documentation about unwinding for
+`wasm32-unknown-unknown`](./wasm32-unknown-unknown.md#unwinding).