mentat/futures/task/struct.Task.html

204 lines
15 KiB
HTML
Raw Normal View History

2018-08-22 17:04:13 +00:00
<!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 `Task` struct in crate `futures`.">
<meta name="keywords" content="rust, rustlang, rust-lang, Task">
<title>futures::task::Task - 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 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">&#9776;</div>
<p class='location'>Struct Task</p><div class="sidebar-elems"><div class="block items"><a class="sidebar-title" href="#methods">Methods</a><div class="sidebar-links"><a href="#method.notify">notify</a><a href="#method.is_current">is_current</a><a href="#method.will_notify_current">will_notify_current</a></div><a class="sidebar-title" href="#implementations">Trait Implementations</a><div class="sidebar-links"><a href="#impl-Clone">Clone</a><a href="#impl-Debug">Debug</a></div></div><p class='location'><a href='../index.html'>futures</a>::<wbr><a href='index.html'>task</a></p><script>window.sidebarCurrent = {name: 'Task', 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">
</div>
</form>
</nav>
<section id='main' class="content">
<h1 class='fqn'><span class='in-band'>Struct <a href='../index.html'>futures</a>::<wbr><a href='index.html'>task</a>::<wbr><a class="struct" href=''>Task</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/futures/task_impl/mod.rs.html#58-62' title='goto source code'>[src]</a></span></h1>
<pre class='rust struct'>pub struct Task { /* fields omitted */ }</pre><div class='docblock'><p>A handle to a &quot;task&quot;, which represents a single lightweight &quot;thread&quot; of
execution driving a future to completion.</p>
<p>In general, futures are composed into large units of work, which are then
spawned as tasks onto an <em>executor</em>. The executor is responsible for polling
the future as notifications arrive, until the future terminates.</p>
<p>This is obtained by the <code>task::current</code> function.</p>
</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'><code>impl <a class="struct" href="../../futures/task/struct.Task.html" title="struct futures::task::Task">Task</a></code><a href='#impl' class='anchor'></a></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/futures/task_impl/mod.rs.html#108-194' title='goto source code'>[src]</a></span></h3>
<div class='impl-items'><h4 id='method.notify' class="method"><span id='notify.v' class='invisible'><code>pub fn <a href='#method.notify' class='fnname'>notify</a>(&amp;self)</code></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/futures/task_impl/mod.rs.html#117-120' title='goto source code'>[src]</a></span></h4>
<div class='docblock'><p>Indicate that the task should attempt to poll its future in a timely
fashion.</p>
<p>It's typically guaranteed that, after calling <code>notify</code>, <code>poll</code> will
be called at least once subsequently (unless the future has terminated).
If the task is currently polling its future when <code>notify</code> is called, it
must poll the future <em>again</em> afterwards, ensuring that all relevant
events are eventually observed by the future.</p>
</div><h4 id='method.is_current' class="method"><span id='is_current.v' class='invisible'><code>pub fn <a href='#method.is_current' class='fnname'>is_current</a>(&amp;self) -&gt; <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.bool.html">bool</a></code></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/futures/task_impl/mod.rs.html#165-167' title='goto source code'>[src]</a></span></h4>
<div class='stability'><div class='stab deprecated'>Deprecated<p>: intended to be removed, see docs for details</p>
</div></div><div class='docblock'><p>Returns <code>true</code> when called from within the context of the task.</p>
<p>In other words, the task is currently running on the thread calling the
function. Note that this is currently, and has historically, been
implemented by tracking an <code>id</code> on every instance of <code>Spawn</code> created.
When a <code>Spawn</code> is being polled it stores in thread-local-storage the id
of the instance, and then <code>task::current</code> will return a <code>Task</code> that also
stores this id.</p>
<p>The intention of this function was to answer questions like &quot;if I
<code>notify</code> this task, is it equivalent to <code>task::current().notify()</code>?&quot;
The answer &quot;yes&quot; may be able to avoid some extra work to block the
current task, such as sending a task along a channel or updating a
stored <code>Task</code> somewhere. An answer of &quot;no&quot; typically results in doing
the work anyway.</p>
<p>Unfortunately this function has been somewhat buggy in the past and is
not intended to be supported in the future. By simply matching <code>id</code> the
intended question above isn't accurately taking into account, for
example, unpark events (now deprecated, but still a feature). Thus many
old users of this API weren't fully accounting for the question it was
intended they were asking.</p>
<p>This API continues to be implemented but will in the future, e.g. in the
0.1.x series of this crate, eventually return <code>false</code> unconditionally.
It is intended that this function will be removed in the next breaking
change of this crate. If you'd like to continue to be able to answer the
example question above, it's recommended you use the
<code>will_notify_current</code> method.</p>
<p>If you've got questions about this though please let us know! We'd like
to learn about other use cases here that we did not consider.</p>
<h1 id="panics" class="section-header"><a href="#panics">Panics</a></h1>
<p>This function will panic if no current future is being polled.</p>
</div><h4 id='method.will_notify_current' class="method"><span id='will_notify_current.v' class='invisible'><code>pub fn <a href='#method.will_notify_current' class='fnname'>will_notify_current</a>(&amp;self) -&gt; <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.bool.html">bool</a></code></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/futures/task_impl/mod.rs.html#188-193' title='goto source code'>[src]</a></span></h4>
<div class='docblock'><p>This function is intended as a performance optimization for structures
which store a <code>Task</code> internally.</p>
<p>The purpose of this function is to answer the question &quot;if I <code>notify</code>
this task is it equivalent to <code>task::current().notify()</code>&quot;. An answer
&quot;yes&quot; may mean that you don't actually need to call <code>task::current()</code>
and store it, but rather you can simply leave a stored task in place. An
answer of &quot;no&quot; typically means that you need to call <code>task::current()</code>
and store it somewhere.</p>
<p>As this is purely a performance optimization a valid implementation for
this function is to always return <code>false</code>. A best effort is done to
return <code>true</code> where possible, but false negatives may happen. Note that
this function will not return a false positive, however.</p>
<h1 id="panics-1" class="section-header"><a href="#panics-1">Panics</a></h1>
<p>This function will panic if no current future is being polled.</p>
</div></div>
<h2 id='implementations' class='small-section-header'>
Trait Implementations<a href='#implementations' class='anchor'></a>
</h2>
<h3 id='impl-Clone' class='impl'><span class='in-band'><code>impl <a class="trait" href="https://doc.rust-lang.org/nightly/core/clone/trait.Clone.html" title="trait core::clone::Clone">Clone</a> for <a class="struct" href="../../futures/task/struct.Task.html" title="struct futures::task::Task">Task</a></code><a href='#impl-Clone' class='anchor'></a></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/futures/task_impl/mod.rs.html#57' title='goto source code'>[src]</a></span></h3>
<div class='impl-items'><h4 id='method.clone' class="method"><span id='clone.v' class='invisible'><code>fn <a href='https://doc.rust-lang.org/nightly/core/clone/trait.Clone.html#tymethod.clone' class='fnname'>clone</a>(&amp;self) -&gt; <a class="struct" href="../../futures/task/struct.Task.html" title="struct futures::task::Task">Task</a></code></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/futures/task_impl/mod.rs.html#57' title='goto source code'>[src]</a></span></h4>
<div class='docblock'><p>Returns a copy of the value. <a href="https://doc.rust-lang.org/nightly/core/clone/trait.Clone.html#tymethod.clone">Read more</a></p>
</div><h4 id='method.clone_from' class="method"><span id='clone_from.v' class='invisible'><code>fn <a href='https://doc.rust-lang.org/nightly/core/clone/trait.Clone.html#method.clone_from' class='fnname'>clone_from</a>(&amp;mut self, source: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&amp;</a>Self)</code></span><span class='out-of-band'><div class='ghost'></div><div class='since' title='Stable since Rust version 1.0.0'>1.0.0</div><a class='srclink' href='https://doc.rust-lang.org/nightly/src/core/clone.rs.html#112-114' title='goto source code'>[src]</a></span></h4>
<div class='docblock'><p>Performs copy-assignment from <code>source</code>. <a href="https://doc.rust-lang.org/nightly/core/clone/trait.Clone.html#method.clone_from">Read more</a></p>
</div></div><h3 id='impl-Debug' class='impl'><span class='in-band'><code>impl <a class="trait" href="https://doc.rust-lang.org/nightly/core/fmt/trait.Debug.html" title="trait core::fmt::Debug">Debug</a> for <a class="struct" href="../../futures/task/struct.Task.html" title="struct futures::task::Task">Task</a></code><a href='#impl-Debug' class='anchor'></a></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/futures/task_impl/mod.rs.html#196-201' title='goto source code'>[src]</a></span></h3>
<div class='impl-items'><h4 id='method.fmt' class="method"><span id='fmt.v' class='invisible'><code>fn <a href='https://doc.rust-lang.org/nightly/core/fmt/trait.Debug.html#tymethod.fmt' class='fnname'>fmt</a>(&amp;self, f: &amp;mut <a class="struct" href="https://doc.rust-lang.org/nightly/core/fmt/struct.Formatter.html" title="struct core::fmt::Formatter">Formatter</a>) -&gt; <a class="type" href="https://doc.rust-lang.org/nightly/core/fmt/type.Result.html" title="type core::fmt::Result">Result</a></code></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/futures/task_impl/mod.rs.html#197-200' title='goto source code'>[src]</a></span></h4>
<div class='docblock'><p>Formats the value using the given formatter. <a href="https://doc.rust-lang.org/nightly/core/fmt/trait.Debug.html#tymethod.fmt">Read more</a></p>
</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>&#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 = "futures";
</script>
<script src="../../main.js"></script>
<script defer src="../../search-index.js"></script>
</body>
</html>