mirror of
https://github.com/rtic-rs/rtic.git
synced 2024-12-12 05:07:16 +01:00
219 lines
55 KiB
HTML
219 lines
55 KiB
HTML
|
<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="An extension trait for `Future`s that provides a variety of convenient adapters."><title>FutureExt in futures_util::future - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-46f98efaafac5295.ttf.woff2,FiraSans-Regular-018c141bf0843ffd.woff2,FiraSans-Medium-8f9a781e4970d388.woff2,SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2,SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2" crossorigin href="../../static.files/${f}">`).join(""))</script><link rel="stylesheet" href="../../static.files/normalize-76eba96aa4d2e634.css"><link rel="stylesheet" href="../../static.files/rustdoc-b0742ba02757f159.css"><meta name="rustdoc-vars" data-root-path="../../" data-static-root-path="../../static.files/" data-current-crate="futures_util" data-themes="" data-resource-suffix="" data-rustdoc-version="1.83.0 (90b35a623 2024-11-26)" data-channel="1.83.0" data-search-js="search-f0d225181b97f9a4.js" data-settings-js="settings-805db61a62df4bd2.js" ><script src="../../static.files/storage-1d39b6787ed640ff.js"></script><script defer src="sidebar-items.js"></script><script defer src="../../static.files/main-f070b9041d14864c.js"></script><noscript><link rel="stylesheet" href="../../static.files/noscript-0111fcff984fae8f.css"></noscript><link rel="alternate icon" type="image/png" href="../../static.files/favicon-32x32-422f7d1d52889060.png"><link rel="icon" type="image/svg+xml" href="../../static.files/favicon-2c020d218678b618.svg"></head><body class="rustdoc trait"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle" title="show sidebar"></button></nav><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../../futures_util/index.html">futures_<wbr>util</a><span class="version">0.3.31</span></h2></div><div class="sidebar-elems"><section id="rustdoc-toc"><h2 class="location"><a href="#">Future<wbr>Ext</a></h2><h3><a href="#provided-methods">Provided Methods</a></h3><ul class="block"><li><a href="#method.flatten" title="flatten">flatten</a></li><li><a href="#method.flatten_stream" title="flatten_stream">flatten_stream</a></li><li><a href="#method.fuse" title="fuse">fuse</a></li><li><a href="#method.inspect" title="inspect">inspect</a></li><li><a href="#method.into_stream" title="into_stream">into_stream</a></li><li><a href="#method.left_future" title="left_future">left_future</a></li><li><a href="#method.map" title="map">map</a></li><li><a href="#method.map_into" title="map_into">map_into</a></li><li><a href="#method.never_error" title="never_error">never_error</a></li><li><a href="#method.now_or_never" title="now_or_never">now_or_never</a></li><li><a href="#method.poll_unpin" title="poll_unpin">poll_unpin</a></li><li><a href="#method.right_future" title="right_future">right_future</a></li><li><a href="#method.then" title="then">then</a></li><li><a href="#method.unit_error" title="unit_error">unit_error</a></li></ul><h3><a href="#implementors">Implementors</a></h3></section><div id="rustdoc-modnav"><h2><a href="index.html">In futures_<wbr>util::<wbr>future</a></h2></div></div></nav><div class="sidebar-resizer"></div><main><div class="width-limiter"><rustdoc-search></rustdoc-search><section id="main-content" class="content"><div class="main-heading"><span class="rustdoc-breadcrumbs"><a href="../index.html">futures_util</a>::<wbr><a href="index.html">future</a></span><h1>Trait <span class="trait">FutureExt</span><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/futures_util/future/future/mod.rs.html#123-606">source</a> </span></div><pre clas
|
|||
|
|
<details class="toggle type-contents-toggle"><summary class="hideme"><span>Show 14 methods</span></summary> // Provided methods
|
|||
|
|
fn <a href="#method.map" class="fn">map</a><U, F>(self, f: F) -> <a class="struct" href="struct.Map.html" title="struct futures_util::future::Map">Map</a><Self, F> <a href="#" class="tooltip" data-notable-ty="Map<Self, F>">ⓘ</a>
|
|||
|
|
<span class="where">where F: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/ops/function/trait.FnOnce.html" title="trait core::ops::function::FnOnce">FnOnce</a>(Self::<a class="associatedtype" href="https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html#associatedtype.Output" title="type core::future::future::Future::Output">Output</a>) -> U,
|
|||
|
|
Self: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a></span> { ... }
|
|||
|
|
<span class="item-spacer"></span> fn <a href="#method.map_into" class="fn">map_into</a><U>(self) -> <a class="struct" href="struct.MapInto.html" title="struct futures_util::future::MapInto">MapInto</a><Self, U> <a href="#" class="tooltip" data-notable-ty="MapInto<Self, U>">ⓘ</a>
|
|||
|
|
<span class="where">where Self::<a class="associatedtype" href="https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html#associatedtype.Output" title="type core::future::future::Future::Output">Output</a>: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/convert/trait.Into.html" title="trait core::convert::Into">Into</a><U>,
|
|||
|
|
Self: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a></span> { ... }
|
|||
|
|
<span class="item-spacer"></span> fn <a href="#method.then" class="fn">then</a><Fut, F>(self, f: F) -> <a class="struct" href="struct.Then.html" title="struct futures_util::future::Then">Then</a><Self, Fut, F> <a href="#" class="tooltip" data-notable-ty="Then<Self, Fut, F>">ⓘ</a>
|
|||
|
|
<span class="where">where F: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/ops/function/trait.FnOnce.html" title="trait core::ops::function::FnOnce">FnOnce</a>(Self::<a class="associatedtype" href="https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html#associatedtype.Output" title="type core::future::future::Future::Output">Output</a>) -> Fut,
|
|||
|
|
Fut: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html" title="trait core::future::future::Future">Future</a>,
|
|||
|
|
Self: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a></span> { ... }
|
|||
|
|
<span class="item-spacer"></span> fn <a href="#method.left_future" class="fn">left_future</a><B>(self) -> <a class="enum" href="enum.Either.html" title="enum futures_util::future::Either">Either</a><Self, B> <a href="#" class="tooltip" data-notable-ty="Either<Self, B>">ⓘ</a>
|
|||
|
|
<span class="where">where B: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html" title="trait core::future::future::Future">Future</a><Output = Self::<a class="associatedtype" href="https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html#associatedtype.Output" title="type core::future::future::Future::Output">Output</a>>,
|
|||
|
|
Self: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a></span> { ... }
|
|||
|
|
<span class="item-spacer"></span> fn <a href="#method.right_future" class="fn">right_future</a><A>(self) -> <a class="enum" href="enum.Either.html" title="enum futures_util::future::Either">Either</a><A, Self> <a href="#" class="tooltip" data-notable-ty="Either<A, Self>">ⓘ</a>
|
|||
|
|
<span class="where">where A: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html" title="trait core::future::future::Future">Future</a><Output = Self::<a class="associatedtype" href="https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html#associatedtype.Output" title="type core::future::future::Future::Output">Output</a>>,
|
|||
|
|
Self: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a></span> { ... }
|
|||
|
|
<span class="item-spacer"></span> fn <a href="#method.into_stream" class="fn">into_stream</a>(self) -> <a class="struct" href="struct.IntoStream.html" title="struct futures_util::future::IntoStream">IntoStream</a><Self>
|
|||
|
|
<span class="where">where Self: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a></span> { ... }
|
|||
|
|
<span class="item-spacer"></span> fn <a href="#method.flatten" class="fn">flatten</a>(self) -> <a class="struct" href="struct.Flatten.html" title="struct futures_util::future::Flatten">Flatten</a><Self> <a href="#" class="tooltip" data-notable-ty="Flatten<Self>">ⓘ</a>
|
|||
|
|
<span class="where">where Self::<a class="associatedtype" href="https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html#associatedtype.Output" title="type core::future::future::Future::Output">Output</a>: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html" title="trait core::future::future::Future">Future</a>,
|
|||
|
|
Self: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a></span> { ... }
|
|||
|
|
<span class="item-spacer"></span> fn <a href="#method.flatten_stream" class="fn">flatten_stream</a>(self) -> <a class="struct" href="struct.FlattenStream.html" title="struct futures_util::future::FlattenStream">FlattenStream</a><Self>
|
|||
|
|
<span class="where">where Self::<a class="associatedtype" href="https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html#associatedtype.Output" title="type core::future::future::Future::Output">Output</a>: <a class="trait" href="../stream/trait.Stream.html" title="trait futures_util::stream::Stream">Stream</a>,
|
|||
|
|
Self: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a></span> { ... }
|
|||
|
|
<span class="item-spacer"></span> fn <a href="#method.fuse" class="fn">fuse</a>(self) -> <a class="struct" href="struct.Fuse.html" title="struct futures_util::future::Fuse">Fuse</a><Self> <a href="#" class="tooltip" data-notable-ty="Fuse<Self>">ⓘ</a>
|
|||
|
|
<span class="where">where Self: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a></span> { ... }
|
|||
|
|
<span class="item-spacer"></span> fn <a href="#method.inspect" class="fn">inspect</a><F>(self, f: F) -> <a class="struct" href="struct.Inspect.html" title="struct futures_util::future::Inspect">Inspect</a><Self, F> <a href="#" class="tooltip" data-notable-ty="Inspect<Self, F>">ⓘ</a>
|
|||
|
|
<span class="where">where F: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/ops/function/trait.FnOnce.html" title="trait core::ops::function::FnOnce">FnOnce</a>(&Self::<a class="associatedtype" href="https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html#associatedtype.Output" title="type core::future::future::Future::Output">Output</a>),
|
|||
|
|
Self: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a></span> { ... }
|
|||
|
|
<span class="item-spacer"></span> fn <a href="#method.unit_error" class="fn">unit_error</a>(self) -> <a class="struct" href="struct.UnitError.html" title="struct futures_util::future::UnitError">UnitError</a><Self> <a href="#" class="tooltip" data-notable-ty="UnitError<Self>">ⓘ</a>
|
|||
|
|
<span class="where">where Self: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a></span> { ... }
|
|||
|
|
<span class="item-spacer"></span> fn <a href="#method.never_error" class="fn">never_error</a>(self) -> <a class="struct" href="struct.NeverError.html" title="struct futures_util::future::NeverError">NeverError</a><Self> <a href="#" class="tooltip" data-notable-ty="NeverError<Self>">ⓘ</a>
|
|||
|
|
<span class="where">where Self: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a></span> { ... }
|
|||
|
|
<span class="item-spacer"></span> fn <a href="#method.poll_unpin" class="fn">poll_unpin</a>(&mut self, cx: &mut <a class="struct" href="https://doc.rust-lang.org/1.83.0/core/task/wake/struct.Context.html" title="struct core::task::wake::Context">Context</a><'_>) -> <a class="enum" href="https://doc.rust-lang.org/1.83.0/core/task/poll/enum.Poll.html" title="enum core::task::poll::Poll">Poll</a><Self::<a class="associatedtype" href="https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html#associatedtype.Output" title="type core::future::future::Future::Output">Output</a>>
|
|||
|
|
<span class="where">where Self: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/marker/trait.Unpin.html" title="trait core::marker::Unpin">Unpin</a></span> { ... }
|
|||
|
|
<span class="item-spacer"></span> fn <a href="#method.now_or_never" class="fn">now_or_never</a>(self) -> <a class="enum" href="https://doc.rust-lang.org/1.83.0/core/option/enum.Option.html" title="enum core::option::Option">Option</a><Self::<a class="associatedtype" href="https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html#associatedtype.Output" title="type core::future::future::Future::Output">Output</a>>
|
|||
|
|
<span class="where">where Self: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a></span> { ... }
|
|||
|
|
</details>}</code></pre><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>An extension trait for <code>Future</code>s that provides a variety of convenient
|
|||
|
|
adapters.</p>
|
|||
|
|
</div></details><h2 id="provided-methods" class="section-header">Provided Methods<a href="#provided-methods" class="anchor">§</a></h2><div class="methods"><details class="toggle method-toggle" open><summary><section id="method.map" class="method"><a class="src rightside" href="../../src/futures_util/future/future/mod.rs.html#146-152">source</a><h4 class="code-header">fn <a href="#method.map" class="fn">map</a><U, F>(self, f: F) -> <a class="struct" href="struct.Map.html" title="struct futures_util::future::Map">Map</a><Self, F> <a href="#" class="tooltip" data-notable-ty="Map<Self, F>">ⓘ</a><div class="where">where
|
|||
|
|
F: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/ops/function/trait.FnOnce.html" title="trait core::ops::function::FnOnce">FnOnce</a>(Self::<a class="associatedtype" href="https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html#associatedtype.Output" title="type core::future::future::Future::Output">Output</a>) -> U,
|
|||
|
|
Self: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h4></section></summary><div class="docblock"><p>Map this future’s output to a different type, returning a new future of
|
|||
|
|
the resulting type.</p>
|
|||
|
|
<p>This function is similar to the <code>Option::map</code> or <code>Iterator::map</code> where
|
|||
|
|
it will change the type of the underlying future. This is useful to
|
|||
|
|
chain along a computation once a future has been resolved.</p>
|
|||
|
|
<p>Note that this function consumes the receiving future and returns a
|
|||
|
|
wrapped version of it, similar to the existing <code>map</code> methods in the
|
|||
|
|
standard library.</p>
|
|||
|
|
<h5 id="examples"><a class="doc-anchor" href="#examples">§</a>Examples</h5>
|
|||
|
|
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>futures::future::FutureExt;
|
|||
|
|
|
|||
|
|
<span class="kw">let </span>future = <span class="kw">async </span>{ <span class="number">1 </span>};
|
|||
|
|
<span class="kw">let </span>new_future = future.map(|x| x + <span class="number">3</span>);
|
|||
|
|
<span class="macro">assert_eq!</span>(new_future.<span class="kw">await</span>, <span class="number">4</span>);</code></pre></div>
|
|||
|
|
</div></details><details class="toggle method-toggle" open><summary><section id="method.map_into" class="method"><a class="src rightside" href="../../src/futures_util/future/future/mod.rs.html#159-165">source</a><h4 class="code-header">fn <a href="#method.map_into" class="fn">map_into</a><U>(self) -> <a class="struct" href="struct.MapInto.html" title="struct futures_util::future::MapInto">MapInto</a><Self, U> <a href="#" class="tooltip" data-notable-ty="MapInto<Self, U>">ⓘ</a><div class="where">where
|
|||
|
|
Self::<a class="associatedtype" href="https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html#associatedtype.Output" title="type core::future::future::Future::Output">Output</a>: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/convert/trait.Into.html" title="trait core::convert::Into">Into</a><U>,
|
|||
|
|
Self: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h4></section></summary><div class="docblock"><p>Map this future’s output to a different type, returning a new future of
|
|||
|
|
the resulting type.</p>
|
|||
|
|
<p>This function is equivalent to calling <code>map(Into::into)</code> but allows naming
|
|||
|
|
the return type.</p>
|
|||
|
|
</div></details><details class="toggle method-toggle" open><summary><section id="method.then" class="method"><a class="src rightside" href="../../src/futures_util/future/future/mod.rs.html#191-198">source</a><h4 class="code-header">fn <a href="#method.then" class="fn">then</a><Fut, F>(self, f: F) -> <a class="struct" href="struct.Then.html" title="struct futures_util::future::Then">Then</a><Self, Fut, F> <a href="#" class="tooltip" data-notable-ty="Then<Self, Fut, F>">ⓘ</a><div class="where">where
|
|||
|
|
F: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/ops/function/trait.FnOnce.html" title="trait core::ops::function::FnOnce">FnOnce</a>(Self::<a class="associatedtype" href="https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html#associatedtype.Output" title="type core::future::future::Future::Output">Output</a>) -> Fut,
|
|||
|
|
Fut: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html" title="trait core::future::future::Future">Future</a>,
|
|||
|
|
Self: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h4></section></summary><div class="docblock"><p>Chain on a computation for when a future finished, passing the result of
|
|||
|
|
the future to the provided closure <code>f</code>.</p>
|
|||
|
|
<p>The returned value of the closure must implement the <code>Future</code> trait
|
|||
|
|
and can represent some more work to be done before the composed future
|
|||
|
|
is finished.</p>
|
|||
|
|
<p>The closure <code>f</code> is only run <em>after</em> successful completion of the <code>self</code>
|
|||
|
|
future.</p>
|
|||
|
|
<p>Note that this function consumes the receiving future and returns a
|
|||
|
|
wrapped version of it.</p>
|
|||
|
|
<h5 id="examples-1"><a class="doc-anchor" href="#examples-1">§</a>Examples</h5>
|
|||
|
|
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>futures::future::FutureExt;
|
|||
|
|
|
|||
|
|
<span class="kw">let </span>future_of_1 = <span class="kw">async </span>{ <span class="number">1 </span>};
|
|||
|
|
<span class="kw">let </span>future_of_4 = future_of_1.then(|x| <span class="kw">async move </span>{ x + <span class="number">3 </span>});
|
|||
|
|
<span class="macro">assert_eq!</span>(future_of_4.<span class="kw">await</span>, <span class="number">4</span>);</code></pre></div>
|
|||
|
|
</div></details><details class="toggle method-toggle" open><summary><section id="method.left_future" class="method"><a class="src rightside" href="../../src/futures_util/future/future/mod.rs.html#222-228">source</a><h4 class="code-header">fn <a href="#method.left_future" class="fn">left_future</a><B>(self) -> <a class="enum" href="enum.Either.html" title="enum futures_util::future::Either">Either</a><Self, B> <a href="#" class="tooltip" data-notable-ty="Either<Self, B>">ⓘ</a><div class="where">where
|
|||
|
|
B: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html" title="trait core::future::future::Future">Future</a><Output = Self::<a class="associatedtype" href="https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html#associatedtype.Output" title="type core::future::future::Future::Output">Output</a>>,
|
|||
|
|
Self: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h4></section></summary><div class="docblock"><p>Wrap this future in an <code>Either</code> future, making it the left-hand variant
|
|||
|
|
of that <code>Either</code>.</p>
|
|||
|
|
<p>This can be used in combination with the <code>right_future</code> method to write <code>if</code>
|
|||
|
|
statements that evaluate to different futures in different branches.</p>
|
|||
|
|
<h5 id="examples-2"><a class="doc-anchor" href="#examples-2">§</a>Examples</h5>
|
|||
|
|
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>futures::future::FutureExt;
|
|||
|
|
|
|||
|
|
<span class="kw">let </span>x = <span class="number">6</span>;
|
|||
|
|
<span class="kw">let </span>future = <span class="kw">if </span>x < <span class="number">10 </span>{
|
|||
|
|
<span class="kw">async </span>{ <span class="bool-val">true </span>}.left_future()
|
|||
|
|
} <span class="kw">else </span>{
|
|||
|
|
<span class="kw">async </span>{ <span class="bool-val">false </span>}.right_future()
|
|||
|
|
};
|
|||
|
|
|
|||
|
|
<span class="macro">assert_eq!</span>(future.<span class="kw">await</span>, <span class="bool-val">true</span>);</code></pre></div>
|
|||
|
|
</div></details><details class="toggle method-toggle" open><summary><section id="method.right_future" class="method"><a class="src rightside" href="../../src/futures_util/future/future/mod.rs.html#252-258">source</a><h4 class="code-header">fn <a href="#method.right_future" class="fn">right_future</a><A>(self) -> <a class="enum" href="enum.Either.html" title="enum futures_util::future::Either">Either</a><A, Self> <a href="#" class="tooltip" data-notable-ty="Either<A, Self>">ⓘ</a><div class="where">where
|
|||
|
|
A: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html" title="trait core::future::future::Future">Future</a><Output = Self::<a class="associatedtype" href="https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html#associatedtype.Output" title="type core::future::future::Future::Output">Output</a>>,
|
|||
|
|
Self: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h4></section></summary><div class="docblock"><p>Wrap this future in an <code>Either</code> future, making it the right-hand variant
|
|||
|
|
of that <code>Either</code>.</p>
|
|||
|
|
<p>This can be used in combination with the <code>left_future</code> method to write <code>if</code>
|
|||
|
|
statements that evaluate to different futures in different branches.</p>
|
|||
|
|
<h5 id="examples-3"><a class="doc-anchor" href="#examples-3">§</a>Examples</h5>
|
|||
|
|
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>futures::future::FutureExt;
|
|||
|
|
|
|||
|
|
<span class="kw">let </span>x = <span class="number">6</span>;
|
|||
|
|
<span class="kw">let </span>future = <span class="kw">if </span>x > <span class="number">10 </span>{
|
|||
|
|
<span class="kw">async </span>{ <span class="bool-val">true </span>}.left_future()
|
|||
|
|
} <span class="kw">else </span>{
|
|||
|
|
<span class="kw">async </span>{ <span class="bool-val">false </span>}.right_future()
|
|||
|
|
};
|
|||
|
|
|
|||
|
|
<span class="macro">assert_eq!</span>(future.<span class="kw">await</span>, <span class="bool-val">false</span>);</code></pre></div>
|
|||
|
|
</div></details><details class="toggle method-toggle" open><summary><section id="method.into_stream" class="method"><a class="src rightside" href="../../src/futures_util/future/future/mod.rs.html#278-283">source</a><h4 class="code-header">fn <a href="#method.into_stream" class="fn">into_stream</a>(self) -> <a class="struct" href="struct.IntoStream.html" title="struct futures_util::future::IntoStream">IntoStream</a><Self><div class="where">where
|
|||
|
|
Self: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h4></section></summary><div class="docblock"><p>Convert this future into a single element stream.</p>
|
|||
|
|
<p>The returned stream contains single success if this future resolves to
|
|||
|
|
success or single error if this future resolves into error.</p>
|
|||
|
|
<h5 id="examples-4"><a class="doc-anchor" href="#examples-4">§</a>Examples</h5>
|
|||
|
|
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>futures::future::FutureExt;
|
|||
|
|
<span class="kw">use </span>futures::stream::StreamExt;
|
|||
|
|
|
|||
|
|
<span class="kw">let </span>future = <span class="kw">async </span>{ <span class="number">17 </span>};
|
|||
|
|
<span class="kw">let </span>stream = future.into_stream();
|
|||
|
|
<span class="kw">let </span>collected: Vec<<span class="kw">_</span>> = stream.collect().<span class="kw">await</span>;
|
|||
|
|
<span class="macro">assert_eq!</span>(collected, <span class="macro">vec!</span>[<span class="number">17</span>]);</code></pre></div>
|
|||
|
|
</div></details><details class="toggle method-toggle" open><summary><section id="method.flatten" class="method"><a class="src rightside" href="../../src/futures_util/future/future/mod.rs.html#307-314">source</a><h4 class="code-header">fn <a href="#method.flatten" class="fn">flatten</a>(self) -> <a class="struct" href="struct.Flatten.html" title="struct futures_util::future::Flatten">Flatten</a><Self> <a href="#" class="tooltip" data-notable-ty="Flatten<Self>">ⓘ</a><div class="where">where
|
|||
|
|
Self::<a class="associatedtype" href="https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html#associatedtype.Output" title="type core::future::future::Future::Output">Output</a>: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html" title="trait core::future::future::Future">Future</a>,
|
|||
|
|
Self: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h4></section></summary><div class="docblock"><p>Flatten the execution of this future when the output of this
|
|||
|
|
future is itself another future.</p>
|
|||
|
|
<p>This can be useful when combining futures together to flatten the
|
|||
|
|
computation out the final result.</p>
|
|||
|
|
<p>This method is roughly equivalent to <code>self.then(|x| x)</code>.</p>
|
|||
|
|
<p>Note that this function consumes the receiving future and returns a
|
|||
|
|
wrapped version of it.</p>
|
|||
|
|
<h5 id="examples-5"><a class="doc-anchor" href="#examples-5">§</a>Examples</h5>
|
|||
|
|
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>futures::future::FutureExt;
|
|||
|
|
|
|||
|
|
<span class="kw">let </span>nested_future = <span class="kw">async </span>{ <span class="kw">async </span>{ <span class="number">1 </span>} };
|
|||
|
|
<span class="kw">let </span>future = nested_future.flatten();
|
|||
|
|
<span class="macro">assert_eq!</span>(future.<span class="kw">await</span>, <span class="number">1</span>);</code></pre></div>
|
|||
|
|
</div></details><details class="toggle method-toggle" open><summary><section id="method.flatten_stream" class="method"><a class="src rightside" href="../../src/futures_util/future/future/mod.rs.html#341-347">source</a><h4 class="code-header">fn <a href="#method.flatten_stream" class="fn">flatten_stream</a>(self) -> <a class="struct" href="struct.FlattenStream.html" title="struct futures_util::future::FlattenStream">FlattenStream</a><Self><div class="where">where
|
|||
|
|
Self::<a class="associatedtype" href="https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html#associatedtype.Output" title="type core::future::future::Future::Output">Output</a>: <a class="trait" href="../stream/trait.Stream.html" title="trait futures_util::stream::Stream">Stream</a>,
|
|||
|
|
Self: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h4></section></summary><div class="docblock"><p>Flatten the execution of this future when the successful result of this
|
|||
|
|
future is a stream.</p>
|
|||
|
|
<p>This can be useful when stream initialization is deferred, and it is
|
|||
|
|
convenient to work with that stream as if stream was available at the
|
|||
|
|
call site.</p>
|
|||
|
|
<p>Note that this function consumes this future and returns a wrapped
|
|||
|
|
version of it.</p>
|
|||
|
|
<h5 id="examples-6"><a class="doc-anchor" href="#examples-6">§</a>Examples</h5>
|
|||
|
|
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>futures::future::FutureExt;
|
|||
|
|
<span class="kw">use </span>futures::stream::{<span class="self">self</span>, StreamExt};
|
|||
|
|
|
|||
|
|
<span class="kw">let </span>stream_items = <span class="macro">vec!</span>[<span class="number">17</span>, <span class="number">18</span>, <span class="number">19</span>];
|
|||
|
|
<span class="kw">let </span>future_of_a_stream = <span class="kw">async </span>{ stream::iter(stream_items) };
|
|||
|
|
|
|||
|
|
<span class="kw">let </span>stream = future_of_a_stream.flatten_stream();
|
|||
|
|
<span class="kw">let </span>list: Vec<<span class="kw">_</span>> = stream.collect().<span class="kw">await</span>;
|
|||
|
|
<span class="macro">assert_eq!</span>(list, <span class="macro">vec!</span>[<span class="number">17</span>, <span class="number">18</span>, <span class="number">19</span>]);</code></pre></div>
|
|||
|
|
</div></details><details class="toggle method-toggle" open><summary><section id="method.fuse" class="method"><a class="src rightside" href="../../src/futures_util/future/future/mod.rs.html#365-371">source</a><h4 class="code-header">fn <a href="#method.fuse" class="fn">fuse</a>(self) -> <a class="struct" href="struct.Fuse.html" title="struct futures_util::future::Fuse">Fuse</a><Self> <a href="#" class="tooltip" data-notable-ty="Fuse<Self>">ⓘ</a><div class="where">where
|
|||
|
|
Self: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h4></section></summary><div class="docblock"><p>Fuse a future such that <code>poll</code> will never again be called once it has
|
|||
|
|
completed. This method can be used to turn any <code>Future</code> into a
|
|||
|
|
<code>FusedFuture</code>.</p>
|
|||
|
|
<p>Normally, once a future has returned <code>Poll::Ready</code> from <code>poll</code>,
|
|||
|
|
any further calls could exhibit bad behavior such as blocking
|
|||
|
|
forever, panicking, never returning, etc. If it is known that <code>poll</code>
|
|||
|
|
may be called too often then this method can be used to ensure that it
|
|||
|
|
has defined semantics.</p>
|
|||
|
|
<p>If a <code>fuse</code>d future is <code>poll</code>ed after having returned <code>Poll::Ready</code>
|
|||
|
|
previously, it will return <code>Poll::Pending</code>, from <code>poll</code> again (and will
|
|||
|
|
continue to do so for all future calls to <code>poll</code>).</p>
|
|||
|
|
<p>This combinator will drop the underlying future as soon as it has been
|
|||
|
|
completed to ensure resources are reclaimed as soon as possible.</p>
|
|||
|
|
</div></details><details class="toggle method-toggle" open><summary><section id="method.inspect" class="method"><a class="src rightside" href="../../src/futures_util/future/future/mod.rs.html#391-397">source</a><h4 class="code-header">fn <a href="#method.inspect" class="fn">inspect</a><F>(self, f: F) -> <a class="struct" href="struct.Inspect.html" title="struct futures_util::future::Inspect">Inspect</a><Self, F> <a href="#" class="tooltip" data-notable-ty="Inspect<Self, F>">ⓘ</a><div class="where">where
|
|||
|
|
F: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/ops/function/trait.FnOnce.html" title="trait core::ops::function::FnOnce">FnOnce</a>(&Self::<a class="associatedtype" href="https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html#associatedtype.Output" title="type core::future::future::Future::Output">Output</a>),
|
|||
|
|
Self: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h4></section></summary><div class="docblock"><p>Do something with the output of a future before passing it on.</p>
|
|||
|
|
<p>When using futures, you’ll often chain several of them together. While
|
|||
|
|
working on such code, you might want to check out what’s happening at
|
|||
|
|
various parts in the pipeline, without consuming the intermediate
|
|||
|
|
value. To do that, insert a call to <code>inspect</code>.</p>
|
|||
|
|
<h5 id="examples-7"><a class="doc-anchor" href="#examples-7">§</a>Examples</h5>
|
|||
|
|
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>futures::future::FutureExt;
|
|||
|
|
|
|||
|
|
<span class="kw">let </span>future = <span class="kw">async </span>{ <span class="number">1 </span>};
|
|||
|
|
<span class="kw">let </span>new_future = future.inspect(|<span class="kw-2">&</span>x| <span class="macro">println!</span>(<span class="string">"about to resolve: {}"</span>, x));
|
|||
|
|
<span class="macro">assert_eq!</span>(new_future.<span class="kw">await</span>, <span class="number">1</span>);</code></pre></div>
|
|||
|
|
</div></details><details class="toggle method-toggle" open><summary><section id="method.unit_error" class="method"><a class="src rightside" href="../../src/futures_util/future/future/mod.rs.html#537-542">source</a><h4 class="code-header">fn <a href="#method.unit_error" class="fn">unit_error</a>(self) -> <a class="struct" href="struct.UnitError.html" title="struct futures_util::future::UnitError">UnitError</a><Self> <a href="#" class="tooltip" data-notable-ty="UnitError<Self>">ⓘ</a><div class="where">where
|
|||
|
|
Self: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h4></section></summary><div class="docblock"><p>Turns a <a href="https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html" title="trait core::future::future::Future"><code>Future<Output = T></code></a> into a
|
|||
|
|
<a href="trait.TryFuture.html" title="trait futures_util::future::TryFuture"><code>TryFuture<Ok = T, Error = ()</code>></a>.</p>
|
|||
|
|
</div></details><details class="toggle method-toggle" open><summary><section id="method.never_error" class="method"><a class="src rightside" href="../../src/futures_util/future/future/mod.rs.html#546-551">source</a><h4 class="code-header">fn <a href="#method.never_error" class="fn">never_error</a>(self) -> <a class="struct" href="struct.NeverError.html" title="struct futures_util::future::NeverError">NeverError</a><Self> <a href="#" class="tooltip" data-notable-ty="NeverError<Self>">ⓘ</a><div class="where">where
|
|||
|
|
Self: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h4></section></summary><div class="docblock"><p>Turns a <a href="https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html" title="trait core::future::future::Future"><code>Future<Output = T></code></a> into a
|
|||
|
|
<a href="trait.TryFuture.html" title="trait futures_util::future::TryFuture"><code>TryFuture<Ok = T, Error = Never</code>></a>.</p>
|
|||
|
|
</div></details><details class="toggle method-toggle" open><summary><section id="method.poll_unpin" class="method"><a class="src rightside" href="../../src/futures_util/future/future/mod.rs.html#554-559">source</a><h4 class="code-header">fn <a href="#method.poll_unpin" class="fn">poll_unpin</a>(&mut self, cx: &mut <a class="struct" href="https://doc.rust-lang.org/1.83.0/core/task/wake/struct.Context.html" title="struct core::task::wake::Context">Context</a><'_>) -> <a class="enum" href="https://doc.rust-lang.org/1.83.0/core/task/poll/enum.Poll.html" title="enum core::task::poll::Poll">Poll</a><Self::<a class="associatedtype" href="https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html#associatedtype.Output" title="type core::future::future::Future::Output">Output</a>><div class="where">where
|
|||
|
|
Self: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/marker/trait.Unpin.html" title="trait core::marker::Unpin">Unpin</a>,</div></h4></section></summary><div class="docblock"><p>A convenience for calling <code>Future::poll</code> on <code>Unpin</code> future types.</p>
|
|||
|
|
</div></details><details class="toggle method-toggle" open><summary><section id="method.now_or_never" class="method"><a class="src rightside" href="../../src/futures_util/future/future/mod.rs.html#592-605">source</a><h4 class="code-header">fn <a href="#method.now_or_never" class="fn">now_or_never</a>(self) -> <a class="enum" href="https://doc.rust-lang.org/1.83.0/core/option/enum.Option.html" title="enum core::option::Option">Option</a><Self::<a class="associatedtype" href="https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html#associatedtype.Output" title="type core::future::future::Future::Output">Output</a>><div class="where">where
|
|||
|
|
Self: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h4></section></summary><div class="docblock"><p>Evaluates and consumes the future, returning the resulting output if
|
|||
|
|
the future is ready after the first call to <code>Future::poll</code>.</p>
|
|||
|
|
<p>If <code>poll</code> instead returns <code>Poll::Pending</code>, <code>None</code> is returned.</p>
|
|||
|
|
<p>This method is useful in cases where immediacy is more important than
|
|||
|
|
waiting for a result. It is also convenient for quickly obtaining
|
|||
|
|
the value of a future that is known to always resolve immediately.</p>
|
|||
|
|
<h5 id="examples-8"><a class="doc-anchor" href="#examples-8">§</a>Examples</h5>
|
|||
|
|
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>futures::{future::ready, future::pending};
|
|||
|
|
<span class="kw">let </span>future_ready = ready(<span class="string">"foobar"</span>);
|
|||
|
|
<span class="kw">let </span>future_pending = pending::<<span class="kw-2">&</span><span class="lifetime">'static </span>str>();
|
|||
|
|
|
|||
|
|
<span class="macro">assert_eq!</span>(future_ready.now_or_never(), <span class="prelude-val">Some</span>(<span class="string">"foobar"</span>));
|
|||
|
|
<span class="macro">assert_eq!</span>(future_pending.now_or_never(), <span class="prelude-val">None</span>);</code></pre></div>
|
|||
|
|
<p>In cases where it is absolutely known that a future should always
|
|||
|
|
resolve immediately and never return <code>Poll::Pending</code>, this method can
|
|||
|
|
be combined with <code>expect()</code>:</p>
|
|||
|
|
|
|||
|
|
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span>future_ready = ready(<span class="string">"foobar"</span>);
|
|||
|
|
|
|||
|
|
<span class="macro">assert_eq!</span>(future_ready.now_or_never().expect(<span class="string">"Future not ready"</span>), <span class="string">"foobar"</span>);</code></pre></div>
|
|||
|
|
</div></details></div><h2 id="implementors" class="section-header">Implementors<a href="#implementors" class="anchor">§</a></h2><div id="implementors-list"><section id="impl-FutureExt-for-T" class="impl"><a class="src rightside" href="../../src/futures_util/future/future/mod.rs.html#119">source</a><a href="#impl-FutureExt-for-T" class="anchor">§</a><h3 class="code-header">impl<T> <a class="trait" href="trait.FutureExt.html" title="trait futures_util::future::FutureExt">FutureExt</a> for T<div class="where">where
|
|||
|
|
T: <a class="trait" href="https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html" title="trait core::future::future::Future">Future</a> + ?<a class="trait" href="https://doc.rust-lang.org/1.83.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h3></section></div><script src="../../trait.impl/futures_util/future/future/trait.FutureExt.js" async></script><script type="text/json" id="notable-traits-data">{"Either<A, Self>":"<h3>Notable traits for <code><a class=\"enum\" href=\"enum.Either.html\" title=\"enum futures_util::future::Either\">Either</a><A, B></code></h3><pre><code><div class=\"where\">impl<A, B> <a class=\"trait\" href=\"https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html\" title=\"trait core::future::future::Future\">Future</a> for <a class=\"enum\" href=\"enum.Either.html\" title=\"enum futures_util::future::Either\">Either</a><A, B><div class=\"where\">where\n A: <a class=\"trait\" href=\"https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html\" title=\"trait core::future::future::Future\">Future</a>,\n B: <a class=\"trait\" href=\"https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html\" title=\"trait core::future::future::Future\">Future</a><Output = A::<a class=\"associatedtype\" href=\"https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html#associatedtype.Output\" title=\"type core::future::future::Future::Output\">Output</a>>,</div></div><div class=\"where\"> type <a href=\"https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html#associatedtype.Output\" class=\"associatedtype\">Output</a> = A::<a class=\"associatedtype\" href=\"https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html#associatedtype.Output\" title=\"type core::future::future::Future::Output\">Output</a>;</div>","Either<Self, B>":"<h3>Notable traits for <code><a class=\"enum\" href=\"enum.Either.html\" title=\"enum futures_util::future::Either\">Either</a><A, B></code></h3><pre><code><div class=\"where\">impl<A, B> <a class=\"trait\" href=\"https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html\" title=\"trait core::future::future::Future\">Future</a> for <a class=\"enum\" href=\"enum.Either.html\" title=\"enum futures_util::future::Either\">Either</a><A, B><div class=\"where\">where\n A: <a class=\"trait\" href=\"https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html\" title=\"trait core::future::future::Future\">Future</a>,\n B: <a class=\"trait\" href=\"https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html\" title=\"trait core::future::future::Future\">Future</a><Output = A::<a class=\"associatedtype\" href=\"https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html#associatedtype.Output\" title=\"type core::future::future::Future::Output\">Output</a>>,</div></div><div class=\"where\"> type <a href=\"https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html#associatedtype.Output\" class=\"associatedtype\">Output</a> = A::<a class=\"associatedtype\" href=\"https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html#associatedtype.Output\" title=\"type core::future::future::Future::Output\">Output</a>;</div>","Flatten<Self>":"<h3>Notable traits for <code><a class=\"struct\" href=\"struct.Flatten.html\" title=\"struct futures_util::future::Flatten\">Flatten</a><F></code></h3><pre><code><div class=\"where\">impl<F> <a class=\"trait\" href=\"https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html\" title=\"trait core::future::future::Future\">Future</a> for <a class=\"struct\" href=\"struct.Flatten.html\" title=\"struct futures_util::future::Flatten\">Flatten</a><F><div class=\"where\">where\n Flatten<F, <F as <a class=\"trait\" href=\"https://doc.rust-lang.org/1.83.0/core/future/future/trait.Future.html\" title=\"trait core::future::future::Future\">Future</a>>::<a class=\"associatedtype\" href=\"https://doc.rust-lan
|