Adding large folders

This commit is contained in:
2026-02-26 12:00:21 -05:00
parent 5400d82acd
commit 49701c85ad
47332 changed files with 1942573 additions and 0 deletions

View File

@@ -0,0 +1,11 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="refresh" content="0;URL=../../../../tokio/task/coop/fn.consume_budget.html">
<title>Redirection</title>
</head>
<body>
<p>Redirecting to <a href="../../../../tokio/task/coop/fn.consume_budget.html">../../../../tokio/task/coop/fn.consume_budget.html</a>...</p>
<script>location.replace("../../../../tokio/task/coop/fn.consume_budget.html" + location.search + location.hash);</script>
</body>
</html>

View File

@@ -0,0 +1,18 @@
<!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="Consumes a unit of budget and returns the execution back to the Tokio runtime if the tasks coop budget was exhausted."><title>consume_budget in tokio::task::coop - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-6b053e98.ttf.woff2,FiraSans-Italic-81dc35de.woff2,FiraSans-Regular-0fe48ade.woff2,FiraSans-MediumItalic-ccf7e434.woff2,FiraSans-Medium-e1aa3f0a.woff2,SourceCodePro-Regular-8badfe75.ttf.woff2,SourceCodePro-Semibold-aa29a496.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2"href="../../../static.files/${f}">`).join(""))</script><link rel="stylesheet" href="../../../static.files/normalize-9960930a.css"><link rel="stylesheet" href="../../../static.files/rustdoc-ca0dd0c4.css"><meta name="rustdoc-vars" data-root-path="../../../" data-static-root-path="../../../static.files/" data-current-crate="tokio" data-themes="" data-resource-suffix="" data-rustdoc-version="1.93.1 (01f6ddf75 2026-02-11) (Arch Linux rust 1:1.93.1-1)" data-channel="1.93.1" data-search-js="search-9e2438ea.js" data-stringdex-js="stringdex-a3946164.js" data-settings-js="settings-c38705f0.js" ><script src="../../../static.files/storage-e2aeef58.js"></script><script defer src="sidebar-items.js"></script><script defer src="../../../static.files/main-a410ff4d.js"></script><noscript><link rel="stylesheet" href="../../../static.files/noscript-263c88ec.css"></noscript><link rel="alternate icon" type="image/png" href="../../../static.files/favicon-32x32-eab170b8.png"><link rel="icon" type="image/svg+xml" href="../../../static.files/favicon-044be391.svg"></head><body class="rustdoc fn"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><rustdoc-topbar><h2><a href="#">consume_budget</a></h2></rustdoc-topbar><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../../../tokio/index.html">tokio</a><span class="version">1.49.0</span></h2></div><div class="sidebar-elems"><section id="rustdoc-toc"><h2 class="location"><a href="#">consume_<wbr>budget</a></h2><h3><a href="#">Sections</a></h3><ul class="block top-toc"><li><a href="#examples" title="Examples">Examples</a></li></ul></section><div id="rustdoc-modnav"><h2><a href="index.html">In tokio::<wbr>task::<wbr>coop</a></h2></div></div></nav><div class="sidebar-resizer" title="Drag to resize sidebar"></div><main><div class="width-limiter"><section id="main-content" class="content"><div class="main-heading"><div class="rustdoc-breadcrumbs"><a href="../../index.html">tokio</a>::<wbr><a href="../index.html">task</a>::<wbr><a href="index.html">coop</a></div><h1>Function <span class="fn">consume_<wbr>budget</span>&nbsp;<button id="copy-path" title="Copy item path to clipboard">Copy item path</button></h1><rustdoc-toolbar></rustdoc-toolbar><span class="sub-heading"><a class="src" href="../../../src/tokio/task/coop/consume_budget.rs.html#25-39">Source</a> </span></div><pre class="rust item-decl"><code>pub async fn consume_budget()</code></pre><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>Consumes a unit of budget and returns the execution back to the Tokio
runtime <em>if</em> the tasks coop budget was exhausted.</p>
<p>The task will only yield if its entire coop budget has been exhausted.
This function can be used in order to insert optional yield points into long
computations that do not use Tokio resources like sockets or semaphores,
without redundantly yielding to the runtime each time.</p>
<h2 id="examples"><a class="doc-anchor" href="#examples">§</a>Examples</h2>
<p>Make sure that a function which returns a sum of (potentially lots of)
iterated values is cooperative.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">async fn </span>sum_iterator(input: <span class="kw-2">&amp;mut </span><span class="kw">impl </span>std::iter::Iterator&lt;Item=i64&gt;) -&gt; i64 {
<span class="kw">let </span><span class="kw-2">mut </span>sum: i64 = <span class="number">0</span>;
<span class="kw">while let </span><span class="prelude-val">Some</span>(i) = input.next() {
sum += i;
tokio::task::consume_budget().<span class="kw">await
</span>}
sum
}</code></pre></div></div></details></section></div></main></body></html>

View File

