<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="API documentation for the Rust `UnwindSafe` trait in crate `std`."><meta name="keywords" content="rust, rustlang, rust-lang, UnwindSafe"><title>std::panic::UnwindSafe - Rust</title><link rel="stylesheet" type="text/css" href="../../normalize.css"><link rel="stylesheet" type="text/css" href="../../rustdoc.css" id="mainThemeStyle"><link rel="stylesheet" type="text/css" href="../../dark.css"><link rel="stylesheet" type="text/css" href="../../light.css" id="themeStyle"><script src="../../storage.js"></script><link rel="shortcut icon" href="https://doc.rust-lang.org/favicon.ico"></head><body class="rustdoc trait"><!--[if lte IE 8]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="sidebar"><div class="sidebar-menu">☰</div><a href='../../std/index.html'><img src='https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png' alt='logo' width='100'></a><p class='location'>Trait UnwindSafe</p><div class="sidebar-elems"><div class="block items"><a class="sidebar-title" href="#foreign-impls">Implementations on Foreign Types</a><div class="sidebar-links"><a href="#impl-UnwindSafe">Unique<T></a></div><a class="sidebar-title" href="#implementors">Implementors</a><a class="sidebar-title" href="#synthetic-implementors">Auto Implementors</a></div><p class='location'><a href='../index.html'>std</a>::<wbr><a href='index.html'>panic</a></p><script>window.sidebarCurrent = {name: 'UnwindSafe', ty: 'trait', relpath: ''};</script><script defer src="sidebar-items.js"></script></div></nav><div class="theme-picker"><button id="theme-picker" aria-label="Pick another theme!"><img src="../../brush.svg" width="18" alt="Pick another theme!"></button><div id="theme-choices"></div></div><script src="../../theme.js"></script><nav class="sub"><form class="search-form js-only"><div class="search-container"><input class="search-input" name="search" autocomplete="off" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"><a id="settings-menu" href="../../settings.html"><img src="../../wheel.svg" width="18" alt="Change settings"></a></div></form></nav><section id="main" class="content"><h1 class='fqn'><span class='in-band'>Trait <a href='../index.html'>std</a>::<wbr><a href='index.html'>panic</a>::<wbr><a class="trait" href=''>UnwindSafe</a></span><span class='out-of-band'><span class='since' title='Stable since Rust version 1.9.0'>1.9.0</span><span id='render-detail'><a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">[<span class='inner'>−</span>]</a></span><a class='srclink' href='../../src/std/panic.rs.html#112' title='goto source code'>[src]</a></span></h1><div class="docblock type-decl"><pre class='rust trait'>pub auto trait UnwindSafe { }</pre></div><div class='docblock'><p>A marker trait which represents "panic safe" types in Rust.</p> <p>This trait is implemented by default for many types and behaves similarly in terms of inference of implementation to the <a href="../marker/trait.Send.html"><code>Send</code></a> and <a href="../marker/trait.Sync.html"><code>Sync</code></a> traits. The purpose of this trait is to encode what types are safe to cross a <a href="./fn.catch_unwind.html"><code>catch_unwind</code></a> boundary with no fear of unwind safety.</p> <h2 id="what-is-unwind-safety" class="section-header"><a href="#what-is-unwind-safety">What is unwind safety?</a></h2> <p>In Rust a function can "return" early if it either panics or calls a function which transitively panics. This sort of control flow is not always anticipated, and has the possibility of causing subtle bugs through a combination of two critical components:</p> <ol> <li>A data structure is in a temporarily invalid state when the thread panics.</li> <li>This broken invariant is then later observed.</li> </ol> <p>Typically in Rust, it is difficult to perform step (2) because catching a panic involves either spawning a thread (which in turns makes it difficult to later witness broken invariants) or using the <code>catch_unwind</code> function in this module. Additionally, even if an invariant is witnessed, it typically isn't a problem in Rust because there are no uninitialized values (like in C or C++).</p> <p>It is possible, however, for <strong>logical</strong> invariants to be broken in Rust, which can end up causing behavioral bugs. Another key aspect of unwind safety in Rust is that, in the absence of <code>unsafe</code> code, a panic cannot lead to memory unsafety.</p> <p>That was a bit of a whirlwind tour of unwind safety, but for more information about unwind safety and how it applies to Rust, see an <a href="https://github.com/rust-lang/rfcs/blob/master/text/1236-stabilize-catch-panic.md">associated RFC</a>.</p> <h2 id="what-is-unwindsafe" class="section-header"><a href="#what-is-unwindsafe">What is <code>UnwindSafe</code>?</a></h2> <p>Now that we've got an idea of what unwind safety is in Rust, it's also important to understand what this trait represents. As mentioned above, one way to witness broken invariants is through the <code>catch_unwind</code> function in this module as it allows catching a panic and then re-using the environment of the closure.</p> <p>Simply put, a type <code>T</code> implements <code>UnwindSafe</code> if it cannot easily allow witnessing a broken invariant through the use of <code>catch_unwind</code> (catching a panic). This trait is a marker trait, so it is automatically implemented for many types, and it is also structurally composed (e.g. a struct is unwind safe if all of its components are unwind safe).</p> <p>Note, however, that this is not an unsafe trait, so there is not a succinct contract that this trait is providing. Instead it is intended as more of a "speed bump" to alert users of <code>catch_unwind</code> that broken invariants may be witnessed and may need to be accounted for.</p> <h2 id="who-implements-unwindsafe" class="section-header"><a href="#who-implements-unwindsafe">Who implements <code>UnwindSafe</code>?</a></h2> <p>Types such as <code>&mut T</code> and <code>&RefCell<T></code> are examples which are <strong>not</strong> unwind safe. The general idea is that any mutable state which can be shared across <code>catch_unwind</code> is not unwind safe by default. This is because it is very easy to witness a broken invariant outside of <code>catch_unwind</code> as the data is simply accessed as usual.</p> <p>Types like <code>&Mutex<T></code>, however, are unwind safe because they implement poisoning by default. They still allow witnessing a broken invariant, but they already provide their own "speed bumps" to do so.</p> <h2 id="when-should-unwindsafe-be-used" class="section-header"><a href="#when-should-unwindsafe-be-used">When should <code>UnwindSafe</code> be used?</a></h2> <p>It is not intended that most types or functions need to worry about this trait. It is only used as a bound on the <code>catch_unwind</code> function and as mentioned above, the lack of <code>unsafe</code> means it is mostly an advisory. The <a href="./struct.AssertUnwindSafe.html"><code>AssertUnwindSafe</code></a> wrapper struct can be used to force this trait to be implemented for any closed over variables passed to <code>catch_unwind</code>.</p> </div> <h2 id='foreign-impls' class='small-section-header'> Implementations on Foreign Types<a href='#foreign-impls' class='anchor'></a> </h2> <h3 id='impl-UnwindSafe' class='impl'><span class='in-band'><table class='table-display'><tbody><tr><td><code>impl<T: <a class="trait" href="../../std/panic/trait.UnwindSafe.html" title="trait std::panic::UnwindSafe">UnwindSafe</a> + ?<a class="trait" href="../../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>> <a class="trait" href="../../std/panic/trait.UnwindSafe.html" title="trait std::panic::UnwindSafe">UnwindSafe</a> for Unique<T></code><a href='#impl-UnwindSafe' class='anchor'></a></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/std/panic.rs.html#212' title='goto source code'>[src]</a></span></td></tr></tbody></table></h3><span class='docblock autohide'><div class='impl-items'></div></span> <h2 id='implementors' class='small-section-header'> Implementors<a href='#implementors' class='anchor'></a> </h2> <ul class='item-list' id='implementors-list'> <li><table class='table-display'><tbody><tr><td><code>impl<'a, T: ?<a class="trait" href="../../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>> !UnwindSafe for <a class="primitive" href="../primitive.reference.html">&'a mut </a>T</code><td><div class='out-of-band'><a class='srclink' href='../../src/std/panic.rs.html#204' title='goto source code'>[src]</a></div></td></tr></tbody></table></li> <li><table class='table-display'><tbody><tr><td><code>impl<'a, T: <a class="trait" href="../../std/panic/trait.RefUnwindSafe.html" title="trait std::panic::RefUnwindSafe">RefUnwindSafe</a> + ?<a class="trait" href="../../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>> UnwindSafe for <a class="primitive" href="../primitive.reference.html">&'a </a>T</code><td><div class='out-of-band'><a class='srclink' href='../../src/std/panic.rs.html#206' title='goto source code'>[src]</a></div></td></tr></tbody></table></li> <li><table class='table-display'><tbody><tr><td><code>impl<T: <a class="trait" href="../../std/panic/trait.RefUnwindSafe.html" title="trait std::panic::RefUnwindSafe">RefUnwindSafe</a> + ?<a class="trait" href="../../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>> UnwindSafe for <a class="primitive" href="../primitive.pointer.html">*const T</a></code><td><div class='out-of-band'><a class='srclink' href='../../src/std/panic.rs.html#208' title='goto source code'>[src]</a></div></td></tr></tbody></table></li> <li><table class='table-display'><tbody><tr><td><code>impl<T: <a class="trait" href="../../std/panic/trait.RefUnwindSafe.html" title="trait std::panic::RefUnwindSafe">RefUnwindSafe</a> + ?<a class="trait" href="../../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>> UnwindSafe for <a class="primitive" href="../primitive.pointer.html">*mut T</a></code><td><div class='out-of-band'><a class='srclink' href='../../src/std/panic.rs.html#210' title='goto source code'>[src]</a></div></td></tr></tbody></table></li> <li><table class='table-display'><tbody><tr><td><code>impl<T: <a class="trait" href="../../std/panic/trait.RefUnwindSafe.html" title="trait std::panic::RefUnwindSafe">RefUnwindSafe</a> + ?<a class="trait" href="../../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>> UnwindSafe for <a class="struct" href="../../std/ptr/struct.NonNull.html" title="struct std::ptr::NonNull">NonNull</a><T></code><td><div class='out-of-band'><a class='srclink' href='../../src/std/panic.rs.html#214' title='goto source code'>[src]</a></div></td></tr></tbody></table></li> <li><table class='table-display'><tbody><tr><td><code>impl<T: ?<a class="trait" href="../../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>> UnwindSafe for <a class="struct" href="../../std/sync/struct.Mutex.html" title="struct std::sync::Mutex">Mutex</a><T></code><td><div class='out-of-band'><a class='srclink' href='../../src/std/panic.rs.html#216' title='goto source code'>[src]</a></div></td></tr></tbody></table></li> <li><table class='table-display'><tbody><tr><td><code>impl<T: ?<a class="trait" href="../../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>> UnwindSafe for <a class="struct" href="../../std/sync/struct.RwLock.html" title="struct std::sync::RwLock">RwLock</a><T></code><td><div class='out-of-band'><a class='srclink' href='../../src/std/panic.rs.html#218' title='goto source code'>[src]</a></div></td></tr></tbody></table></li> <li><table class='table-display'><tbody><tr><td><code>impl<T> UnwindSafe for <a class="struct" href="../../std/panic/struct.AssertUnwindSafe.html" title="struct std::panic::AssertUnwindSafe">AssertUnwindSafe</a><T></code><td><div class='out-of-band'><a class='srclink' href='../../src/std/panic.rs.html#220' title='goto source code'>[src]</a></div></td></tr></tbody></table></li> <li><table class='table-display'><tbody><tr><td><code>impl<T: <a class="trait" href="../../std/panic/trait.RefUnwindSafe.html" title="trait std::panic::RefUnwindSafe">RefUnwindSafe</a> + ?<a class="trait" href="../../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>> UnwindSafe for <a class="struct" href="../../std/rc/struct.Rc.html" title="struct std::rc::Rc">Rc</a><T></code><td><div class='out-of-band'><a class='srclink' href='../../src/std/panic.rs.html#226' title='goto source code'>[src]</a></div></td></tr></tbody></table></li> <li><table class='table-display'><tbody><tr><td><code>impl<T: <a class="trait" href="../../std/panic/trait.RefUnwindSafe.html" title="trait std::panic::RefUnwindSafe">RefUnwindSafe</a> + ?<a class="trait" href="../../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>> UnwindSafe for <a class="struct" href="../../std/sync/struct.Arc.html" title="struct std::sync::Arc">Arc</a><T></code><td><div class='out-of-band'><a class='srclink' href='../../src/std/panic.rs.html#228' title='goto source code'>[src]</a></div></td></tr></tbody></table></li> </ul> <h2 id='synthetic-implementors' class='small-section-header'> Auto implementors<a href='#synthetic-implementors' class='anchor'></a> </h2> <ul class='item-list' id='synthetic-implementors-list'> </ul><script type="text/javascript">window.inlined_types=new Set([]);</script><script type="text/javascript" async src="../../implementors/std/panic/trait.UnwindSafe.js"> </script></section><section id="search" class="content hidden"></section><section class="footer"></section><aside id="help" class="hidden"><div><h1 class="hidden">Help</h1><div class="shortcuts"><h2>Keyboard Shortcuts</h2><dl><dt><kbd>?</kbd></dt><dd>Show this help dialog</dd><dt><kbd>S</kbd></dt><dd>Focus the search field</dd><dt><kbd>↑</kbd></dt><dd>Move up in search results</dd><dt><kbd>↓</kbd></dt><dd>Move down in search results</dd><dt><kbd>↹</kbd></dt><dd>Switch tab</dd><dt><kbd>⏎</kbd></dt><dd>Go to active search result</dd><dt><kbd>+</kbd></dt><dd>Expand all sections</dd><dt><kbd>-</kbd></dt><dd>Collapse all sections</dd></dl></div><div class="infos"><h2>Search Tricks</h2><p>Prefix searches with a type followed by a colon (e.g. <code>fn:</code>) to restrict the search to a given type.</p><p>Accepted types are: <code>fn</code>, <code>mod</code>, <code>struct</code>, <code>enum</code>, <code>trait</code>, <code>type</code>, <code>macro</code>, and <code>const</code>.</p><p>Search functions by type signature (e.g. <code>vec -> usize</code> or <code>* -> vec</code>)</p><p>Search multiple things at once by splitting your query with comma (e.g. <code>str,u8</code> or <code>String,struct:Vec,test</code>)</p></div></div></aside><script>window.rootPath = "../../";window.currentCrate = "std";</script><script src="../../aliases.js"></script><script src="../../main.js"></script><script defer src="../../search-index.js"></script></body></html>