mentat/tokio/executor/thread_pool/index.html
2018-08-22 17:04:13 +00:00

207 lines
No EOL
10 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!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_pool` mod in crate `tokio`.">
<meta name="keywords" content="rust, rustlang, rust-lang, thread_pool">
<title>tokio::executor::thread_pool - 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="../../../main.css" id="themeStyle">
<script src="../../../storage.js"></script>
</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">
<div class="sidebar-menu">&#9776;</div>
<p class='location'>Module thread_pool</p><div class="sidebar-elems"><div class="block items"><ul><li><a href="#structs">Structs</a></li></ul></div><p class='location'><a href='../../index.html'>tokio</a>::<wbr><a href='../index.html'>executor</a></p><script>window.sidebarCurrent = {name: 'thread_pool', ty: 'mod', 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">
</div>
</form>
</nav>
<section id='main' class="content">
<h1 class='fqn'><span class='in-band'>Module <a href='../../index.html'>tokio</a>::<wbr><a href='../index.html'>executor</a>::<wbr><a class="mod" href=''>thread_pool</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'>&#x2212;</span>]
</a>
</span><a class='srclink' href='../../../src/tokio/executor/mod.rs.html#54-132' title='goto source code'>[src]</a></span></h1>
<div class='docblock'><p>Maintains a pool of threads across which the set of spawned tasks are
executed.</p>
<p><a href="struct.ThreadPool.html"><code>ThreadPool</code></a> is an executor that uses a thread pool for executing
tasks concurrently across multiple cores. It uses a thread pool that is
optimized for use cases that involve multiplexing large number of
independent tasks that perform short(ish) amounts of computation and are
mainly waiting on I/O, i.e. the Tokio use case.</p>
<p>Usually, users of <a href="struct.ThreadPool.html"><code>ThreadPool</code></a> will not create pool instances.
Instead, they will create a <a href="../../runtime/struct.Runtime.html"><code>Runtime</code></a> instance, which comes with a
pre-configured thread pool.</p>
<p>At the core, <a href="struct.ThreadPool.html"><code>ThreadPool</code></a> uses a work-stealing based scheduling
strategy. When spawning a task while <em>external</em> to the thread pool
(i.e., from a thread that is not part of the thread pool), the task is
randomly assigned to a worker thread. When spawning a task while
<em>internal</em> to the thread pool, the task is assigned to the current
worker.</p>
<p>Each worker maintains its own queue and first focuses on processing all
tasks in its queue. When the worker's queue is empty, the worker will
attempt to <em>steal</em> tasks from other worker queues. This strategy helps
ensure that work is evenly distributed across threads while minimizing
synchronization between worker threads.</p>
<h1 id="usage" class="section-header"><a href="#usage">Usage</a></h1>
<p>Thread pool instances are created using <a href="struct.ThreadPool.html#method.new"><code>ThreadPool::new</code></a> or
<a href="struct.Builder.html#method.new"><code>Builder::new</code></a>. The first option returns a thread pool with default
configuration values. The second option allows configuring the thread
pool before instantiating it.</p>
<p>Once an instance is obtained, futures may be spawned onto it using the
<a href="struct.ThreadPool.html#method.spawn"><code>spawn</code></a> function.</p>
<p>A handle to the thread pool is obtained using <a href="struct.ThreadPool.html#method.sender"><code>ThreadPool::sender</code></a>.
This handle is <strong>only</strong> able to spawn futures onto the thread pool. It
is unable to affect the lifecycle of the thread pool in any way. This
handle can be passed into functions or stored in structs as a way to
grant the capability of spawning futures.</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">futures</span>::<span class="ident">future</span>::{<span class="ident">Future</span>, <span class="ident">lazy</span>};
<span class="comment">// Create a thread pool with default configuration values</span>
<span class="kw">let</span> <span class="ident">thread_pool</span> <span class="op">=</span> <span class="ident">ThreadPool</span>::<span class="ident">new</span>();
<span class="ident">thread_pool</span>.<span class="ident">spawn</span>(<span class="ident">lazy</span>(<span class="op">||</span> {
<span class="macro">println</span><span class="macro">!</span>(<span class="string">&quot;called from a worker thread&quot;</span>);
<span class="prelude-val">Ok</span>(())
}));
<span class="comment">// Gracefully shutdown the threadpool</span>
<span class="ident">thread_pool</span>.<span class="ident">shutdown</span>().<span class="ident">wait</span>().<span class="ident">unwrap</span>();</pre>
</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 tokio::executor::thread_pool::Builder'>Builder</a></td>
<td class='docblock-short'>
<p>Builds a thread pool with custom configuration values.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.Sender.html"
title='struct tokio::executor::thread_pool::Sender'>Sender</a></td>
<td class='docblock-short'>
<p>Submit futures to the associated thread pool for execution.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.Shutdown.html"
title='struct tokio::executor::thread_pool::Shutdown'>Shutdown</a></td>
<td class='docblock-short'>
<p>Future that resolves when the thread pool is shutdown.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.ThreadPool.html"
title='struct tokio::executor::thread_pool::ThreadPool'>ThreadPool</a></td>
<td class='docblock-short'>
<p>Work-stealing based thread pool for executing futures.</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><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>&#9166;</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>
</div>
</div>
</aside>
<script>
window.rootPath = "../../../";
window.currentCrate = "tokio";
</script>
<script src="../../../main.js"></script>
<script defer src="../../../search-index.js"></script>
</body>
</html>