@@ -0,0 +1,26 @@
<!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="Creates a wrapper future that makes the inner future cooperate with the Tokio scheduler."><title>cooperative in tokio::task::coop - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-6b053e98.ttf.woff2,FiraSans-Italic-81dc35de.woff2,FiraSans-Regular-0fe48ade.woff2,FiraSans-MediumItalic-ccf7e434.woff2,FiraSans-Medium-e1aa3f0a.woff2,SourceCodePro-Regular-8badfe75.ttf.woff2,SourceCodePro-Semibold-aa29a496.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2"href="../../../static.files/${f}">`).join(""))</script><link rel="stylesheet" href="../../../static.files/normalize-9960930a.css"><link rel="stylesheet" href="../../../static.files/rustdoc-ca0dd0c4.css"><meta name="rustdoc-vars" data-root-path="../../../" data-static-root-path="../../../static.files/" data-current-crate="tokio" data-themes="" data-resource-suffix="" data-rustdoc-version="1.93.1 (01f6ddf75 2026-02-11) (Arch Linux rust 1:1.93.1-1)" data-channel="1.93.1" data-search-js="search-9e2438ea.js" data-stringdex-js="stringdex-a3946164.js" data-settings-js="settings-c38705f0.js" ><script src="../../../static.files/storage-e2aeef58.js"></script><script defer src="sidebar-items.js"></script><script defer src="../../../static.files/main-a410ff4d.js"></script><noscript><link rel="stylesheet" href="../../../static.files/noscript-263c88ec.css"></noscript><link rel="alternate icon" type="image/png" href="../../../static.files/favicon-32x32-eab170b8.png"><link rel="icon" type="image/svg+xml" href="../../../static.files/favicon-044be391.svg"></head><body class="rustdoc fn"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><rustdoc-topbar><h2><a href="#">cooperative</a></h2></rustdoc-topbar><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../../../tokio/index.html">tokio</a><span class="version">1.49.0</span></h2></div><div class="sidebar-elems"><section id="rustdoc-toc"><h2 class="location"><a href="#">cooperative</a></h2><h3><a href="#">Sections</a></h3><ul class="block top-toc"><li><a href="#examples" title="Examples">Examples</a></li></ul></section><div id="rustdoc-modnav"><h2><a href="index.html">In tokio::<wbr>task::<wbr>coop</a></h2></div></div></nav><div class="sidebar-resizer" title="Drag to resize sidebar"></div><main><div class="width-limiter"><section id="main-content" class="content"><div class="main-heading"><div class="rustdoc-breadcrumbs"><a href="../../index.html">tokio</a>::<wbr><a href="../index.html">task</a>::<wbr><a href="index.html">coop</a></div><h1>Function <span class="fn">cooperative</span>&nbsp;<button id="copy-path" title="Copy item path to clipboard">Copy item path</button></h1><rustdoc-toolbar></rustdoc-toolbar><span class="sub-heading"><a class="src" href="../../../src/tokio/task/coop/mod.rs.html#490-492">Source</a> </span></div><pre class="rust item-decl"><code>pub fn cooperative&lt;F: <a class="trait" href="https://doc.rust-lang.org/1.93.1/core/future/future/trait.Future.html" title="trait core::future::future::Future">Future</a>&gt;(fut: F) -&gt; <a class="struct" href="struct.Coop.html" title="struct tokio::task::coop::Coop">Coop</a>&lt;F&gt; <a href="#" class="tooltip" data-notable-ty="Coop&lt;F&gt;"></a></code></pre><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>Creates a wrapper future that makes the inner future cooperate with the Tokio scheduler.</p>
<p>When polled, the wrapper will first call <a href="fn.poll_proceed.html" title="fn tokio::task::coop::poll_proceed"><code>poll_proceed</code></a> to consume task budget, and
immediately yield if the budget has been depleted. If budget was available, the inner future
is polled. The budget consumption will be made final using <a href="struct.RestoreOnPending.html#method.made_progress" title="method tokio::task::coop::RestoreOnPending::made_progress"><code>RestoreOnPending::made_progress</code></a>
if the inner future resolves to its final value.</p>
<h2 id="examples"><a class="doc-anchor" href="#examples">§</a>Examples</h2>
<p>When you call <code>recv</code> on the <code>Receiver</code> of a <a href="../../sync/mpsc/index.html" title="mod tokio::sync::mpsc"><code>tokio::sync::mpsc</code></a>
channel, task budget will automatically be consumed when the next value is returned.
This makes tasks that use Tokio mpsc channels automatically cooperative.</p>
<p>If youre using <a href="https://docs.rs/futures/latest/futures/channel/mpsc/index.html"><code>futures::channel::mpsc</code></a>
instead, automatic task budget consumption will not happen. This example shows how can use
<code>cooperative</code> to make <code>futures::channel::mpsc</code> channels cooperate with the scheduler in the
same way Tokio channels do.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>tokio::task::coop::cooperative;
<span class="kw">use </span>futures::channel::mpsc::Receiver;
<span class="kw">use </span>futures::stream::StreamExt;
<span class="kw">async fn </span>receive_next&lt;T&gt;(receiver: <span class="kw-2">&amp;mut </span>Receiver&lt;T&gt;) -&gt; <span class="prelude-ty">Option</span>&lt;T&gt; {
<span class="comment">// Use `StreamExt::next` to obtain a `Future` that resolves to the next value
</span><span class="kw">let </span>recv_future = receiver.next();
<span class="comment">// Wrap it a cooperative wrapper
</span><span class="kw">let </span>coop_future = cooperative(recv_future);
<span class="comment">// And await
</span>coop_future.<span class="kw">await
</span>}</code></pre></div></div></details><script type="text/json" id="notable-traits-data">{"Coop<F>":"<h3>Notable traits for <code><a class=\"struct\" href=\"struct.Coop.html\" title=\"struct tokio::task::coop::Coop\">Coop</a>&lt;F&gt;</code></h3><pre><code><div class=\"where\">impl&lt;F: <a class=\"trait\" href=\"https://doc.rust-lang.org/1.93.1/core/future/future/trait.Future.html\" title=\"trait core::future::future::Future\">Future</a>&gt; <a class=\"trait\" href=\"https://doc.rust-lang.org/1.93.1/core/future/future/trait.Future.html\" title=\"trait core::future::future::Future\">Future</a> for <a class=\"struct\" href=\"struct.Coop.html\" title=\"struct tokio::task::coop::Coop\">Coop</a>&lt;F&gt;</div><div class=\"where\"> type <a href=\"https://doc.rust-lang.org/1.93.1/core/future/future/trait.Future.html#associatedtype.Output\" class=\"associatedtype\">Output</a> = F::<a class=\"associatedtype\" href=\"https://doc.rust-lang.org/1.93.1/core/future/future/trait.Future.html#associatedtype.Output\" title=\"type core::future::future::Future::Output\">Output</a>;</div>"}</script></section></div></main></body></html>

