<!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 `thread` mod in crate `std`.">
<meta name="keywords" content="rust, rustlang, rust-lang, thread">
<title>std::thread - Rust</title>
<link rel="stylesheet" type="text/css" href="../../normalize.css">
<link rel="stylesheet" type="text/css" href="../../rustdoc.css">
<link rel="stylesheet" type="text/css" href="../../main.css">
<link rel="shortcut icon" href="https://doc.rust-lang.org/favicon.ico">
</head>
<body class="rustdoc mod">
<!--[if lte IE 8]>
<div class="warning">
This old browser is unsupported and will most likely display funky
things.
</div>
<![endif]-->
<nav class="sidebar">
<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'>Module thread</p><div class="block items"><ul><li><a href="#structs">Structs</a></li><li><a href="#enums">Enums</a></li><li><a href="#functions">Functions</a></li><li><a href="#types">Type Definitions</a></li></ul></div><p class='location'><a href='../index.html'>std</a></p><script>window.sidebarCurrent = {name: 'thread', ty: 'mod', 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">
<h1 class='fqn'><span class='in-band'>Module <a href='../index.html'>std</a>::<wbr><a class="mod" href=''>thread</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/mod.rs.html#11-1479' title='goto source code'>[src]</a></span></h1>
<div class='docblock'><p>Native threads.</p>
<h2 id='the-threading-model' class='section-header'><a href='#the-threading-model'>The threading model</a></h2>
<p>An executing Rust program consists of a collection of native OS threads,
each with their own stack and local state. Threads can be named, and
provide some built-in support for low-level synchronization.</p>
<p>Communication between threads can be done through
<a href="../../std/sync/mpsc/index.html">channels</a>, Rust's message-passing types, along with <a href="../../std/sync/index.html">other forms of thread
synchronization</a> and shared-memory data
structures. In particular, types that are guaranteed to be
threadsafe are easily shared between threads using the
atomically-reference-counted container, <a href="../../std/sync/struct.Arc.html"><code>Arc</code></a>.</p>
<p>Fatal logic errors in Rust cause <em>thread panic</em>, during which
a thread will unwind the stack, running destructors and freeing
owned resources. Thread panic is unrecoverable from within
the panicking thread (i.e. there is no 'try/catch' in Rust), but
the panic may optionally be detected from a different thread. If
the main thread panics, the application will exit with a non-zero
exit code.</p>
<p>When the main thread of a Rust program terminates, the entire program shuts
down, even if other threads are still running. However, this module provides
convenient facilities for automatically waiting for the termination of a
child thread (i.e., join).</p>
<h2 id='spawning-a-thread' class='section-header'><a href='#spawning-a-thread'>Spawning a thread</a></h2>
<p>A new thread can be spawned using the <a href="../../std/thread/fn.spawn.html"><code>thread::spawn</code></a> function:</p>
<pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">thread</span>;
<span class="ident">thread</span>::<span class="ident">spawn</span>(<span class="kw">move</span> <span class="op">||</span> {
<span class="comment">// some work here</span>
});<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=fn%20main()%20%7B%0Ause%20std%3A%3Athread%3B%0A%0Athread%3A%3Aspawn(move%20%7C%7C%20%7B%0A%20%20%20%20%2F%2F%20some%20work%20here%0A%7D)%3B%0A%7D">Run</a></pre>
<p>In this example, the spawned thread is "detached" from the current
thread. This means that it can outlive its parent (the thread that spawned
it), unless this parent is the main thread.</p>
<p>The parent thread can also wait on the completion of the child
thread; a call to <a href="../../std/thread/fn.spawn.html"><code>spawn</code></a> produces a <a href="../../std/thread/struct.JoinHandle.html"><code>JoinHandle</code></a>, which provides
a <code>join</code> method for waiting:</p>
<pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">thread</span>;
<span class="kw">let</span> <span class="ident">child</span> <span class="op">=</span> <span class="ident">thread</span>::<span class="ident">spawn</span>(<span class="kw">move</span> <span class="op">||</span> {
<span class="comment">// some work here</span>
});
<span class="comment">// some work here</span>
<span class="kw">let</span> <span class="ident">res</span> <span class="op">=</span> <span class="ident">child</span>.<span class="ident">join</span>();<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=fn%20main()%20%7B%0Ause%20std%3A%3Athread%3B%0A%0Alet%20child%20%3D%20thread%3A%3Aspawn(move%20%7C%7C%20%7B%0A%20%20%20%20%2F%2F%20some%20work%20here%0A%7D)%3B%0A%2F%2F%20some%20work%20here%0Alet%20res%20%3D%20child.join()%3B%0A%7D">Run</a></pre>
<p>The <a href="../../std/thread/struct.JoinHandle.html#method.join"><code>join</code></a> method returns a <a href="../../std/thread/type.Result.html"><code>thread::Result</code></a> containing <a href="../../std/result/enum.Result.html#variant.Ok"><code>Ok</code></a> of the final
value produced by the child thread, or <a href="../../std/result/enum.Result.html#variant.Err"><code>Err</code></a> of the value given to
a call to <a href="../../std/macro.panic.html"><code>panic!</code></a> if the child panicked.</p>
<h2 id='configuring-threads' class='section-header'><a href='#configuring-threads'>Configuring threads</a></h2>
<p>A new thread can be configured before it is spawned via the <a href="../../std/thread/struct.Builder.html"><code>Builder</code></a> type,
which currently allows you to set the name and stack size for the child thread:</p>
<pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">thread</span>;
<span class="ident">thread</span>::<span class="ident">Builder</span>::<span class="ident">new</span>().<span class="ident">name</span>(<span class="string">"child1"</span>.<span class="ident">to_string</span>()).<span class="ident">spawn</span>(<span class="kw">move</span> <span class="op">||</span> {
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"Hello, world!"</span>);
});<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused_must_use)%5D%0Afn%20main()%20%7B%0Ause%20std%3A%3Athread%3B%0A%0Athread%3A%3ABuilder%3A%3Anew().name(%22child1%22.to_string()).spawn(move%20%7C%7C%20%7B%0A%20%20%20%20println!(%22Hello%2C%20world!%22)%3B%0A%7D)%3B%0A%7D">Run</a></pre>
<h2 id='the-thread-type' class='section-header'><a href='#the-thread-type'>The <code>Thread</code> type</a></h2>
<p>Threads are represented via the <a href="../../std/thread/struct.Thread.html"><code>Thread</code></a> type, which you can get in one of
two ways:</p>
<ul>
<li>By spawning a new thread, e.g. using the <a href="../../std/thread/fn.spawn.html"><code>thread::spawn</code></a>
function, and calling <a href="../../std/thread/struct.JoinHandle.html#method.thread"><code>thread</code></a> on the <a href="../../std/thread/struct.JoinHandle.html"><code>JoinHandle</code></a>.</li>
<li>By requesting the current thread, using the <a href="../../std/thread/fn.current.html"><code>thread::current</code></a> function.</li>
</ul>
<p>The <a href="../../std/thread/fn.current.html"><code>thread::current</code></a> function is available even for threads not spawned
by the APIs of this module.</p>
<h2 id='thread-local-storage' class='section-header'><a href='#thread-local-storage'>Thread-local storage</a></h2>
<p>This module also provides an implementation of thread-local storage for Rust
programs. Thread-local storage is a method of storing data into a global
variable that each thread in the program will have its own copy of.
Threads do not share this data, so accesses do not need to be synchronized.</p>
<p>A thread-local key owns the value it contains and will destroy the value when the
thread exits. It is created with the <a href="../macro.thread_local.html"><code>thread_local!</code></a> macro and can contain any
value that is <code>'static</code> (no borrowed pointers). It provides an accessor function,
<a href="struct.LocalKey.html#method.with"><code>with</code></a>, that yields a shared reference to the value to the specified
closure. Thread-local keys allow only shared access to values, as there would be no
way to guarantee uniqueness if mutable borrows were allowed. Most values
will want to make use of some form of <strong>interior mutability</strong> through the
<a href="../cell/struct.Cell.html"><code>Cell</code></a> or <a href="../cell/struct.RefCell.html"><code>RefCell</code></a> types.</p>
</div><h2 id='structs' class='section-header'><a href="#structs">Structs</a></h2>
<table>
<tr class=' module-item'>
<td><a class="struct" href="struct.Builder.html"
title='struct std::thread::Builder'>Builder</a></td>
<td class='docblock-short'>
<p>Thread factory, which can be used in order to configure the properties of
a new thread.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.JoinHandle.html"
title='struct std::thread::JoinHandle'>JoinHandle</a></td>
<td class='docblock-short'>
<p>An owned permission to join on a thread (block on its termination).</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.LocalKey.html"
title='struct std::thread::LocalKey'>LocalKey</a></td>
<td class='docblock-short'>
<p>A thread local storage key which owns its contents.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.Thread.html"
title='struct std::thread::Thread'>Thread</a></td>
<td class='docblock-short'>
<p>A handle to a thread.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.ThreadId.html"
title='struct std::thread::ThreadId'>ThreadId</a></td>
<td class='docblock-short'>
<p>A unique identifier for a running thread.</p>
</td>
</tr></table><h2 id='enums' class='section-header'><a href="#enums">Enums</a></h2>
<table>
<tr class='unstable module-item'>
<td><a class="enum" href="enum.LocalKeyState.html"
title='enum std::thread::LocalKeyState'>LocalKeyState</a></td>
<td class='docblock-short'>
[<div class='stab unstable'>Experimental</div>] <p>Indicator of the state of a thread local storage key.</p>
</td>
</tr></table><h2 id='functions' class='section-header'><a href="#functions">Functions</a></h2>
<table>
<tr class=' module-item'>
<td><a class="fn" href="fn.current.html"
title='fn std::thread::current'>current</a></td>
<td class='docblock-short'>
<p>Gets a handle to the thread that invokes it.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="fn" href="fn.panicking.html"
title='fn std::thread::panicking'>panicking</a></td>
<td class='docblock-short'>
<p>Determines whether the current thread is unwinding because of panic.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="fn" href="fn.park.html"
title='fn std::thread::park'>park</a></td>
<td class='docblock-short'>
<p>Blocks unless or until the current thread's token is made available.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="fn" href="fn.park_timeout.html"
title='fn std::thread::park_timeout'>park_timeout</a></td>
<td class='docblock-short'>
<p>Blocks unless or until the current thread's token is made available or
the specified duration has been reached (may wake spuriously).</p>
</td>
</tr>
<tr class='deprecated module-item'>
<td><a class="fn" href="fn.park_timeout_ms.html"
title='fn std::thread::park_timeout_ms'>park_timeout_ms</a></td>
<td class='docblock-short'>
[<div class='stab deprecated'>Deprecated</div>] <p>Use <a href="fn.park_timeout.html"><code>park_timeout</code></a>.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="fn" href="fn.sleep.html"
title='fn std::thread::sleep'>sleep</a></td>
<td class='docblock-short'>
<p>Puts the current thread to sleep for the specified amount of time.</p>
</td>
</tr>
<tr class='deprecated module-item'>
<td><a class="fn" href="fn.sleep_ms.html"
title='fn std::thread::sleep_ms'>sleep_ms</a></td>
<td class='docblock-short'>
[<div class='stab deprecated'>Deprecated</div>] <p>Puts the current thread to sleep for the specified amount of time.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="fn" href="fn.spawn.html"
title='fn std::thread::spawn'>spawn</a></td>
<td class='docblock-short'>
<p>Spawns a new thread, returning a <a href="../../std/thread/struct.JoinHandle.html"><code>JoinHandle</code></a> for it.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="fn" href="fn.yield_now.html"
title='fn std::thread::yield_now'>yield_now</a></td>
<td class='docblock-short'>
<p>Cooperatively gives up a timeslice to the OS scheduler.</p>
</td>
</tr></table><h2 id='types' class='section-header'><a href="#types">Type Definitions</a></h2>
<table>
<tr class=' module-item'>
<td><a class="type" href="type.Result.html"
title='type std::thread::Result'>Result</a></td>
<td class='docblock-short'>
<p>A specialized <a href="../../std/result/enum.Result.html"><code>Result</code></a> type for threads.</p>
</td>
</tr></table></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>
<dt>+</dt>
<dd>Collapse/expand 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>
</div>
</div>
</aside>
<script>
window.rootPath = "../../";
window.currentCrate = "std";
</script>
<script src="../../main.js"></script>
<script defer src="../../search-index.js"></script>
</body>
</html>
distrib
>
Mageia
>
6
>
armv7hl
>
media
>
core-updates
>
by-pkgid
>
564935689ab5527f955e5449ded02799
>
files
>
5287
