KA-DEVS/mcquery-rs
5
0
Fork 0
Code Issues Pull Requests Releases Activity
b89c52748d
mcquery-rs/doc/tokio/macro.select.html

279 lines
36 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 `select` macro in crate `tokio`."><meta name="keywords" content="rust, rustlang, rust-lang, select"><title>tokio::select - 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="../light.css" id="themeStyle"><link rel="stylesheet" type="text/css" href="../dark.css" disabled ><link rel="stylesheet" type="text/css" href="../ayu.css" disabled ><script id="default-settings"></script><script src="../storage.js"></script><noscript><link rel="stylesheet" href="../noscript.css"></noscript><link rel="icon" type="image/svg+xml" href="../favicon.svg">
<link rel="alternate icon" type="image/png" href="../favicon-16x16.png">
<link rel="alternate icon" type="image/png" href="../favicon-32x32.png"><style type="text/css">#crate-search{background-image:url("../down-arrow.svg");}</style></head><body class="rustdoc macro"><!--[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><a href='../tokio/index.html'><div class='logo-container rust-logo'><img src='../rust-logo.png' alt='logo'></div></a><div class="sidebar-elems"><p class="location"><a href="index.html">tokio</a></p><script>window.sidebarCurrent = {name: "select", ty: "macro", relpath: ""};</script><script defer src="sidebar-items.js"></script></div></nav><div class="theme-picker"><button id="theme-picker" aria-label="Pick another theme!" aria-haspopup="menu"><img src="../brush.svg" width="18" alt="Pick another theme!"></button><div id="theme-choices" role="menu"></div></div><script src="../theme.js"></script><nav class="sub"><form class="search-form"><div class="search-container"><div><select id="crate-search"><option value="All crates">All crates</option></select><input class="search-input" name="search" disabled autocomplete="off" spellcheck="false" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"></div><span class="help-button">?</span>
<a id="settings-menu" href="../settings.html"><img src="../wheel.svg" width="18" alt="Change settings"></a></div></form></nav><section id="main" class="content"><h1 class="fqn"><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/macros/select.rs.html#288-487" title="goto source code">[src]</a></span><span class="in-band">Macro <a href="index.html">tokio</a>::<wbr><a class="macro" href="">select</a></span></h1><div class="docblock type-decl hidden-by-usual-hider"><div class="example-wrap"><pre class="rust macro">
<span class="macro">macro_rules</span><span class="macro">!</span> <span class="ident">select</span> {
(@ {
<span class="comment">// One `_` for each branch in the `select!` macro. Passing this to</span>
<span class="comment">// `count!` converts $skip to an integer.</span>
( $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">count</span>:<span class="ident">tt</span>)<span class="op">*</span> )
<span class="comment">// Normalized select branches. `( $skip )` is a set of `_` characters.</span>
<span class="comment">// There is one `_` for each select branch **before** this one. Given</span>
<span class="comment">// that all input futures are stored in a tuple, $skip is useful for</span>
<span class="comment">// generating a pattern to reference the future for the current branch.</span>
<span class="comment">// $skip is also used as an argument to `count!`, returning the index of</span>
<span class="comment">// the current select branch.</span>
$( ( $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">skip</span>:<span class="ident">tt</span>)<span class="op">*</span> ) <span class="macro-nonterminal">$</span><span class="macro-nonterminal">bind</span>:<span class="ident">pat</span> <span class="op">=</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">fut</span>:<span class="ident">expr</span>, <span class="kw">if</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">c</span>:<span class="ident">expr</span> <span class="op">=</span><span class="op">&gt;</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">handle</span>:<span class="ident">expr</span>, )<span class="op">+</span>
<span class="comment">// Fallback expression used when all select branches have been disabled.</span>
; <span class="macro-nonterminal">$</span><span class="kw">else</span>:<span class="macro-nonterminal">expr</span>
}) <span class="op">=</span><span class="op">&gt;</span> { ... };
(@ { $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">t</span>:<span class="ident">tt</span>)<span class="op">*</span> } ) <span class="op">=</span><span class="op">&gt;</span> { ... };
(@ { $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">t</span>:<span class="ident">tt</span>)<span class="op">*</span> } <span class="kw">else</span> <span class="op">=</span><span class="op">&gt;</span> <span class="macro-nonterminal">$</span><span class="kw">else</span>:<span class="macro-nonterminal">expr</span> $(,)<span class="question-mark">?</span>) <span class="op">=</span><span class="op">&gt;</span> { ... };
(@ { ( $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">s</span>:<span class="ident">tt</span>)<span class="op">*</span> ) $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">t</span>:<span class="ident">tt</span>)<span class="op">*</span> } <span class="macro-nonterminal">$</span><span class="macro-nonterminal">p</span>:<span class="ident">pat</span> <span class="op">=</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">f</span>:<span class="ident">expr</span>, <span class="kw">if</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">c</span>:<span class="ident">expr</span> <span class="op">=</span><span class="op">&gt;</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">h</span>:<span class="ident">block</span>, $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">r</span>:<span class="ident">tt</span>)<span class="op">*</span> ) <span class="op">=</span><span class="op">&gt;</span> { ... };
(@ { ( $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">s</span>:<span class="ident">tt</span>)<span class="op">*</span> ) $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">t</span>:<span class="ident">tt</span>)<span class="op">*</span> } <span class="macro-nonterminal">$</span><span class="macro-nonterminal">p</span>:<span class="ident">pat</span> <span class="op">=</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">f</span>:<span class="ident">expr</span> <span class="op">=</span><span class="op">&gt;</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">h</span>:<span class="ident">block</span>, $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">r</span>:<span class="ident">tt</span>)<span class="op">*</span> ) <span class="op">=</span><span class="op">&gt;</span> { ... };
(@ { ( $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">s</span>:<span class="ident">tt</span>)<span class="op">*</span> ) $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">t</span>:<span class="ident">tt</span>)<span class="op">*</span> } <span class="macro-nonterminal">$</span><span class="macro-nonterminal">p</span>:<span class="ident">pat</span> <span class="op">=</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">f</span>:<span class="ident">expr</span>, <span class="kw">if</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">c</span>:<span class="ident">expr</span> <span class="op">=</span><span class="op">&gt;</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">h</span>:<span class="ident">block</span> $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">r</span>:<span class="ident">tt</span>)<span class="op">*</span> ) <span class="op">=</span><span class="op">&gt;</span> { ... };
(@ { ( $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">s</span>:<span class="ident">tt</span>)<span class="op">*</span> ) $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">t</span>:<span class="ident">tt</span>)<span class="op">*</span> } <span class="macro-nonterminal">$</span><span class="macro-nonterminal">p</span>:<span class="ident">pat</span> <span class="op">=</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">f</span>:<span class="ident">expr</span> <span class="op">=</span><span class="op">&gt;</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">h</span>:<span class="ident">block</span> $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">r</span>:<span class="ident">tt</span>)<span class="op">*</span> ) <span class="op">=</span><span class="op">&gt;</span> { ... };
(@ { ( $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">s</span>:<span class="ident">tt</span>)<span class="op">*</span> ) $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">t</span>:<span class="ident">tt</span>)<span class="op">*</span> } <span class="macro-nonterminal">$</span><span class="macro-nonterminal">p</span>:<span class="ident">pat</span> <span class="op">=</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">f</span>:<span class="ident">expr</span>, <span class="kw">if</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">c</span>:<span class="ident">expr</span> <span class="op">=</span><span class="op">&gt;</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">h</span>:<span class="ident">expr</span> ) <span class="op">=</span><span class="op">&gt;</span> { ... };
(@ { ( $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">s</span>:<span class="ident">tt</span>)<span class="op">*</span> ) $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">t</span>:<span class="ident">tt</span>)<span class="op">*</span> } <span class="macro-nonterminal">$</span><span class="macro-nonterminal">p</span>:<span class="ident">pat</span> <span class="op">=</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">f</span>:<span class="ident">expr</span> <span class="op">=</span><span class="op">&gt;</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">h</span>:<span class="ident">expr</span> ) <span class="op">=</span><span class="op">&gt;</span> { ... };
(@ { ( $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">s</span>:<span class="ident">tt</span>)<span class="op">*</span> ) $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">t</span>:<span class="ident">tt</span>)<span class="op">*</span> } <span class="macro-nonterminal">$</span><span class="macro-nonterminal">p</span>:<span class="ident">pat</span> <span class="op">=</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">f</span>:<span class="ident">expr</span>, <span class="kw">if</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">c</span>:<span class="ident">expr</span> <span class="op">=</span><span class="op">&gt;</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">h</span>:<span class="ident">expr</span>, $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">r</span>:<span class="ident">tt</span>)<span class="op">*</span> ) <span class="op">=</span><span class="op">&gt;</span> { ... };
(@ { ( $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">s</span>:<span class="ident">tt</span>)<span class="op">*</span> ) $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">t</span>:<span class="ident">tt</span>)<span class="op">*</span> } <span class="macro-nonterminal">$</span><span class="macro-nonterminal">p</span>:<span class="ident">pat</span> <span class="op">=</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">f</span>:<span class="ident">expr</span> <span class="op">=</span><span class="op">&gt;</span> <span class="macro-nonterminal">$</span><span class="macro-nonterminal">h</span>:<span class="ident">expr</span>, $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">r</span>:<span class="ident">tt</span>)<span class="op">*</span> ) <span class="op">=</span><span class="op">&gt;</span> { ... };
( <span class="macro-nonterminal">$</span><span class="macro-nonterminal">p</span>:<span class="ident">pat</span> <span class="op">=</span> $(<span class="macro-nonterminal">$</span><span class="macro-nonterminal">t</span>:<span class="ident">tt</span>)<span class="op">*</span> ) <span class="op">=</span><span class="op">&gt;</span> { ... };
() <span class="op">=</span><span class="op">&gt;</span> { ... };
}</pre></div>
</div><div class="docblock"><p>Wait on multiple concurrent branches, returning when the <strong>first</strong> branch
completes, cancelling the remaining branches.</p>
<p>The <code>select!</code> macro must be used inside of async functions, closures, and
blocks.</p>
<p>The <code>select!</code> macro accepts one or more branches with the following pattern:</p>
<pre><code class="language-text">&lt;pattern&gt; = &lt;async expression&gt; (, if &lt;precondition&gt;)? =&gt; &lt;handler&gt;,
</code></pre>
<p>Additionally, the <code>select!</code> macro may include a single, optional <code>else</code>
branch, which evaluates if none of the other branches match their patterns:</p>
<pre><code class="language-text">else &lt;expression&gt;
</code></pre>
<p>The macro aggregates all <code>&lt;async expression&gt;</code> expressions and runs them
concurrently on the <strong>current</strong> task. Once the <strong>first</strong> expression
completes with a value that matches its <code>&lt;pattern&gt;</code>, the <code>select!</code> macro
returns the result of evaluating the completed branch's <code>&lt;handler&gt;</code>
expression.</p>
<p>Additionally, each branch may include an optional <code>if</code> precondition. This
precondition is evaluated <strong>before</strong> the <code>&lt;async expression&gt;</code>. If the
precondition returns <code>false</code>, the branch is entirely disabled. This
capability is useful when using <code>select!</code> within a loop.</p>
<p>The complete lifecycle of a <code>select!</code> expression is as follows:</p>
<ol>
<li>Evaluate all provided <code>&lt;precondition&gt;</code> expressions. If the precondition
returns <code>false</code>, disable the branch for the remainder of the current call
to <code>select!</code>. Re-entering <code>select!</code> due to a loop clears the &quot;disabled&quot;
state.</li>
<li>Aggregate the <code>&lt;async expression&gt;</code>s from each branch, including the
disabled ones. If the branch is disabled, <code>&lt;async expression&gt;</code> is still
evaluated, but the resulting future is not polled.</li>
<li>Concurrently await on the results for all remaining <code>&lt;async expression&gt;</code>s.</li>
<li>Once an <code>&lt;async expression&gt;</code> returns a value, attempt to apply the value
to the provided <code>&lt;pattern&gt;</code>, if the pattern matches, evaluate <code>&lt;handler&gt;</code>
and return. If the pattern <strong>does not</strong> match, disable the current branch
and for the remainder of the current call to <code>select!</code>. Continue from step 3.</li>
<li>If <strong>all</strong> branches are disabled, evaluate the <code>else</code> expression. If none
is provided, panic.</li>
</ol>
<h1 id="notes" class="section-header"><a href="#notes">Notes</a></h1><h3 id="runtime-characteristics" class="section-header"><a href="#runtime-characteristics">Runtime characteristics</a></h3>
<p>By running all async expressions on the current task, the expressions are
able to run <strong>concurrently</strong> but not in <strong>parallel</strong>. This means all
expressions are run on the same thread and if one branch blocks the thread,
all other expressions will be unable to continue. If parallelism is
required, spawn each async expression using <a href="../tokio/fn.spawn.html"><code>tokio::spawn</code></a> and pass the
join handle to <code>select!</code>.</p>
<h3 id="avoid-racy-if-preconditions" class="section-header"><a href="#avoid-racy-if-preconditions">Avoid racy <code>if</code> preconditions</a></h3>
<p>Given that <code>if</code> preconditions are used to disable <code>select!</code> branches, some
caution must be used to avoid missing values.</p>
<p>For example, here is <strong>incorrect</strong> usage of <code>sleep</code> with <code>if</code>. The objective
is to repeatedly run an asynchronous task for up to 50 milliseconds.
However, there is a potential for the <code>sleep</code> completion to be missed.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">tokio</span>::<span class="ident">time</span>::{<span class="self">self</span>, <span class="ident">Duration</span>};
<span class="ident">async</span> <span class="kw">fn</span> <span class="ident">some_async_work</span>() {
<span class="comment">// do work</span>
}
<span class="attribute">#[<span class="ident">tokio</span>::<span class="ident">main</span>]</span>
<span class="ident">async</span> <span class="kw">fn</span> <span class="ident">main</span>() {
<span class="kw">let</span> <span class="ident">sleep</span> <span class="op">=</span> <span class="ident">time</span>::<span class="ident">sleep</span>(<span class="ident">Duration</span>::<span class="ident">from_millis</span>(<span class="number">50</span>));
<span class="ident">tokio</span>::<span class="macro">pin</span><span class="macro">!</span>(<span class="ident">sleep</span>);
<span class="kw">while</span> <span class="op">!</span><span class="ident">sleep</span>.<span class="ident">is_elapsed</span>() {
<span class="ident">tokio</span>::<span class="macro">select</span><span class="macro">!</span> {
<span class="kw">_</span> <span class="op">=</span> <span class="kw-2">&amp;</span><span class="kw-2">mut</span> <span class="ident">sleep</span>, <span class="kw">if</span> <span class="op">!</span><span class="ident">sleep</span>.<span class="ident">is_elapsed</span>() <span class="op">=</span><span class="op">&gt;</span> {
<span class="macro">println</span><span class="macro">!</span>(<span class="string">&quot;operation timed out&quot;</span>);
}
<span class="kw">_</span> <span class="op">=</span> <span class="ident">some_async_work</span>() <span class="op">=</span><span class="op">&gt;</span> {
<span class="macro">println</span><span class="macro">!</span>(<span class="string">&quot;operation completed&quot;</span>);
}
}
}
}</pre></div>
<p>In the above example, <code>sleep.is_elapsed()</code> may return <code>true</code> even if
<code>sleep.poll()</code> never returned <code>Ready</code>. This opens up a potential race
condition where <code>sleep</code> expires between the <code>while !sleep.is_elapsed()</code>
check and the call to <code>select!</code> resulting in the <code>some_async_work()</code> call to
run uninterrupted despite the sleep having elapsed.</p>
<p>One way to write the above example without the race would be:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">tokio</span>::<span class="ident">time</span>::{<span class="self">self</span>, <span class="ident">Duration</span>};
<span class="ident">async</span> <span class="kw">fn</span> <span class="ident">some_async_work</span>() {
<span class="comment">// do work</span>
}
<span class="attribute">#[<span class="ident">tokio</span>::<span class="ident">main</span>]</span>
<span class="ident">async</span> <span class="kw">fn</span> <span class="ident">main</span>() {
<span class="kw">let</span> <span class="ident">sleep</span> <span class="op">=</span> <span class="ident">time</span>::<span class="ident">sleep</span>(<span class="ident">Duration</span>::<span class="ident">from_millis</span>(<span class="number">50</span>));
<span class="ident">tokio</span>::<span class="macro">pin</span><span class="macro">!</span>(<span class="ident">sleep</span>);
<span class="kw">loop</span> {
<span class="ident">tokio</span>::<span class="macro">select</span><span class="macro">!</span> {
<span class="kw">_</span> <span class="op">=</span> <span class="kw-2">&amp;</span><span class="kw-2">mut</span> <span class="ident">sleep</span> <span class="op">=</span><span class="op">&gt;</span> {
<span class="macro">println</span><span class="macro">!</span>(<span class="string">&quot;operation timed out&quot;</span>);
<span class="kw">break</span>;
}
<span class="kw">_</span> <span class="op">=</span> <span class="ident">some_async_work</span>() <span class="op">=</span><span class="op">&gt;</span> {
<span class="macro">println</span><span class="macro">!</span>(<span class="string">&quot;operation completed&quot;</span>);
}
}
}
}</pre></div>
<h3 id="fairness" class="section-header"><a href="#fairness">Fairness</a></h3>
<p><code>select!</code> randomly picks a branch to check first. This provides some level
of fairness when calling <code>select!</code> in a loop with branches that are always
ready.</p>
<h1 id="panics" class="section-header"><a href="#panics">Panics</a></h1>
<p><code>select!</code> panics if all branches are disabled <strong>and</strong> there is no provided
<code>else</code> branch. A branch is disabled when the provided <code>if</code> precondition
returns <code>false</code> <strong>or</strong> when the pattern does not match the result of `<async
expression>.</p>
<h1 id="examples" class="section-header"><a href="#examples">Examples</a></h1>
<p>Basic select with two branches.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="ident">async</span> <span class="kw">fn</span> <span class="ident">do_stuff_async</span>() {
<span class="comment">// async work</span>
}
<span class="ident">async</span> <span class="kw">fn</span> <span class="ident">more_async_work</span>() {
<span class="comment">// more here</span>
}
<span class="attribute">#[<span class="ident">tokio</span>::<span class="ident">main</span>]</span>
<span class="ident">async</span> <span class="kw">fn</span> <span class="ident">main</span>() {
<span class="ident">tokio</span>::<span class="macro">select</span><span class="macro">!</span> {
<span class="kw">_</span> <span class="op">=</span> <span class="ident">do_stuff_async</span>() <span class="op">=</span><span class="op">&gt;</span> {
<span class="macro">println</span><span class="macro">!</span>(<span class="string">&quot;do_stuff_async() completed first&quot;</span>)
}
<span class="kw">_</span> <span class="op">=</span> <span class="ident">more_async_work</span>() <span class="op">=</span><span class="op">&gt;</span> {
<span class="macro">println</span><span class="macro">!</span>(<span class="string">&quot;more_async_work() completed first&quot;</span>)
}
};
}</pre></div>
<p>Basic stream selecting.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">tokio_stream</span>::{<span class="self">self</span> <span class="kw">as</span> <span class="ident">stream</span>, <span class="ident">StreamExt</span>};
<span class="attribute">#[<span class="ident">tokio</span>::<span class="ident">main</span>]</span>
<span class="ident">async</span> <span class="kw">fn</span> <span class="ident">main</span>() {
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">stream1</span> <span class="op">=</span> <span class="ident">stream</span>::<span class="ident">iter</span>(<span class="macro">vec</span><span class="macro">!</span>[<span class="number">1</span>, <span class="number">2</span>, <span class="number">3</span>]);
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">stream2</span> <span class="op">=</span> <span class="ident">stream</span>::<span class="ident">iter</span>(<span class="macro">vec</span><span class="macro">!</span>[<span class="number">4</span>, <span class="number">5</span>, <span class="number">6</span>]);
<span class="kw">let</span> <span class="ident">next</span> <span class="op">=</span> <span class="ident">tokio</span>::<span class="macro">select</span><span class="macro">!</span> {
<span class="ident">v</span> <span class="op">=</span> <span class="ident">stream1</span>.<span class="ident">next</span>() <span class="op">=</span><span class="op">&gt;</span> <span class="ident">v</span>.<span class="ident">unwrap</span>(),
<span class="ident">v</span> <span class="op">=</span> <span class="ident">stream2</span>.<span class="ident">next</span>() <span class="op">=</span><span class="op">&gt;</span> <span class="ident">v</span>.<span class="ident">unwrap</span>(),
};
<span class="macro">assert</span><span class="macro">!</span>(<span class="ident">next</span> <span class="op">=</span><span class="op">=</span> <span class="number">1</span> <span class="op">|</span><span class="op">|</span> <span class="ident">next</span> <span class="op">=</span><span class="op">=</span> <span class="number">4</span>);
}</pre></div>
<p>Collect the contents of two streams. In this example, we rely on pattern
matching and the fact that <code>stream::iter</code> is &quot;fused&quot;, i.e. once the stream
is complete, all calls to <code>next()</code> return <code>None</code>.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">tokio_stream</span>::{<span class="self">self</span> <span class="kw">as</span> <span class="ident">stream</span>, <span class="ident">StreamExt</span>};
<span class="attribute">#[<span class="ident">tokio</span>::<span class="ident">main</span>]</span>
<span class="ident">async</span> <span class="kw">fn</span> <span class="ident">main</span>() {
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">stream1</span> <span class="op">=</span> <span class="ident">stream</span>::<span class="ident">iter</span>(<span class="macro">vec</span><span class="macro">!</span>[<span class="number">1</span>, <span class="number">2</span>, <span class="number">3</span>]);
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">stream2</span> <span class="op">=</span> <span class="ident">stream</span>::<span class="ident">iter</span>(<span class="macro">vec</span><span class="macro">!</span>[<span class="number">4</span>, <span class="number">5</span>, <span class="number">6</span>]);
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">values</span> <span class="op">=</span> <span class="macro">vec</span><span class="macro">!</span>[];
<span class="kw">loop</span> {
<span class="ident">tokio</span>::<span class="macro">select</span><span class="macro">!</span> {
<span class="prelude-val">Some</span>(<span class="ident">v</span>) <span class="op">=</span> <span class="ident">stream1</span>.<span class="ident">next</span>() <span class="op">=</span><span class="op">&gt;</span> <span class="ident">values</span>.<span class="ident">push</span>(<span class="ident">v</span>),
<span class="prelude-val">Some</span>(<span class="ident">v</span>) <span class="op">=</span> <span class="ident">stream2</span>.<span class="ident">next</span>() <span class="op">=</span><span class="op">&gt;</span> <span class="ident">values</span>.<span class="ident">push</span>(<span class="ident">v</span>),
<span class="kw">else</span> <span class="op">=</span><span class="op">&gt;</span> <span class="kw">break</span>,
}
}
<span class="ident">values</span>.<span class="ident">sort</span>();
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="kw-2">&amp;</span>[<span class="number">1</span>, <span class="number">2</span>, <span class="number">3</span>, <span class="number">4</span>, <span class="number">5</span>, <span class="number">6</span>], <span class="kw-2">&amp;</span><span class="ident">values</span>[..]);
}</pre></div>
<p>Using the same future in multiple <code>select!</code> expressions can be done by passing
a reference to the future. Doing so requires the future to be <a href="https://doc.rust-lang.org/nightly/core/marker/trait.Unpin.html"><code>Unpin</code></a>. A
future can be made <a href="https://doc.rust-lang.org/nightly/core/marker/trait.Unpin.html"><code>Unpin</code></a> by either using <a href="https://doc.rust-lang.org/nightly/alloc/boxed/struct.Box.html#method.pin"><code>Box::pin</code></a> or stack pinning.</p>
<p>Here, a stream is consumed for at most 1 second.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">tokio_stream</span>::{<span class="self">self</span> <span class="kw">as</span> <span class="ident">stream</span>, <span class="ident">StreamExt</span>};
<span class="kw">use</span> <span class="ident">tokio</span>::<span class="ident">time</span>::{<span class="self">self</span>, <span class="ident">Duration</span>};
<span class="attribute">#[<span class="ident">tokio</span>::<span class="ident">main</span>]</span>
<span class="ident">async</span> <span class="kw">fn</span> <span class="ident">main</span>() {
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">stream</span> <span class="op">=</span> <span class="ident">stream</span>::<span class="ident">iter</span>(<span class="macro">vec</span><span class="macro">!</span>[<span class="number">1</span>, <span class="number">2</span>, <span class="number">3</span>]);
<span class="kw">let</span> <span class="ident">sleep</span> <span class="op">=</span> <span class="ident">time</span>::<span class="ident">sleep</span>(<span class="ident">Duration</span>::<span class="ident">from_secs</span>(<span class="number">1</span>));
<span class="ident">tokio</span>::<span class="macro">pin</span><span class="macro">!</span>(<span class="ident">sleep</span>);
<span class="kw">loop</span> {
<span class="ident">tokio</span>::<span class="macro">select</span><span class="macro">!</span> {
<span class="ident">maybe_v</span> <span class="op">=</span> <span class="ident">stream</span>.<span class="ident">next</span>() <span class="op">=</span><span class="op">&gt;</span> {
<span class="kw">if</span> <span class="kw">let</span> <span class="prelude-val">Some</span>(<span class="ident">v</span>) <span class="op">=</span> <span class="ident">maybe_v</span> {
<span class="macro">println</span><span class="macro">!</span>(<span class="string">&quot;got = {}&quot;</span>, <span class="ident">v</span>);
} <span class="kw">else</span> {
<span class="kw">break</span>;
}
}
<span class="kw">_</span> <span class="op">=</span> <span class="kw-2">&amp;</span><span class="kw-2">mut</span> <span class="ident">sleep</span> <span class="op">=</span><span class="op">&gt;</span> {
<span class="macro">println</span><span class="macro">!</span>(<span class="string">&quot;timeout&quot;</span>);
<span class="kw">break</span>;
}
}
}
}</pre></div>
<p>Joining two values using <code>select!</code>.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">tokio</span>::<span class="ident">sync</span>::<span class="ident">oneshot</span>;
<span class="attribute">#[<span class="ident">tokio</span>::<span class="ident">main</span>]</span>
<span class="ident">async</span> <span class="kw">fn</span> <span class="ident">main</span>() {
<span class="kw">let</span> (<span class="ident">tx1</span>, <span class="kw-2">mut</span> <span class="ident">rx1</span>) <span class="op">=</span> <span class="ident">oneshot</span>::<span class="ident">channel</span>();
<span class="kw">let</span> (<span class="ident">tx2</span>, <span class="kw-2">mut</span> <span class="ident">rx2</span>) <span class="op">=</span> <span class="ident">oneshot</span>::<span class="ident">channel</span>();
<span class="ident">tokio</span>::<span class="ident">spawn</span>(<span class="ident">async</span> <span class="kw">move</span> {
<span class="ident">tx1</span>.<span class="ident">send</span>(<span class="string">&quot;first&quot;</span>).<span class="ident">unwrap</span>();
});
<span class="ident">tokio</span>::<span class="ident">spawn</span>(<span class="ident">async</span> <span class="kw">move</span> {
<span class="ident">tx2</span>.<span class="ident">send</span>(<span class="string">&quot;second&quot;</span>).<span class="ident">unwrap</span>();
});
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">a</span> <span class="op">=</span> <span class="prelude-val">None</span>;
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">b</span> <span class="op">=</span> <span class="prelude-val">None</span>;
<span class="kw">while</span> <span class="ident">a</span>.<span class="ident">is_none</span>() <span class="op">|</span><span class="op">|</span> <span class="ident">b</span>.<span class="ident">is_none</span>() {
<span class="ident">tokio</span>::<span class="macro">select</span><span class="macro">!</span> {
<span class="ident">v1</span> <span class="op">=</span> (<span class="kw-2">&amp;</span><span class="kw-2">mut</span> <span class="ident">rx1</span>), <span class="kw">if</span> <span class="ident">a</span>.<span class="ident">is_none</span>() <span class="op">=</span><span class="op">&gt;</span> <span class="ident">a</span> <span class="op">=</span> <span class="prelude-val">Some</span>(<span class="ident">v1</span>.<span class="ident">unwrap</span>()),
<span class="ident">v2</span> <span class="op">=</span> (<span class="kw-2">&amp;</span><span class="kw-2">mut</span> <span class="ident">rx2</span>), <span class="kw">if</span> <span class="ident">b</span>.<span class="ident">is_none</span>() <span class="op">=</span><span class="op">&gt;</span> <span class="ident">b</span> <span class="op">=</span> <span class="prelude-val">Some</span>(<span class="ident">v2</span>.<span class="ident">unwrap</span>()),
}
}
<span class="kw">let</span> <span class="ident">res</span> <span class="op">=</span> (<span class="ident">a</span>.<span class="ident">unwrap</span>(), <span class="ident">b</span>.<span class="ident">unwrap</span>());
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">res</span>.<span class="number">0</span>, <span class="string">&quot;first&quot;</span>);
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">res</span>.<span class="number">1</span>, <span class="string">&quot;second&quot;</span>);
}</pre></div>
</div></section><section id="search" class="content hidden"></section><section class="footer"></section><script>window.rootPath = "../";window.currentCrate = "tokio";</script><script src="../main.js"></script><script defer src="../search-index.js"></script></body></html>
Reference in New Issue View Git Blame Copy Permalink