View File

@@ -0,0 +1,41 @@
<!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="Returns `true` if there is still budget left on the task."><title>has_budget_remaining in tokio::task::coop - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-6b053e98.ttf.woff2,FiraSans-Italic-81dc35de.woff2,FiraSans-Regular-0fe48ade.woff2,FiraSans-MediumItalic-ccf7e434.woff2,FiraSans-Medium-e1aa3f0a.woff2,SourceCodePro-Regular-8badfe75.ttf.woff2,SourceCodePro-Semibold-aa29a496.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2"href="../../../static.files/${f}">`).join(""))</script><link rel="stylesheet" href="../../../static.files/normalize-9960930a.css"><link rel="stylesheet" href="../../../static.files/rustdoc-ca0dd0c4.css"><meta name="rustdoc-vars" data-root-path="../../../" data-static-root-path="../../../static.files/" data-current-crate="tokio" data-themes="" data-resource-suffix="" data-rustdoc-version="1.93.1 (01f6ddf75 2026-02-11) (Arch Linux rust 1:1.93.1-1)" data-channel="1.93.1" data-search-js="search-9e2438ea.js" data-stringdex-js="stringdex-a3946164.js" data-settings-js="settings-c38705f0.js" ><script src="../../../static.files/storage-e2aeef58.js"></script><script defer src="sidebar-items.js"></script><script defer src="../../../static.files/main-a410ff4d.js"></script><noscript><link rel="stylesheet" href="../../../static.files/noscript-263c88ec.css"></noscript><link rel="alternate icon" type="image/png" href="../../../static.files/favicon-32x32-eab170b8.png"><link rel="icon" type="image/svg+xml" href="../../../static.files/favicon-044be391.svg"></head><body class="rustdoc fn"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><rustdoc-topbar><h2><a href="#">has_budget_remaining</a></h2></rustdoc-topbar><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../../../tokio/index.html">tokio</a><span class="version">1.49.0</span></h2></div><div class="sidebar-elems"><section id="rustdoc-toc"><h2 class="location"><a href="#">has_<wbr>budget_<wbr>remaining</a></h2><h3><a href="#">Sections</a></h3><ul class="block top-toc"><li><a href="#examples" title="Examples">Examples</a></li></ul></section><div id="rustdoc-modnav"><h2><a href="index.html">In tokio::<wbr>task::<wbr>coop</a></h2></div></div></nav><div class="sidebar-resizer" title="Drag to resize sidebar"></div><main><div class="width-limiter"><section id="main-content" class="content"><div class="main-heading"><div class="rustdoc-breadcrumbs"><a href="../../index.html">tokio</a>::<wbr><a href="../index.html">task</a>::<wbr><a href="index.html">coop</a></div><h1>Function <span class="fn">has_<wbr>budget_<wbr>remaining</span>&nbsp;<button id="copy-path" title="Copy item path to clipboard">Copy item path</button></h1><rustdoc-toolbar></rustdoc-toolbar><span class="sub-heading"><a class="src" href="../../../src/tokio/task/coop/mod.rs.html#223-227">Source</a> </span></div><pre class="rust item-decl"><code>pub fn has_budget_remaining() -&gt; <a class="primitive" href="https://doc.rust-lang.org/1.93.1/std/primitive.bool.html">bool</a></code></pre><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>Returns <code>true</code> if there is still budget left on the task.</p>
<h2 id="examples"><a class="doc-anchor" href="#examples">§</a>Examples</h2>
<p>This example defines a <code>Timeout</code> future that requires a given <code>future</code> to complete before the
specified duration elapses. If it does, its result is returned; otherwise, an error is returned
and the future is canceled.</p>
<p>Note that the future could exhaust the budget before we evaluate the timeout. Using <code>has_budget_remaining</code>,
we can detect this scenario and ensure the timeout is always checked.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">pub struct </span>Timeout&lt;T&gt; {
future: T,
delay: Pin&lt;Box&lt;Sleep&gt;&gt;,
}
<span class="kw">impl</span>&lt;T&gt; Future <span class="kw">for </span>Timeout&lt;T&gt;
<span class="kw">where
</span>T: Future + Unpin,
{
<span class="kw">type </span>Output = <span class="prelude-ty">Result</span>&lt;T::Output, ()&gt;;
<span class="kw">fn </span>poll(<span class="self">self</span>: Pin&lt;<span class="kw-2">&amp;mut </span><span class="self">Self</span>&gt;, cx: <span class="kw-2">&amp;mut </span>Context&lt;<span class="lifetime">'_</span>&gt;) -&gt; Poll&lt;<span class="self">Self</span>::Output&gt; {
<span class="kw">let </span>this = Pin::into_inner(<span class="self">self</span>);
<span class="kw">let </span>future = Pin::new(<span class="kw-2">&amp;mut </span>this.future);
<span class="kw">let </span>delay = Pin::new(<span class="kw-2">&amp;mut </span>this.delay);
<span class="comment">// check if the future is ready
</span><span class="kw">let </span>had_budget_before = coop::has_budget_remaining();
<span class="kw">if let </span>Poll::Ready(v) = future.poll(cx) {
<span class="kw">return </span>Poll::Ready(<span class="prelude-val">Ok</span>(v));
}
<span class="kw">let </span>has_budget_now = coop::has_budget_remaining();
<span class="comment">// evaluate the timeout
</span><span class="kw">if let </span>(<span class="bool-val">true</span>, <span class="bool-val">false</span>) = (had_budget_before, has_budget_now) {
<span class="comment">// it is the underlying future that exhausted the budget
</span><span class="macro">ready!</span>(<span class="macro">pin!</span>(coop::unconstrained(delay)).poll(cx));
} <span class="kw">else </span>{
<span class="macro">ready!</span>(delay.poll(cx));
}
<span class="kw">return </span>Poll::Ready(<span class="prelude-val">Err</span>(()));
}
}</code></pre></div></div></details></section></div></main></body></html>

