Text of rust.docs.kernel.org › next › src › core › panic › unwind_safe.rs.html as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

unwind_safe.rs - source

Skip to main content core/panic/ unwind_safe.rs 1 use crate ::async_iter::AsyncIterator ; 2 use crate ::cell::UnsafeCell ; 3 use crate ::fmt ; 4 use crate ::future::Future ; 5 use crate ::marker::PointeeSized ; 6 use crate ::ops::{ Deref , DerefMut }; 7 use crate ::pin::Pin ; 8 use crate ::ptr::NonNull ; 9 use crate ::task::{ Context , Poll }; 10 11 /// A marker trait which represents "panic safe" types in Rust. 12 /// 13 /// This trait is implemented by default for many types and behaves similarly in 14 /// terms of inference of implementation to the [`Send`] and [`Sync`] traits.

The 15 /// purpose of this trait is to encode what types are safe to cross a [`catch_unwind`] 16 /// boundary with no fear of unwind safety. 17 /// 18 /// [`catch_unwind`]: ../../std/panic/fn.catch_unwind.html 19 /// 20 /// ## What is unwind safety? 21 /// 22 /// In Rust a function can "return" early if it either panics or calls a 23 /// function which transitively panics. This sort of control flow is not always 24 /// anticipated, and has the possibility of causing subtle bugs through a 25 /// combination of two critical components: 26 /// 27 /// 1.

A data structure is in a temporarily invalid state when the thread 28 /// panics. 29 /// 2. This broken invariant is then later observed. 30 /// 31 /// Typically in Rust, it is difficult to perform step (2) because catching a 32 /// panic involves either spawning a thread (which in turn makes it difficult 33 /// to later witness broken invariants) or using the `catch_unwind` function in this 34 /// module. Additionally, even if an invariant is witnessed, it typically isn't a 35 /// problem in Rust because there are no uninitialized values (like in C or C++).

36 /// 37 /// It is possible, however, for **logical** invariants to be broken in Rust, 38 /// which can end up causing behavioral bugs. Another key aspect of unwind safety 39 /// in Rust is that, in the absence of `unsafe` code, a panic cannot lead to 40 /// memory unsafety. 41 /// 42 /// That was a bit of a whirlwind tour of unwind safety, but for more information 43 /// about unwind safety and how it applies to Rust, see an [associated RFC][rfc].

44 /// 45 /// [rfc]: https://rust-lang.github.io/rfcs/1236-stabilize-catch-panic.html 46 /// 47 /// ## What is `UnwindSafe`? 48 /// 49 /// Now that we've got an idea of what unwind safety is in Rust, it's also 50 /// important to understand what this trait represents. As mentioned above, one 51 /// way to witness broken invariants is through the `catch_unwind` function in this 52 /// module as it allows catching a panic and then re-using the environment of 53 /// the closure.

54 /// 55 /// Simply put, a type `T` implements `UnwindSafe` if it cannot easily allow 56 /// witnessing a broken invariant through the use of `catch_unwind` (catching a 57 /// panic). This trait is an auto trait, so it is automatically implemented for 58 /// many types, and it is also structurally composed (e.g., a struct is unwind 59 /// safe if all of its components are unwind safe). 60 /// 61 /// Note, however, that this is not an unsafe trait, so there is not a succinct 62 /// contract that this trait is providing.

Instead it is intended as more of a 63 /// "speed bump" to alert users of `catch_unwind` that broken invariants may be 64 /// witnessed and may need to be accounted for. 65 /// 66 /// ## Who implements `UnwindSafe`? 67 /// 68 /// Types such as `&mut T` and `&RefCell<T>` are examples which are **not** 69 /// unwind safe. The general idea is that any mutable state which can be shared 70 /// across `catch_unwind` is not unwind safe by default.

This is because it is very 71 /// easy to witness a broken invariant outside of `catch_unwind` as the data is 72 /// simply accessed as usual. 73 /// 74 /// Types like `&Mutex<T>`, however, are unwind safe because they implement 75 /// poisoning by default. They still allow witnessing a broken invariant, but 76 /// they already provide their own "speed bumps" to do so. 77 /// 78 /// ## When should `UnwindSafe` be used?

