rust-lang/rust
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Auto merge of #128321 - BatmanAoD:catch-unwind-doc-update, r=Mark-Simulacrum

Browse Source 
Update `catch_unwind` doc comments for `c_unwind`

Updates `catch_unwind` doc comments to indicate that catching a foreign exception _will no longer_ be UB. Instead, there are two possible behaviors, though it is not specified which one an implementation will choose.

Nominated for t-lang to confirm that they are okay with making such a promise based on t-opsem FCP, or whether they would like to be included in the FCP.

Related: https://github.com/rust-lang/rust/issues/74990, https://github.com/rust-lang/rust/issues/115285, https://github.com/rust-lang/reference/pull/1226
This commit is contained in:
bors
2024-09-29 05:54:47 +00:00
parent 1d9162bced 249d3d2644
commit 9903b256a2
3 changed files with 70 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
library/std/src/thread/mod.rs
View File

@@ -664,6 +664,19 @@ impl Builder {
/// println!("{result}");
/// ```
///
/// # Notes
///
/// This function has the same minimal guarantee regarding "foreign" unwinding operations (e.g.
/// an exception thrown from C++ code, or a `panic!` in Rust code compiled or linked with a
/// different runtime) as [`catch_unwind`]; namely, if the thread created with `thread::spawn`
/// unwinds all the way to the root with such an exception, one of two behaviors are possible,
/// and it is unspecified which will occur:
///
/// * The process aborts.
/// * The process does not abort, and [`join`] will return a `Result::Err`
/// containing an opaque type.
///
/// [`catch_unwind`]: ../../std/panic/fn.catch_unwind.html
/// [`channels`]: crate::sync::mpsc
/// [`join`]: JoinHandle::join
/// [`Err`]: crate::result::Result::Err
@@ -1784,7 +1797,7 @@ impl<T> JoinHandle<T> {
/// operations that happen after `join` returns.
///
/// If the associated thread panics, [`Err`] is returned with the parameter given
/// to [`panic!`].
/// to [`panic!`] (though see the Notes below).
///
/// [`Err`]: crate::result::Result::Err
/// [atomic memory orderings]: crate::sync::atomic
@@ -1806,6 +1819,18 @@ impl<T> JoinHandle<T> {
/// }).unwrap();
/// join_handle.join().expect("Couldn't join on the associated thread");
/// ```
///
/// # Notes
///
/// If a "foreign" unwinding operation (e.g. an exception thrown from C++
/// code, or a `panic!` in Rust code compiled or linked with a different
/// runtime) unwinds all the way to the thread root, the process may be
/// aborted; see the Notes on [`thread::spawn`]. If the process is not
/// aborted, this function will return a `Result::Err` containing an opaque
/// type.
///
/// [`catch_unwind`]: ../../std/panic/fn.catch_unwind.html
/// [`thread::spawn`]: spawn
#[stable(feature = "rust1", since = "1.0.0")]
pub fn join(self) -> Result<T> {
self.0.join()