bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

Add more links in panic docs

Browse source
This commit is contained in:
Pazzaz 2018-04-29 13:45:33 +02:00
parent f76f6fbdea
commit 368fe37c22
2 changed files with 40 additions and 19 deletions
Download patch file Download diff file Expand all files Collapse all files

51
src/libstd/panic.rs
View file

@ -31,10 +31,14 @@ pub use core::panic::{PanicInfo, Location};
/// A marker trait which represents "panic safe" types in Rust.
///
/// This trait is implemented by default for many types and behaves similarly in
/// terms of inference of implementation to the `Send` and `Sync` traits. The
/// purpose of this trait is to encode what types are safe to cross a `catch_unwind`
/// terms of inference of implementation to the [`Send`] and [`Sync`] traits. The
/// purpose of this trait is to encode what types are safe to cross a [`catch_unwind`]
/// boundary with no fear of unwind safety.
///
/// [`Send`]: ../marker/trait.Send.html
/// [`Sync`]: ../marker/trait.Sync.html
/// [`catch_unwind`]: ./fn.catch_unwind.html
///
/// ## What is unwind safety?
///
/// In Rust a function can "return" early if it either panics or calls a
@ -95,12 +99,13 @@ pub use core::panic::{PanicInfo, Location};
///
/// ## When should `UnwindSafe` be used?
///
/// Is not intended that most types or functions need to worry about this trait.
/// It is only used as a bound on the `catch_unwind` function and as mentioned above,
/// the lack of `unsafe` means it is mostly an advisory. The `AssertUnwindSafe`
/// wrapper struct in this module can be used to force this trait to be
/// implemented for any closed over variables passed to the `catch_unwind` function
/// (more on this below).
/// It is not intended that most types or functions need to worry about this trait.
/// It is only used as a bound on the `catch_unwind` function and as mentioned
/// above, the lack of `unsafe` means it is mostly an advisory. The
/// [`AssertUnwindSafe`] wrapper struct can be used to force this trait to be
/// implemented for any closed over variables passed to `catch_unwind`.
///
/// [`AssertUnwindSafe`]: ./struct.AssertUnwindSafe.html
#[stable(feature = "catch_unwind", since = "1.9.0")]
#[rustc_on_unimplemented = "the type {Self} may not be safely transferred \
across an unwind boundary"]
@ -109,11 +114,14 @@ pub auto trait UnwindSafe {}
/// A marker trait representing types where a shared reference is considered
/// unwind safe.
///
/// This trait is namely not implemented by `UnsafeCell`, the root of all
/// This trait is namely not implemented by [`UnsafeCell`], the root of all
/// interior mutability.
///
/// This is a "helper marker trait" used to provide impl blocks for the
/// `UnwindSafe` trait, for more information see that documentation.
/// [`UnwindSafe`] trait, for more information see that documentation.
///
/// [`UnsafeCell`]: ../cell/struct.UnsafeCell.html
/// [`UnwindSafe`]: ./trait.UnwindSafe.html
#[stable(feature = "catch_unwind", since = "1.9.0")]
#[rustc_on_unimplemented = "the type {Self} may contain interior mutability \
and a reference may not be safely transferrable \
@ -122,14 +130,15 @@ pub auto trait RefUnwindSafe {}
/// A simple wrapper around a type to assert that it is unwind safe.
///
/// When using `catch_unwind` it may be the case that some of the closed over
/// When using [`catch_unwind`] it may be the case that some of the closed over
/// variables are not unwind safe. For example if `&mut T` is captured the
/// compiler will generate a warning indicating that it is not unwind safe. It
/// may not be the case, however, that this is actually a problem due to the
/// specific usage of `catch_unwind` if unwind safety is specifically taken into
/// specific usage of [`catch_unwind`] if unwind safety is specifically taken into
/// account. This wrapper struct is useful for a quick and lightweight
/// annotation that a variable is indeed unwind safe.
///
/// [`catch_unwind`]: ./fn.catch_unwind.html
/// # Examples
///
/// One way to use `AssertUnwindSafe` is to assert that the entire closure
@ -318,18 +327,22 @@ impl<T: fmt::Debug> fmt::Debug for AssertUnwindSafe<T> {
/// panic and allowing a graceful handling of the error.
///
/// It is **not** recommended to use this function for a general try/catch
/// mechanism. The `Result` type is more appropriate to use for functions that
/// mechanism. The [`Result`] type is more appropriate to use for functions that
/// can fail on a regular basis. Additionally, this function is not guaranteed
/// to catch all panics, see the "Notes" section below.
///
/// The closure provided is required to adhere to the `UnwindSafe` trait to ensure
/// [`Result`]: ../result/enum.Result.html
///
/// The closure provided is required to adhere to the [`UnwindSafe`] trait to ensure
/// that all captured variables are safe to cross this boundary. The purpose of
/// this bound is to encode the concept of [exception safety][rfc] in the type
/// system. Most usage of this function should not need to worry about this
/// bound as programs are naturally unwind safe without `unsafe` code. If it
/// becomes a problem the associated `AssertUnwindSafe` wrapper type in this
/// module can be used to quickly assert that the usage here is indeed unwind
/// safe.
/// becomes a problem the [`AssertUnwindSafe`] wrapper struct can be used to quickly
/// assert that the usage here is indeed unwind safe.
///
/// [`AssertUnwindSafe`]: ./struct.AssertUnwindSafe.html
/// [`UnwindSafe`]: ./trait.UnwindSafe.html
///
/// [rfc]: https://github.com/rust-lang/rfcs/blob/master/text/1236-stabilize-catch-panic.md
///
@ -364,9 +377,11 @@ pub fn catch_unwind<F: FnOnce() -> R + UnwindSafe, R>(f: F) -> Result<R> {
/// Triggers a panic without invoking the panic hook.
///
/// This is designed to be used in conjunction with `catch_unwind` to, for
/// This is designed to be used in conjunction with [`catch_unwind`] to, for
/// example, carry a panic across a layer of C code.
///
/// [`catch_unwind`]: ./fn.catch_unwind.html
///
/// # Notes
///
/// Note that panics in Rust are not always implemented via unwinding, but they