View File

@@ -0,0 +1,45 @@
<!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="Decrements the task budget and returns `Poll::Pending` if the budget is depleted. This indicates that the task should yield to the scheduler. Otherwise, returns `RestoreOnPending` which can be used to commit the budget consumption."><title>poll_proceed in tokio::task::coop - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-6b053e98.ttf.woff2,FiraSans-Italic-81dc35de.woff2,FiraSans-Regular-0fe48ade.woff2,FiraSans-MediumItalic-ccf7e434.woff2,FiraSans-Medium-e1aa3f0a.woff2,SourceCodePro-Regular-8badfe75.ttf.woff2,SourceCodePro-Semibold-aa29a496.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2"href="../../../static.files/${f}">`).join(""))</script><link rel="stylesheet" href="../../../static.files/normalize-9960930a.css"><link rel="stylesheet" href="../../../static.files/rustdoc-ca0dd0c4.css"><meta name="rustdoc-vars" data-root-path="../../../" data-static-root-path="../../../static.files/" data-current-crate="tokio" data-themes="" data-resource-suffix="" data-rustdoc-version="1.93.1 (01f6ddf75 2026-02-11) (Arch Linux rust 1:1.93.1-1)" data-channel="1.93.1" data-search-js="search-9e2438ea.js" data-stringdex-js="stringdex-a3946164.js" data-settings-js="settings-c38705f0.js" ><script src="../../../static.files/storage-e2aeef58.js"></script><script defer src="sidebar-items.js"></script><script defer src="../../../static.files/main-a410ff4d.js"></script><noscript><link rel="stylesheet" href="../../../static.files/noscript-263c88ec.css"></noscript><link rel="alternate icon" type="image/png" href="../../../static.files/favicon-32x32-eab170b8.png"><link rel="icon" type="image/svg+xml" href="../../../static.files/favicon-044be391.svg"></head><body class="rustdoc fn"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><rustdoc-topbar><h2><a href="#">poll_proceed</a></h2></rustdoc-topbar><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../../../tokio/index.html">tokio</a><span class="version">1.49.0</span></h2></div><div class="sidebar-elems"><section id="rustdoc-toc"><h2 class="location"><a href="#">poll_<wbr>proceed</a></h2><h3><a href="#">Sections</a></h3><ul class="block top-toc"><li><a href="#examples" title="Examples">Examples</a></li></ul></section><div id="rustdoc-modnav"><h2><a href="index.html">In tokio::<wbr>task::<wbr>coop</a></h2></div></div></nav><div class="sidebar-resizer" title="Drag to resize sidebar"></div><main><div class="width-limiter"><section id="main-content" class="content"><div class="main-heading"><div class="rustdoc-breadcrumbs"><a href="../../index.html">tokio</a>::<wbr><a href="../index.html">task</a>::<wbr><a href="index.html">coop</a></div><h1>Function <span class="fn">poll_<wbr>proceed</span>&nbsp;<button id="copy-path" title="Copy item path to clipboard">Copy item path</button></h1><rustdoc-toolbar></rustdoc-toolbar><span class="sub-heading"><a class="src" href="../../../src/tokio/task/coop/mod.rs.html#343-364">Source</a> </span></div><pre class="rust item-decl"><code>pub fn poll_proceed(cx: &amp;mut <a class="struct" href="https://doc.rust-lang.org/1.93.1/core/task/wake/struct.Context.html" title="struct core::task::wake::Context">Context</a>&lt;'_&gt;) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.93.1/core/task/poll/enum.Poll.html" title="enum core::task::poll::Poll">Poll</a>&lt;<a class="struct" href="struct.RestoreOnPending.html" title="struct tokio::task::coop::RestoreOnPending">RestoreOnPending</a>&gt;</code></pre><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>Decrements the task budget and returns <a href="https://doc.rust-lang.org/1.93.1/core/task/poll/enum.Poll.html#variant.Pending" title="variant core::task::poll::Poll::Pending"><code>Poll::Pending</code></a> if the budget is depleted.
This indicates that the task should yield to the scheduler. Otherwise, returns
<a href="struct.RestoreOnPending.html" title="struct tokio::task::coop::RestoreOnPending"><code>RestoreOnPending</code></a> which can be used to commit the budget consumption.</p>
<p>The returned <a href="struct.RestoreOnPending.html" title="struct tokio::task::coop::RestoreOnPending"><code>RestoreOnPending</code></a> will revert the budget to its former
value when dropped unless <a href="struct.RestoreOnPending.html#method.made_progress" title="method tokio::task::coop::RestoreOnPending::made_progress"><code>RestoreOnPending::made_progress</code></a>
is called. It is the callers responsibility to do so when it <em>was</em> able to
make progress after the call to <a href="fn.poll_proceed.html" title="fn tokio::task::coop::poll_proceed"><code>poll_proceed</code></a>.
Restoring the budget automatically ensures the task can try to make progress in some other
way.</p>
<p>Note that <a href="struct.RestoreOnPending.html" title="struct tokio::task::coop::RestoreOnPending"><code>RestoreOnPending</code></a> restores the budget <strong>as it was before <a href="fn.poll_proceed.html" title="fn tokio::task::coop::poll_proceed"><code>poll_proceed</code></a></strong>.
Therefore, if the budget is <em>further</em> adjusted between when <a href="fn.poll_proceed.html" title="fn tokio::task::coop::poll_proceed"><code>poll_proceed</code></a> returns and
<a href="struct.RestoreOnPending.html" title="struct tokio::task::coop::RestoreOnPending"><code>RestoreOnPending</code></a> is dropped, those adjustments are erased unless the caller indicates
that progress was made.</p>
<h2 id="examples"><a class="doc-anchor" href="#examples">§</a>Examples</h2>
<p>This example wraps the <code>futures::channel::mpsc::UnboundedReceiver</code> to
cooperate with the Tokio scheduler. Each time a value is received, task budget
is consumed. If no budget is available, the task yields to the scheduler.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>std::pin::Pin;
<span class="kw">use </span>std::task::{ready, Context, Poll};
<span class="kw">use </span>tokio::task::coop;
<span class="kw">use </span>futures::stream::{Stream, StreamExt};
<span class="kw">use </span>futures::channel::mpsc::UnboundedReceiver;
<span class="kw">struct </span>CoopUnboundedReceiver&lt;T&gt; {
receiver: UnboundedReceiver&lt;T&gt;,
}
<span class="kw">impl</span>&lt;T&gt; Stream <span class="kw">for </span>CoopUnboundedReceiver&lt;T&gt; {
<span class="kw">type </span>Item = T;
<span class="kw">fn </span>poll_next(
<span class="kw-2">mut </span><span class="self">self</span>: Pin&lt;<span class="kw-2">&amp;mut </span><span class="self">Self</span>&gt;,
cx: <span class="kw-2">&amp;mut </span>Context&lt;<span class="lifetime">'_</span>&gt;
) -&gt; Poll&lt;<span class="prelude-ty">Option</span>&lt;T&gt;&gt; {
<span class="kw">let </span>coop = <span class="macro">ready!</span>(coop::poll_proceed(cx));
<span class="kw">match </span><span class="self">self</span>.receiver.poll_next_unpin(cx) {
Poll::Ready(v) =&gt; {
<span class="comment">// We received a value, so consume budget.
</span>coop.made_progress();
Poll::Ready(v)
}
Poll::Pending =&gt; Poll::Pending,
}
}
}</code></pre></div></div></details></section></div></main></body></html>

