<!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 `LocalKey` struct in crate `std`."><meta name="keywords" content="rust, rustlang, rust-lang, LocalKey"><title>std::thread::LocalKey - 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 struct"><!--[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'>Struct LocalKey</p><div class="sidebar-elems"><div class="block items"><a class="sidebar-title" href="#methods">Methods</a><div class="sidebar-links"><a href="#method.with">with</a><a href="#method.try_with">try_with</a></div><a class="sidebar-title" href="#implementations">Trait Implementations</a><div class="sidebar-links"><a href="#impl-Debug">Debug</a></div><a class="sidebar-title" href="#synthetic-implementations">Auto Trait Implementations</a><div class="sidebar-links"><a href="#impl-Send">Send</a><a href="#impl-Sync">Sync</a></div></div><p class='location'><a href='../index.html'>std</a>::<wbr><a href='index.html'>thread</a></p><script>window.sidebarCurrent = {name: 'LocalKey', ty: 'struct', 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'>Struct <a href='../index.html'>std</a>::<wbr><a href='index.html'>thread</a>::<wbr><a class="struct" href=''>LocalKey</a></span><span class='out-of-band'><span class='since' title='Stable since Rust version 1.0.0'>1.0.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/thread/local.rs.html#89-108' title='goto source code'>[src]</a></span></h1><div class="docblock type-decl"><pre class='rust struct'>pub struct LocalKey<T: 'static> { /* fields omitted */ }</pre></div><div class='docblock'><p>A thread local storage key which owns its contents.</p>
<p>This key uses the fastest possible implementation available to it for the
target platform. It is instantiated with the <a href="../../std/macro.thread_local.html"><code>thread_local!</code></a> macro and the
primary method is the <a href="../../std/thread/struct.LocalKey.html#method.with"><code>with</code></a> method.</p>
<p>The <a href="../../std/thread/struct.LocalKey.html#method.with"><code>with</code></a> method yields a reference to the contained value which cannot be
sent across threads or escape the given closure.</p>
<h1 id="initialization-and-destruction" class="section-header"><a href="#initialization-and-destruction">Initialization and Destruction</a></h1>
<p>Initialization is dynamically performed on the first call to <a href="../../std/thread/struct.LocalKey.html#method.with"><code>with</code></a>
within a thread, and values that implement <a href="../../std/ops/trait.Drop.html"><code>Drop</code></a> get destructed when a
thread exits. Some caveats apply, which are explained below.</p>
<p>A <code>LocalKey</code>'s initializer cannot recursively depend on itself, and using
a <code>LocalKey</code> in this way will cause the initializer to infinitely recurse
on the first call to <code>with</code>.</p>
<h1 id="examples" class="section-header"><a href="#examples">Examples</a></h1>
<pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">cell</span>::<span class="ident">RefCell</span>;
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">thread</span>;
<span class="macro">thread_local</span><span class="macro">!</span>(<span class="kw">static</span> <span class="ident">FOO</span>: <span class="ident">RefCell</span><span class="op"><</span><span class="ident">u32</span><span class="op">></span> <span class="op">=</span> <span class="ident">RefCell</span>::<span class="ident">new</span>(<span class="number">1</span>));
<span class="ident">FOO</span>.<span class="ident">with</span>(<span class="op">|</span><span class="ident">f</span><span class="op">|</span> {
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="kw-2">*</span><span class="ident">f</span>.<span class="ident">borrow</span>(), <span class="number">1</span>);
<span class="kw-2">*</span><span class="ident">f</span>.<span class="ident">borrow_mut</span>() <span class="op">=</span> <span class="number">2</span>;
});
<span class="comment">// each thread starts out with the initial value of 1</span>
<span class="ident">thread</span>::<span class="ident">spawn</span>(<span class="kw">move</span><span class="op">||</span> {
<span class="ident">FOO</span>.<span class="ident">with</span>(<span class="op">|</span><span class="ident">f</span><span class="op">|</span> {
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="kw-2">*</span><span class="ident">f</span>.<span class="ident">borrow</span>(), <span class="number">1</span>);
<span class="kw-2">*</span><span class="ident">f</span>.<span class="ident">borrow_mut</span>() <span class="op">=</span> <span class="number">3</span>;
});
});
<span class="comment">// we retain our original value of 2 despite the child thread</span>
<span class="ident">FOO</span>.<span class="ident">with</span>(<span class="op">|</span><span class="ident">f</span><span class="op">|</span> {
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="kw-2">*</span><span class="ident">f</span>.<span class="ident">borrow</span>(), <span class="number">2</span>);
});<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Afn%20main()%20%7B%0Ause%20std%3A%3Acell%3A%3ARefCell%3B%0Ause%20std%3A%3Athread%3B%0A%0Athread_local!(static%20FOO%3A%20RefCell%3Cu32%3E%20%3D%20RefCell%3A%3Anew(1))%3B%0A%0AFOO.with(%7Cf%7C%20%7B%0A%20%20%20%20assert_eq!(*f.borrow()%2C%201)%3B%0A%20%20%20%20*f.borrow_mut()%20%3D%202%3B%0A%7D)%3B%0A%0A%2F%2F%20each%20thread%20starts%20out%20with%20the%20initial%20value%20of%201%0Athread%3A%3Aspawn(move%7C%7C%20%7B%0A%20%20%20%20FOO.with(%7Cf%7C%20%7B%0A%20%20%20%20%20%20%20%20assert_eq!(*f.borrow()%2C%201)%3B%0A%20%20%20%20%20%20%20%20*f.borrow_mut()%20%3D%203%3B%0A%20%20%20%20%7D)%3B%0A%7D)%3B%0A%0A%2F%2F%20we%20retain%20our%20original%20value%20of%202%20despite%20the%20child%20thread%0AFOO.with(%7Cf%7C%20%7B%0A%20%20%20%20assert_eq!(*f.borrow()%2C%202)%3B%0A%7D)%3B%0A%7D">Run</a></pre>
<h1 id="platform-specific-behavior" class="section-header"><a href="#platform-specific-behavior">Platform-specific behavior</a></h1>
<p>Note that a "best effort" is made to ensure that destructors for types
stored in thread local storage are run, but not all platforms can guarantee
that destructors will be run for all types in thread local storage. For
example, there are a number of known caveats where destructors are not run:</p>
<ol>
<li>On Unix systems when pthread-based TLS is being used, destructors will
not be run for TLS values on the main thread when it exits. Note that the
application will exit immediately after the main thread exits as well.</li>
<li>On all platforms it's possible for TLS to re-initialize other TLS slots
during destruction. Some platforms ensure that this cannot happen
infinitely by preventing re-initialization of any slot that has been
destroyed, but not all platforms have this guard. Those platforms that do
not guard typically have a synthetic limit after which point no more
destructors are run.</li>
<li>On macOS, initializing TLS during destruction of other TLS slots can
sometimes cancel <em>all</em> destructors for the current thread, whether or not
the slots have already had their destructors run or not.</li>
</ol>
</div>
<h2 id='methods' class='small-section-header'>
Methods<a href='#methods' class='anchor'></a>
</h2>
<h3 id='impl' class='impl'><span class='in-band'><table class='table-display'><tbody><tr><td><code>impl<T: 'static> <a class="struct" href="../../std/thread/struct.LocalKey.html" title="struct std::thread::LocalKey">LocalKey</a><T></code><a href='#impl' class='anchor'></a></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/std/thread/local.rs.html#222-300' title='goto source code'>[src]</a></span></td></tr></tbody></table></h3><div class='impl-items'><h4 id='method.with' class="method"><span id='with.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.with' class='fnname'>with</a><F, R>(&'static self, f: F) -> R <span class="where fmt-newline">where<br> F: <a class="trait" href="../../std/ops/trait.FnOnce.html" title="trait std::ops::FnOnce">FnOnce</a>(<a class="primitive" href="../primitive.reference.html">&</a>T) -> R, </span></code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/std/thread/local.rs.html#246-250' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='docblock'><p>Acquires a reference to the value in this TLS key.</p>
<p>This will lazily initialize the value if this thread has not referenced
this key yet.</p>
<h1 id="panics" class="section-header"><a href="#panics">Panics</a></h1>
<p>This function will <code>panic!()</code> if the key currently has its
destructor running, and it <strong>may</strong> panic if the destructor has
previously been run for this thread.</p>
</div><h4 id='method.try_with' class="method"><span id='try_with.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.try_with' class='fnname'>try_with</a><F, R>(&'static self, f: F) -> <a class="enum" href="../../std/result/enum.Result.html" title="enum std::result::Result">Result</a><R, <a class="struct" href="../../std/thread/struct.AccessError.html" title="struct std::thread::AccessError">AccessError</a>> <span class="where fmt-newline">where<br> F: <a class="trait" href="../../std/ops/trait.FnOnce.html" title="trait std::ops::FnOnce">FnOnce</a>(<a class="primitive" href="../primitive.reference.html">&</a>T) -> R, </span></code></span></td><td><span class='out-of-band'><div class='ghost'></div><div class='since' title='Stable since Rust version 1.26.0'>1.26.0</div><a class='srclink' href='../../src/std/thread/local.rs.html#286-299' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='docblock'><p>Acquires a reference to the value in this TLS key.</p>
<p>This will lazily initialize the value if this thread has not referenced
this key yet. If the key has been destroyed (which may happen if this is called
in a destructor), this function will return a <code>ThreadLocalError</code>.</p>
<h1 id="panics-1" class="section-header"><a href="#panics-1">Panics</a></h1>
<p>This function will still <code>panic!()</code> if the key is uninitialized and the
key's initializer panics.</p>
</div></div>
<h2 id='implementations' class='small-section-header'>
Trait Implementations<a href='#implementations' class='anchor'></a>
</h2>
<div id='implementations-list'><h3 id='impl-Debug' class='impl'><span class='in-band'><table class='table-display'><tbody><tr><td><code>impl<T: 'static> <a class="trait" href="../../std/fmt/trait.Debug.html" title="trait std::fmt::Debug">Debug</a> for <a class="struct" href="../../std/thread/struct.LocalKey.html" title="struct std::thread::LocalKey">LocalKey</a><T></code><a href='#impl-Debug' class='anchor'></a></span></td><td><span class='out-of-band'><div class='ghost'></div><div class='since' title='Stable since Rust version 1.16.0'>1.16.0</div><a class='srclink' href='../../src/std/thread/local.rs.html#111-115' title='goto source code'>[src]</a></span></td></tr></tbody></table></h3><div class='impl-items'><h4 id='method.fmt' class="method"><span id='fmt.v' class='invisible'><table class='table-display'><tbody><tr><td><code>fn <a href='../../std/fmt/trait.Debug.html#tymethod.fmt' class='fnname'>fmt</a>(&self, f: &mut <a class="struct" href="../../std/fmt/struct.Formatter.html" title="struct std::fmt::Formatter">Formatter</a>) -> <a class="type" href="../../std/fmt/type.Result.html" title="type std::fmt::Result">Result</a></code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/std/thread/local.rs.html#112-114' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='docblock'><p>Formats the value using the given formatter. <a href="../../std/fmt/trait.Debug.html#tymethod.fmt">Read more</a></p>
</div></div></div>
<h2 id='synthetic-implementations' class='small-section-header'>
Auto Trait Implementations<a href='#synthetic-implementations' class='anchor'></a>
</h2>
<div id='synthetic-implementations-list'>
<h3 id='impl-Send' class='impl'><span class='in-band'><table class='table-display'><tbody><tr><td><code>impl<T> <a class="trait" href="../../std/marker/trait.Send.html" title="trait std::marker::Send">Send</a> for <a class="struct" href="../../std/thread/struct.LocalKey.html" title="struct std::thread::LocalKey">LocalKey</a><T></code><a href='#impl-Send' class='anchor'></a></span></td><td><span class='out-of-band'></span></td></tr></tbody></table></h3><div class='impl-items'></div><h3 id='impl-Sync' class='impl'><span class='in-band'><table class='table-display'><tbody><tr><td><code>impl<T> <a class="trait" href="../../std/marker/trait.Sync.html" title="trait std::marker::Sync">Sync</a> for <a class="struct" href="../../std/thread/struct.LocalKey.html" title="struct std::thread::LocalKey">LocalKey</a><T></code><a href='#impl-Sync' class='anchor'></a></span></td><td><span class='out-of-band'></span></td></tr></tbody></table></h3><div class='impl-items'></div></div></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>
distrib
>
Mageia
>
6
>
armv7hl
>
media
>
core-updates
>
by-pkgid
>
4e2dbb669434a7691662cb2f0ad38972
>
files
>
15094
