397 lines
No EOL
20 KiB
HTML
397 lines
No EOL
20 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 `thread` mod in crate `bitflags`.">
|
||
<meta name="keywords" content="rust, rustlang, rust-lang, thread">
|
||
|
||
<title>bitflags::__core::thread - 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></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 mod">
|
||
<h1 class='fqn'><span class='in-band'>Module <a href='../../index.html'>bitflags</a>::<wbr><a href='../index.html'>__core</a>::<wbr><a class='mod' href=''>thread</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-768' class='srclink' href='https://doc.rust-lang.org/nightly/std/thread/index.html?gotosrc=768' 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.</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='the-thread-type' class='section-header'><a href='#the-thread-type'>The <code>Thread</code> type</a></h2>
|
||
<p>Threads are represented via the <code>Thread</code> type, which you can
|
||
get in one of two ways:</p>
|
||
|
||
<ul>
|
||
<li>By spawning a new thread, e.g. using the <code>thread::spawn</code> function.</li>
|
||
<li>By requesting the current thread, using the <code>thread::current</code> function.</li>
|
||
</ul>
|
||
|
||
<p>Threads can be named, and provide some built-in support for low-level
|
||
synchronization (described below).</p>
|
||
|
||
<p>The <code>thread::current()</code> function is available even for threads not spawned
|
||
by the APIs of this module.</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 <code>thread::spawn</code> 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>
|
||
});</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 <code>spawn</code> produces a <code>JoinHandle</code>, 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>();</pre>
|
||
|
||
<p>The <code>join</code> method returns a <code>Result</code> containing <code>Ok</code> of the final
|
||
value produced by the child thread, or <code>Err</code> of the value given to
|
||
a call to <code>panic!</code> 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 <code>Builder</code> 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>);
|
||
});</pre>
|
||
|
||
<h2 id='blocking-support-park-and-unpark' class='section-header'><a href='#blocking-support-park-and-unpark'>Blocking support: park and unpark</a></h2>
|
||
<p>Every thread is equipped with some basic low-level blocking support, via the
|
||
<code>park</code> and <code>unpark</code> functions.</p>
|
||
|
||
<p>Conceptually, each <code>Thread</code> handle has an associated token, which is
|
||
initially not present:</p>
|
||
|
||
<ul>
|
||
<li><p>The <code>thread::park()</code> function blocks the current thread unless or until
|
||
the token is available for its thread handle, at which point it atomically
|
||
consumes the token. It may also return <em>spuriously</em>, without consuming the
|
||
token. <code>thread::park_timeout()</code> does the same, but allows specifying a
|
||
maximum time to block the thread for.</p></li>
|
||
<li><p>The <code>unpark()</code> method on a <code>Thread</code> atomically makes the token available
|
||
if it wasn't already.</p></li>
|
||
</ul>
|
||
|
||
<p>In other words, each <code>Thread</code> acts a bit like a semaphore with initial count
|
||
0, except that the semaphore is <em>saturating</em> (the count cannot go above 1),
|
||
and can return spuriously.</p>
|
||
|
||
<p>The API is typically used by acquiring a handle to the current thread,
|
||
placing that handle in a shared data structure so that other threads can
|
||
find it, and then <code>park</code>ing. When some desired condition is met, another
|
||
thread calls <code>unpark</code> on the handle.</p>
|
||
|
||
<p>The motivation for this design is twofold:</p>
|
||
|
||
<ul>
|
||
<li><p>It avoids the need to allocate mutexes and condvars when building new
|
||
synchronization primitives; the threads already provide basic blocking/signaling.</p></li>
|
||
<li><p>It can be implemented very efficiently on many platforms.</p></li>
|
||
</ul>
|
||
|
||
<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 which 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>At a high level, this module provides two variants of storage:</p>
|
||
|
||
<ul>
|
||
<li><p>Owned thread-local storage. This is a type of thread local key which
|
||
owns the value that it contains, and will destroy the value when the
|
||
thread exits. This variant is created with the <code>thread_local!</code> macro and
|
||
can contain any value which is <code>'static</code> (no borrowed pointers).</p></li>
|
||
<li><p>Scoped thread-local storage. This type of key is used to store a reference
|
||
to a value into local storage temporarily for the scope of a function
|
||
call. There are no restrictions on what types of values can be placed
|
||
into this key.</p></li>
|
||
</ul>
|
||
|
||
<p>Both forms of thread local storage provide an accessor function, <code>with</code>,
|
||
which will yield a shared reference to the value to the specified
|
||
closure. Thread-local keys only allow shared access to values as there is no
|
||
way to guarantee uniqueness if a mutable borrow was allowed. Most values
|
||
will want to make use of some form of <strong>interior mutability</strong> through the
|
||
<code>Cell</code> or <code>RefCell</code> 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='bitflags::__core::thread::Builder'>Builder</a></td>
|
||
<td class='docblock short'>
|
||
<p>Thread configuration. Provides detailed control over the properties
|
||
and behavior of new threads.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class='struct' href='struct.JoinHandle.html'
|
||
title='bitflags::__core::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='bitflags::__core::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='bitflags::__core::thread::Thread'>Thread</a></td>
|
||
<td class='docblock short'>
|
||
<p>A handle to a thread.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class='unstable module-item'>
|
||
<td><a class='struct' href='struct.Key.html'
|
||
title='bitflags::__core::thread::Key'>Key</a></td>
|
||
<td class='docblock short'>
|
||
[<em class='stab unstable'>Unstable</em>]
|
||
</td>
|
||
</tr>
|
||
<tr class='unstable module-item'>
|
||
<td><a class='struct' href='struct.Key.html'
|
||
title='bitflags::__core::thread::Key'>Key</a></td>
|
||
<td class='docblock short'>
|
||
[<em class='stab unstable'>Unstable</em>]
|
||
</td>
|
||
</tr>
|
||
<tr class='unstable module-item'>
|
||
<td><a class='struct' href='struct.KeyInner.html'
|
||
title='bitflags::__core::thread::KeyInner'>KeyInner</a></td>
|
||
<td class='docblock short'>
|
||
[<em class='stab unstable'>Unstable</em>]
|
||
</td>
|
||
</tr>
|
||
<tr class='unstable deprecated module-item'>
|
||
<td><a class='struct' href='struct.ScopedKey.html'
|
||
title='bitflags::__core::thread::ScopedKey'>ScopedKey</a></td>
|
||
<td class='docblock short'>
|
||
[<em class='stab deprecated'>Deprecated</em>] [<em class='stab unstable'>Unstable</em>] <p>Type representing a thread local storage key corresponding to a reference
|
||
to the type parameter <code>T</code>.</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='bitflags::__core::thread::LocalKeyState'>LocalKeyState</a></td>
|
||
<td class='docblock short'>
|
||
[<em class='stab unstable'>Unstable</em>] <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='bitflags::__core::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='bitflags::__core::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='bitflags::__core::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='bitflags::__core::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='bitflags::__core::thread::park_timeout_ms'>park_timeout_ms</a></td>
|
||
<td class='docblock short'>
|
||
[<em class='stab deprecated'>Deprecated</em>] <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=' module-item'>
|
||
<td><a class='fn' href='fn.sleep.html'
|
||
title='bitflags::__core::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='bitflags::__core::thread::sleep_ms'>sleep_ms</a></td>
|
||
<td class='docblock short'>
|
||
[<em class='stab deprecated'>Deprecated</em>] <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='bitflags::__core::thread::spawn'>spawn</a></td>
|
||
<td class='docblock short'>
|
||
<p>Spawns a new thread, returning a <code>JoinHandle</code> for it.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class='fn' href='fn.yield_now.html'
|
||
title='bitflags::__core::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='bitflags::__core::thread::Result'>Result</a></td>
|
||
<td class='docblock short'>
|
||
|
||
</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>
|
||
</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> |