View File

@@ -0,0 +1,5 @@
<!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="Turn off cooperative scheduling for a future. The future will never be forced to yield by Tokio. Using this exposes your service to starvation if the unconstrained future never yields otherwise."><title>unconstrained in tokio::task::coop - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-6b053e98.ttf.woff2,FiraSans-Italic-81dc35de.woff2,FiraSans-Regular-0fe48ade.woff2,FiraSans-MediumItalic-ccf7e434.woff2,FiraSans-Medium-e1aa3f0a.woff2,SourceCodePro-Regular-8badfe75.ttf.woff2,SourceCodePro-Semibold-aa29a496.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2"href="../../../static.files/${f}">`).join(""))</script><link rel="stylesheet" href="../../../static.files/normalize-9960930a.css"><link rel="stylesheet" href="../../../static.files/rustdoc-ca0dd0c4.css"><meta name="rustdoc-vars" data-root-path="../../../" data-static-root-path="../../../static.files/" data-current-crate="tokio" data-themes="" data-resource-suffix="" data-rustdoc-version="1.93.1 (01f6ddf75 2026-02-11) (Arch Linux rust 1:1.93.1-1)" data-channel="1.93.1" data-search-js="search-9e2438ea.js" data-stringdex-js="stringdex-a3946164.js" data-settings-js="settings-c38705f0.js" ><script src="../../../static.files/storage-e2aeef58.js"></script><script defer src="sidebar-items.js"></script><script defer src="../../../static.files/main-a410ff4d.js"></script><noscript><link rel="stylesheet" href="../../../static.files/noscript-263c88ec.css"></noscript><link rel="alternate icon" type="image/png" href="../../../static.files/favicon-32x32-eab170b8.png"><link rel="icon" type="image/svg+xml" href="../../../static.files/favicon-044be391.svg"></head><body class="rustdoc fn"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><rustdoc-topbar><h2><a href="#">unconstrained</a></h2></rustdoc-topbar><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../../../tokio/index.html">tokio</a><span class="version">1.49.0</span></h2></div><div class="sidebar-elems"><div id="rustdoc-modnav"><h2><a href="index.html">In tokio::<wbr>task::<wbr>coop</a></h2></div></div></nav><div class="sidebar-resizer" title="Drag to resize sidebar"></div><main><div class="width-limiter"><section id="main-content" class="content"><div class="main-heading"><div class="rustdoc-breadcrumbs"><a href="../../index.html">tokio</a>::<wbr><a href="../index.html">task</a>::<wbr><a href="index.html">coop</a></div><h1>Function <span class="fn">unconstrained</span>&nbsp;<button id="copy-path" title="Copy item path to clipboard">Copy item path</button></h1><rustdoc-toolbar></rustdoc-toolbar><span class="sub-heading"><a class="src" href="../../../src/tokio/task/coop/unconstrained.rs.html#43-45">Source</a> </span></div><pre class="rust item-decl"><code>pub fn unconstrained&lt;F&gt;(inner: F) -&gt; <a class="struct" href="struct.Unconstrained.html" title="struct tokio::task::coop::Unconstrained">Unconstrained</a>&lt;F&gt; <a href="#" class="tooltip" data-notable-ty="Unconstrained&lt;F&gt;"></a></code></pre><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>Turn off cooperative scheduling for a future. The future will never be forced to yield by
Tokio. Using this exposes your service to starvation if the unconstrained future never yields
otherwise.</p>
<p>See also the usage example in the <a href="index.html#unconstrained">task module</a>.</p>
</div></details><script type="text/json" id="notable-traits-data">{"Unconstrained<F>":"<h3>Notable traits for <code><a class=\"struct\" href=\"struct.Unconstrained.html\" title=\"struct tokio::task::coop::Unconstrained\">Unconstrained</a>&lt;F&gt;</code></h3><pre><code><div class=\"where\">impl&lt;F&gt; <a class=\"trait\" href=\"https://doc.rust-lang.org/1.93.1/core/future/future/trait.Future.html\" title=\"trait core::future::future::Future\">Future</a> for <a class=\"struct\" href=\"struct.Unconstrained.html\" title=\"struct tokio::task::coop::Unconstrained\">Unconstrained</a>&lt;F&gt;<div class=\"where\">where\n F: <a class=\"trait\" href=\"https://doc.rust-lang.org/1.93.1/core/future/future/trait.Future.html\" title=\"trait core::future::future::Future\">Future</a>,</div></div><div class=\"where\"> type <a href=\"https://doc.rust-lang.org/1.93.1/core/future/future/trait.Future.html#associatedtype.Output\" class=\"associatedtype\">Output</a> = &lt;F as <a class=\"trait\" href=\"https://doc.rust-lang.org/1.93.1/core/future/future/trait.Future.html\" title=\"trait core::future::future::Future\">Future</a>&gt;::<a class=\"associatedtype\" href=\"https://doc.rust-lang.org/1.93.1/core/future/future/trait.Future.html#associatedtype.Output\" title=\"type core::future::future::Future::Output\">Output</a>;</div>"}</script></section></div></main></body></html>

