bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

update docs for catch_unwind & related funcs

Browse source 
Documentation comments for `catch_unwind` and `thread::join` to indicate
new behavioral guarantee when catching a foreign exception.
This commit is contained in:
Kyle J Strand 2024-07-28 16:48:14 -06:00 • committed by Kyle J Strand
parent d571ae851d
commit 249d3d2644
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

@ -665,6 +665,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
@ -1737,7 +1750,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
@ -1759,6 +1772,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()