198 lines
No EOL
13 KiB
HTML
198 lines
No EOL
13 KiB
HTML
<!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 `bitflags`.">
|
||
<meta name="keywords" content="rust, rustlang, rust-lang, UnwindSafe">
|
||
|
||
<title>bitflags::__core::panic::UnwindSafe - Rust</title>
|
||
|
||
<link rel="stylesheet" type="text/css" href="../../../rustdoc.css">
|
||
<link rel="stylesheet" type="text/css" href="../../../main.css">
|
||
|
||
|
||
|
||
|
||
</head>
|
||
<body class="rustdoc">
|
||
<!--[if lte IE 8]>
|
||
<div class="warning">
|
||
This old browser is unsupported and will most likely display funky
|
||
things.
|
||
</div>
|
||
<![endif]-->
|
||
|
||
|
||
|
||
<nav class="sidebar">
|
||
|
||
<p class='location'><a href='../../index.html'>bitflags</a>::<wbr><a href='../index.html'>__core</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>
|
||
</nav>
|
||
|
||
<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">
|
||
</div>
|
||
</form>
|
||
</nav>
|
||
|
||
<section id='main' class="content trait">
|
||
<h1 class='fqn'><span class='in-band'>Trait <a href='../../index.html'>bitflags</a>::<wbr><a href='../index.html'>__core</a>::<wbr><a href='index.html'>panic</a>::<wbr><a class='trait' href=''>UnwindSafe</a></span><span class='out-of-band'><span id='render-detail'>
|
||
<a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">
|
||
[<span class='inner'>−</span>]
|
||
</a>
|
||
</span><a id='src-6623' class='srclink' href='https://doc.rust-lang.org/nightly/std/panic/trait.UnwindSafe.html?gotosrc=6623' title='goto source code'>[src]</a></span></h1>
|
||
<pre class='rust trait'>pub trait UnwindSafe { }</pre><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 <code>Send</code> and <code>Sync</code> traits. The
|
||
purpose of this trait is to encode what types are safe to cross a <code>recover</code>
|
||
boundary with no fear of panic safety.</p>
|
||
|
||
<h2 id='what-is-panic-safety' class='section-header'><a href='#what-is-panic-safety'>What is panic 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 cricial 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>recover</code> function in this
|
||
module. Additionally, even if an invariant is witnessed, it typically isn't a
|
||
problem in Rust because there's 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 panic 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 panic safety, but for more information
|
||
about panic 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-recoversafe' class='section-header'><a href='#what-is-recoversafe'>What is <code>RecoverSafe</code>?</a></h2>
|
||
<p>Now that we've got an idea of what panic 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>recover</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>RecoverSafe</code> if it cannot easily allow
|
||
witnessing a broken invariant through the use of <code>recover</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 recover
|
||
safe if all of its components are recover 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>recover</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>
|
||
recover safe. The general idea is that any mutable state which can be shared
|
||
across <code>recover</code> is not recover safe by default. This is because it is very
|
||
easy to witness a broken invariant outside of <code>recover</code> as the data is
|
||
simply accessed as usual.</p>
|
||
|
||
<p>Types like <code>&Mutex<T></code>, however, are recover 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>Is not intended that most types or functions need to worry about this trait.
|
||
It is only used as a bound on the <code>recover</code> function and as mentioned above,
|
||
the lack of <code>unsafe</code> means it is mostly an advisory. The <code>AssertRecoverSafe</code>
|
||
wrapper struct in this module can be used to force this trait to be
|
||
implemented for any closed over variables passed to the <code>recover</code> function
|
||
(more on this below).</p>
|
||
</div>
|
||
<h2 id='implementors'>Implementors</h2>
|
||
<ul class='item-list' id='implementors-list'>
|
||
<li><code>impl<'a, T> !UnwindSafe for &'a mut T <span class='where'>where T: ?<a class='trait' href='../../../bitflags/__core/marker/trait.Sized.html' title='bitflags::__core::marker::Sized'>Sized</a></span></code></li>
|
||
<li><code>impl<'a, T> UnwindSafe for &'a T <span class='where'>where T: <a class='trait' href='../../../bitflags/__core/panic/trait.RefUnwindSafe.html' title='bitflags::__core::panic::RefUnwindSafe'>RefUnwindSafe</a> + ?<a class='trait' href='../../../bitflags/__core/marker/trait.Sized.html' title='bitflags::__core::marker::Sized'>Sized</a></span></code></li>
|
||
<li><code>impl<T> UnwindSafe for <a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.pointer.html'>*const T</a> <span class='where'>where T: <a class='trait' href='../../../bitflags/__core/panic/trait.RefUnwindSafe.html' title='bitflags::__core::panic::RefUnwindSafe'>RefUnwindSafe</a> + ?<a class='trait' href='../../../bitflags/__core/marker/trait.Sized.html' title='bitflags::__core::marker::Sized'>Sized</a></span></code></li>
|
||
<li><code>impl<T> UnwindSafe for <a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.pointer.html'>*mut T</a> <span class='where'>where T: <a class='trait' href='../../../bitflags/__core/panic/trait.RefUnwindSafe.html' title='bitflags::__core::panic::RefUnwindSafe'>RefUnwindSafe</a> + ?<a class='trait' href='../../../bitflags/__core/marker/trait.Sized.html' title='bitflags::__core::marker::Sized'>Sized</a></span></code></li>
|
||
<li><code>impl<T> UnwindSafe for <a class='struct' href='../../../bitflags/__core/ptr/struct.Unique.html' title='bitflags::__core::ptr::Unique'>Unique</a><T> <span class='where'>where T: <a class='trait' href='../../../bitflags/__core/panic/trait.UnwindSafe.html' title='bitflags::__core::panic::UnwindSafe'>UnwindSafe</a></span></code></li>
|
||
<li><code>impl<T> UnwindSafe for <a class='struct' href='../../../bitflags/__core/ptr/struct.Shared.html' title='bitflags::__core::ptr::Shared'>Shared</a><T> <span class='where'>where T: <a class='trait' href='../../../bitflags/__core/panic/trait.RefUnwindSafe.html' title='bitflags::__core::panic::RefUnwindSafe'>RefUnwindSafe</a> + ?<a class='trait' href='../../../bitflags/__core/marker/trait.Sized.html' title='bitflags::__core::marker::Sized'>Sized</a></span></code></li>
|
||
<li><code>impl<T> UnwindSafe for <a class='struct' href='../../../bitflags/__core/sync/struct.Mutex.html' title='bitflags::__core::sync::Mutex'>Mutex</a><T> <span class='where'>where T: ?<a class='trait' href='../../../bitflags/__core/marker/trait.Sized.html' title='bitflags::__core::marker::Sized'>Sized</a></span></code></li>
|
||
<li><code>impl<T> UnwindSafe for <a class='struct' href='../../../bitflags/__core/sync/struct.RwLock.html' title='bitflags::__core::sync::RwLock'>RwLock</a><T> <span class='where'>where T: ?<a class='trait' href='../../../bitflags/__core/marker/trait.Sized.html' title='bitflags::__core::marker::Sized'>Sized</a></span></code></li>
|
||
<li><code>impl<T> UnwindSafe for <a class='struct' href='../../../bitflags/__core/panic/struct.AssertUnwindSafe.html' title='bitflags::__core::panic::AssertUnwindSafe'>AssertUnwindSafe</a><T></code></li>
|
||
<li><code>impl<T> UnwindSafe for <a class='struct' href='../../../bitflags/__core/panic/struct.AssertRecoverSafe.html' title='bitflags::__core::panic::AssertRecoverSafe'>AssertRecoverSafe</a><T></code></li>
|
||
<li><code>impl<T> UnwindSafe for <a class='struct' href='../../../bitflags/__core/rc/struct.Rc.html' title='bitflags::__core::rc::Rc'>Rc</a><T> <span class='where'>where T: <a class='trait' href='../../../bitflags/__core/panic/trait.RefUnwindSafe.html' title='bitflags::__core::panic::RefUnwindSafe'>RefUnwindSafe</a> + ?<a class='trait' href='../../../bitflags/__core/marker/trait.Sized.html' title='bitflags::__core::marker::Sized'>Sized</a></span></code></li>
|
||
<li><code>impl<T> UnwindSafe for <a class='struct' href='../../../bitflags/__core/sync/struct.Arc.html' title='bitflags::__core::sync::Arc'>Arc</a><T> <span class='where'>where T: <a class='trait' href='../../../bitflags/__core/panic/trait.RefUnwindSafe.html' title='bitflags::__core::panic::RefUnwindSafe'>RefUnwindSafe</a> + ?<a class='trait' href='../../../bitflags/__core/marker/trait.Sized.html' title='bitflags::__core::marker::Sized'>Sized</a></span></code></li>
|
||
</ul><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>?</dt>
|
||
<dd>Show this help dialog</dd>
|
||
<dt>S</dt>
|
||
<dd>Focus the search field</dd>
|
||
<dt>⇤</dt>
|
||
<dd>Move up in search results</dd>
|
||
<dt>⇥</dt>
|
||
<dd>Move down in search results</dd>
|
||
<dt>⏎</dt>
|
||
<dd>Go to active search result</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>
|
||
</div>
|
||
</div>
|
||
</aside>
|
||
|
||
|
||
|
||
<script>
|
||
window.rootPath = "../../../";
|
||
window.currentCrate = "bitflags";
|
||
window.playgroundUrl = "";
|
||
</script>
|
||
<script src="../../../jquery.js"></script>
|
||
<script src="../../../main.js"></script>
|
||
|
||
<script defer src="../../../search-index.js"></script>
|
||
</body>
|
||
</html> |