View File

@@ -0,0 +1,43 @@
<!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="Utilities for improved cooperative scheduling."><title>tokio::task::coop - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-6b053e98.ttf.woff2,FiraSans-Italic-81dc35de.woff2,FiraSans-Regular-0fe48ade.woff2,FiraSans-MediumItalic-ccf7e434.woff2,FiraSans-Medium-e1aa3f0a.woff2,SourceCodePro-Regular-8badfe75.ttf.woff2,SourceCodePro-Semibold-aa29a496.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2"href="../../../static.files/${f}">`).join(""))</script><link rel="stylesheet" href="../../../static.files/normalize-9960930a.css"><link rel="stylesheet" href="../../../static.files/rustdoc-ca0dd0c4.css"><meta name="rustdoc-vars" data-root-path="../../../" data-static-root-path="../../../static.files/" data-current-crate="tokio" data-themes="" data-resource-suffix="" data-rustdoc-version="1.93.1 (01f6ddf75 2026-02-11) (Arch Linux rust 1:1.93.1-1)" data-channel="1.93.1" data-search-js="search-9e2438ea.js" data-stringdex-js="stringdex-a3946164.js" data-settings-js="settings-c38705f0.js" ><script src="../../../static.files/storage-e2aeef58.js"></script><script defer src="../sidebar-items.js"></script><script defer src="../../../static.files/main-a410ff4d.js"></script><noscript><link rel="stylesheet" href="../../../static.files/noscript-263c88ec.css"></noscript><link rel="alternate icon" type="image/png" href="../../../static.files/favicon-32x32-eab170b8.png"><link rel="icon" type="image/svg+xml" href="../../../static.files/favicon-044be391.svg"></head><body class="rustdoc mod"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><rustdoc-topbar><h2><a href="#">Module coop</a></h2></rustdoc-topbar><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../../../tokio/index.html">tokio</a><span class="version">1.49.0</span></h2></div><div class="sidebar-elems"><section id="rustdoc-toc"><h2 class="location"><a href="#">Module coop</a></h2><h3><a href="#">Sections</a></h3><ul class="block top-toc"><li><a href="#cooperative-scheduling" title="Cooperative scheduling">Cooperative scheduling</a><ul><li><a href="#unconstrained" title="unconstrained">unconstrained</a></li></ul></li></ul><h3><a href="#structs">Module Items</a></h3><ul class="block"><li><a href="#structs" title="Structs">Structs</a></li><li><a href="#functions" title="Functions">Functions</a></li></ul></section><div id="rustdoc-modnav"><h2><a href="../index.html">In tokio::<wbr>task</a></h2></div></div></nav><div class="sidebar-resizer" title="Drag to resize sidebar"></div><main><div class="width-limiter"><section id="main-content" class="content"><div class="main-heading"><div class="rustdoc-breadcrumbs"><a href="../../index.html">tokio</a>::<wbr><a href="../index.html">task</a></div><h1>Module <span>coop</span>&nbsp;<button id="copy-path" title="Copy item path to clipboard">Copy item path</button></h1><rustdoc-toolbar></rustdoc-toolbar><span class="sub-heading"><a class="src" href="../../../src/tokio/task/coop/mod.rs.html#1-573">Source</a> </span></div><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>Utilities for improved cooperative scheduling.</p>
<h4 id="cooperative-scheduling"><a class="doc-anchor" href="#cooperative-scheduling">§</a>Cooperative scheduling</h4>
<p>A single call to <a href="https://doc.rust-lang.org/1.93.1/core/future/future/trait.Future.html#tymethod.poll" title="method core::future::future::Future::poll"><code>poll</code></a> on a top-level task may potentially do a lot of
work before it returns <code>Poll::Pending</code>. If a task runs for a long period of
time without yielding back to the executor, it can starve other tasks
waiting on that executor to execute them, or drive underlying resources.
Since Rust does not have a runtime, it is difficult to forcibly preempt a
long-running task. Instead, this module provides an opt-in mechanism for
futures to collaborate with the executor to avoid starvation.</p>
<p>Consider a future like this one:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">async fn </span>drop_all&lt;I: Stream + Unpin&gt;(<span class="kw-2">mut </span>input: I) {
<span class="kw">while let </span><span class="prelude-val">Some</span>(<span class="kw">_</span>) = input.next().<span class="kw">await </span>{}
}</code></pre></div>
<p>It may look harmless, but consider what happens under heavy load if the
input stream is <em>always</em> ready. If we spawn <code>drop_all</code>, the task will never
yield, and will starve other tasks and resources on the same executor.</p>
<p>To account for this, Tokio has explicit yield points in a number of library
functions, which force tasks to return to the executor periodically.</p>
<h5 id="unconstrained"><a class="doc-anchor" href="#unconstrained">§</a>unconstrained</h5>
<p>If necessary, <a href="fn.unconstrained.html" title="fn tokio::task::coop::unconstrained"><code>task::unconstrained</code></a> lets you opt a future out of Tokios cooperative
scheduling. When a future is wrapped with <code>unconstrained</code>, it will never be forced to yield to
Tokio. For example:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>tokio::{task, sync::mpsc};
<span class="kw">let </span>fut = <span class="kw">async </span>{
<span class="kw">let </span>(tx, <span class="kw-2">mut </span>rx) = mpsc::unbounded_channel();
<span class="kw">for </span>i <span class="kw">in </span><span class="number">0</span>..<span class="number">1000 </span>{
<span class="kw">let _ </span>= tx.send(());
<span class="comment">// This will always be ready. If coop was in effect, this code would be forced to yield
// periodically. However, if left unconstrained, then this code will never yield.
</span>rx.recv().<span class="kw">await</span>;
}
};
task::coop::unconstrained(fut).<span class="kw">await</span>;</code></pre></div></div></details><h2 id="structs" class="section-header">Structs<a href="#structs" class="anchor">§</a></h2><dl class="item-table"><dt><a class="struct" href="struct.Coop.html" title="struct tokio::task::coop::Coop">Coop</a></dt><dd>Future wrapper to ensure cooperative scheduling created by <a href="fn.cooperative.html" title="fn tokio::task::coop::cooperative"><code>cooperative</code></a>.</dd><dt><a class="struct" href="struct.RestoreOnPending.html" title="struct tokio::task::coop::RestoreOnPending">Restore<wbr>OnPending</a></dt><dd>Value returned by the <a href="fn.poll_proceed.html" title="fn tokio::task::coop::poll_proceed"><code>poll_proceed</code></a> method.</dd><dt><a class="struct" href="struct.Unconstrained.html" title="struct tokio::task::coop::Unconstrained">Unconstrained</a></dt><dd>Future for the <a href="fn.unconstrained.html" title="fn tokio::task::coop::unconstrained"><code>unconstrained</code></a> method.</dd></dl><h2 id="functions" class="section-header">Functions<a href="#functions" class="anchor">§</a></h2><dl class="item-table"><dt><a class="fn" href="fn.consume_budget.html" title="fn tokio::task::coop::consume_budget">consume_<wbr>budget</a></dt><dd>Consumes a unit of budget and returns the execution back to the Tokio
runtime <em>if</em> the tasks coop budget was exhausted.</dd><dt><a class="fn" href="fn.cooperative.html" title="fn tokio::task::coop::cooperative">cooperative</a></dt><dd>Creates a wrapper future that makes the inner future cooperate with the Tokio scheduler.</dd><dt><a class="fn" href="fn.has_budget_remaining.html" title="fn tokio::task::coop::has_budget_remaining">has_<wbr>budget_<wbr>remaining</a></dt><dd>Returns <code>true</code> if there is still budget left on the task.</dd><dt><a class="fn" href="fn.poll_proceed.html" title="fn tokio::task::coop::poll_proceed">poll_<wbr>proceed</a></dt><dd>Decrements the task budget and returns <a href="https://doc.rust-lang.org/1.93.1/core/task/poll/enum.Poll.html#variant.Pending" title="variant core::task::poll::Poll::Pending"><code>Poll::Pending</code></a> if the budget is depleted.
This indicates that the task should yield to the scheduler. Otherwise, returns
<a href="struct.RestoreOnPending.html" title="struct tokio::task::coop::RestoreOnPending"><code>RestoreOnPending</code></a> which can be used to commit the budget consumption.</dd><dt><a class="fn" href="fn.unconstrained.html" title="fn tokio::task::coop::unconstrained">unconstrained</a></dt><dd>Turn off cooperative scheduling for a future. The future will never be forced to yield by
Tokio. Using this exposes your service to starvation if the unconstrained future never yields
otherwise.</dd></dl></section></div></main></body></html>

View File

@@ -0,0 +1 @@
window.SIDEBAR_ITEMS = {"fn":["consume_budget","cooperative","has_budget_remaining","poll_proceed","unconstrained"],"struct":["Coop","RestoreOnPending","Unconstrained"]};

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

View File

@@ -0,0 +1,11 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="refresh" content="0;URL=../../../../tokio/task/coop/fn.unconstrained.html">
<title>Redirection</title>
</head>
<body>
<p>Redirecting to <a href="../../../../tokio/task/coop/fn.unconstrained.html">../../../../tokio/task/coop/fn.unconstrained.html</a>...</p>
<script>location.replace("../../../../tokio/task/coop/fn.unconstrained.html" + location.search + location.hash);</script>
</body>
</html>

View File

@@ -0,0 +1,11 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="refresh" content="0;URL=../../../../tokio/task/coop/struct.Unconstrained.html">
<title>Redirection</title>
</head>
<body>
<p>Redirecting to <a href="../../../../tokio/task/coop/struct.Unconstrained.html">../../../../tokio/task/coop/struct.Unconstrained.html</a>...</p>
<script>location.replace("../../../../tokio/task/coop/struct.Unconstrained.html" + location.search + location.hash);</script>
</body>
</html>