79 /// 80 /// It is not intended that most types or functions need to worry about this trait. 81 /// It is only used as a bound on the `catch_unwind` function and as mentioned 82 /// above, the lack of `unsafe` means it is mostly an advisory. The 83 /// [`AssertUnwindSafe`] wrapper struct can be used to force this trait to be 84 /// implemented for any closed over variables passed to `catch_unwind`. 85 #[stable(feature = "catch_unwind" , since = "1.9.0" )] 86 #[rustc_diagnostic_item = "unwind_safe_trait" ] 87 #[diagnostic::on_unimplemented( 88 message = "the type `{Self}` may not be safely transferred across an unwind boundary" , 89 label = "`{Self}` may not be safely transferred across an unwind boundary" 90 )] 91 pub auto trait UnwindSafe {} 92 93 /// A marker trait representing types where a shared reference is considered 94 /// unwind safe.

95 /// 96 /// This trait is namely not implemented by [`UnsafeCell`], the root of all 97 /// interior mutability. 98 /// 99 /// This is a "helper marker trait" used to provide impl blocks for the 100 /// [`UnwindSafe`] trait, for more information see that documentation. 101 #[stable(feature = "catch_unwind" , since = "1.9.0" )] 102 #[rustc_diagnostic_item = "ref_unwind_safe_trait" ] 103 #[diagnostic::on_unimplemented( 104 message = "the type `{Self}` may contain interior mutability and a reference may not be safely \ 105 transferable across a catch_unwind boundary" , 106 label = "`{Self}` may contain interior mutability and a reference may not be safely \ 107 transferable across a catch_unwind boundary" 108 )] 109 pub auto trait RefUnwindSafe {} 110 111 /// A simple wrapper around a type to assert that it is unwind safe.

112 /// 113 /// When using [`catch_unwind`] it may be the case that some of the closed over 114 /// variables are not unwind safe. For example if `&mut T` is captured the 115 /// compiler will generate a warning indicating that it is not unwind safe. It 116 /// might not be the case, however, that this is actually a problem due to the 117 /// specific usage of [`catch_unwind`] if unwind safety is specifically taken into 118 /// account.

This wrapper struct is useful for a quick and lightweight 119 /// annotation that a variable is indeed unwind safe. 120 /// 121 /// [`catch_unwind`]: ../../std/panic/fn.catch_unwind.html 122 /// 123 /// # Examples 124 /// 125 /// One way to use `AssertUnwindSafe` is to assert that the entire closure 126 /// itself is unwind safe, bypassing all checks for all variables: 127 /// 128 /// ``` 129 /// use std::panic::{self, AssertUnwindSafe}; 130 /// 131 /// let mut variable = 4; 132 /// 133 /// // This code will not compile because the closure captures `&mut variable` 134 /// // which is not considered unwind safe by default.

135 /// 136 /// // panic::catch_unwind(|| { 137 /// // variable += 3; 138 /// // }); 139 /// 140 /// // This, however, will compile due to the `AssertUnwindSafe` wrapper 141 /// let result = panic::catch_unwind(AssertUnwindSafe(|| { 142 /// variable += 3; 143 /// })); 144 /// // ... 145 /// ``` 146 /// 147 /// Wrapping the entire closure amounts to a blanket assertion that all captured 148 /// variables are unwind safe.

This has the downside that if new captures are 149 /// added in the future, they will also be considered unwind safe. Therefore, 150 /// you may prefer to just wrap individual captures, as shown below. This is 151 /// more annotation, but it ensures that if a new capture is added which is not 152 /// unwind safe, you will get a compilation error at that time, which will 153 /// allow you to consider whether that new capture in fact represent a bug or 154 /// not.

155 /// 156 /// ``` 157 /// use std::panic::{self, AssertUnwindSafe}; 158 /// 159 /// let mut variable = 4; 160 /// let other_capture = 3; 161 /// 162 /// let result = { 163 /// let mut wrapper = AssertUnwindSafe(&mut variable); 164 /// panic::catch_unwind(move || { 165 /// **wrapper += other_capture; 166 /

The rest of this page is on the live site.