RONCC
/
HPC-Tools-for-Quantum-Computing


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382
							<!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 `futures` crate.">
    <meta name="keywords" content="rust, rustlang, rust-lang, futures">

    <title>futures - Rust</title>

    <link rel="stylesheet" type="text/css" href="../normalize.css">
    <link rel="stylesheet" type="text/css" href="../rustdoc.css" id="mainThemeStyle">
    
    <link rel="stylesheet" type="text/css" href="../dark.css">
    <link rel="stylesheet" type="text/css" href="../main.css" id="themeStyle">
    <script src="../storage.js"></script>
    

    
    
</head>
<body class="rustdoc mod">
    <!--[if lte IE 8]>
    <div class="warning">
        This old browser is unsupported and will most likely display funky
        things.
    </div>
    <![endif]-->

    

    <nav class="sidebar">
        <div class="sidebar-menu">&#9776;</div>
        
        <p class='location'>Crate futures</p><div class="sidebar-elems"><div class="block items"><ul><li><a href="#reexports">Re-exports</a></li><li><a href="#modules">Modules</a></li><li><a href="#macros">Macros</a></li><li><a href="#enums">Enums</a></li><li><a href="#types">Type Definitions</a></li></ul></div><p class='location'></p><script>window.sidebarCurrent = {name: 'futures', ty: 'mod', relpath: '../'};</script></div>
    </nav>

    <div class="theme-picker">
        <button id="theme-picker" aria-label="Pick another theme!">
            <img src="../brush.svg" width="18" alt="Pick another theme!">
        </button>
        <div id="theme-choices"></div>
    </div>
    <script src="../theme.js"></script>
    <nav class="sub">
        <form class="search-form js-only">
            <div class="search-container">
                <input class="search-input" name="search"
                       autocomplete="off"
                       placeholder="Click or press ‘S’ to search, ‘?’ for more options…"
                       type="search">
            </div>
        </form>
    </nav>

    <section id='main' class="content">
<h1 class='fqn'><span class='in-band'>Crate <a class="mod" href=''>futures</a></span><span class='out-of-band'><span id='render-detail'>
                   <a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">
                       [<span class='inner'>&#x2212;</span>]
                   </a>
               </span><a class='srclink' href='../src/futures/lib.rs.html#1-265' title='goto source code'>[src]</a></span></h1>
<div class='docblock'><p>Zero-cost Futures in Rust</p>
<p>This library is an implementation of futures in Rust which aims to provide
a robust implementation of handling asynchronous computations, ergonomic
composition and usage, and zero-cost abstractions over what would otherwise
be written by hand.</p>
<p>Futures are a concept for an object which is a proxy for another value that
may not be ready yet. For example issuing an HTTP request may return a
future for the HTTP response, as it probably hasn't arrived yet. With an
object representing a value that will eventually be available, futures allow
for powerful composition of tasks through basic combinators that can perform
operations like chaining computations, changing the types of futures, or
waiting for two futures to complete at the same time.</p>
<p>You can find extensive tutorials and documentations at <a href="https://tokio.rs">https://tokio.rs</a>
for both this crate (asynchronous programming in general) as well as the
Tokio stack to perform async I/O with.</p>
<h2 id="installation" class="section-header"><a href="#installation">Installation</a></h2>
<p>Add this to your <code>Cargo.toml</code>:</p>
<pre><code class="language-toml">[dependencies]
futures = &quot;0.1&quot;
</code></pre>
<h2 id="examples" class="section-header"><a href="#examples">Examples</a></h2>
<p>Let's take a look at a few examples of how futures might be used:</p>

<pre class="rust rust-example-rendered">
<span class="kw">extern</span> <span class="kw">crate</span> <span class="ident">futures</span>;

<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">io</span>;
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">time</span>::<span class="ident">Duration</span>;
<span class="kw">use</span> <span class="ident">futures</span>::<span class="ident">prelude</span>::<span class="kw-2">*</span>;
<span class="kw">use</span> <span class="ident">futures</span>::<span class="ident">future</span>::<span class="ident">Map</span>;

<span class="comment">// A future is actually a trait implementation, so we can generically take a</span>
<span class="comment">// future of any integer and return back a future that will resolve to that</span>
<span class="comment">// value plus 10 more.</span>
<span class="comment">//</span>
<span class="comment">// Note here that like iterators, we&#39;re returning the `Map` combinator in</span>
<span class="comment">// the futures crate, not a boxed abstraction. This is a zero-cost</span>
<span class="comment">// construction of a future.</span>
<span class="kw">fn</span> <span class="ident">add_ten</span><span class="op">&lt;</span><span class="ident">F</span><span class="op">&gt;</span>(<span class="ident">future</span>: <span class="ident">F</span>) <span class="op">-&gt;</span> <span class="ident">Map</span><span class="op">&lt;</span><span class="ident">F</span>, <span class="kw">fn</span>(<span class="ident">i32</span>) <span class="op">-&gt;</span> <span class="ident">i32</span><span class="op">&gt;</span>
    <span class="kw">where</span> <span class="ident">F</span>: <span class="ident">Future</span><span class="op">&lt;</span><span class="ident">Item</span><span class="op">=</span><span class="ident">i32</span><span class="op">&gt;</span>,
{
    <span class="kw">fn</span> <span class="ident">add</span>(<span class="ident">a</span>: <span class="ident">i32</span>) <span class="op">-&gt;</span> <span class="ident">i32</span> { <span class="ident">a</span> <span class="op">+</span> <span class="number">10</span> }
    <span class="ident">future</span>.<span class="ident">map</span>(<span class="ident">add</span>)
}

<span class="comment">// Not only can we modify one future, but we can even compose them together!</span>
<span class="comment">// Here we have a function which takes two futures as input, and returns a</span>
<span class="comment">// future that will calculate the sum of their two values.</span>
<span class="comment">//</span>
<span class="comment">// Above we saw a direct return value of the `Map` combinator, but</span>
<span class="comment">// performance isn&#39;t always critical and sometimes it&#39;s more ergonomic to</span>
<span class="comment">// return a trait object like we do here. Note though that there&#39;s only one</span>
<span class="comment">// allocation here, not any for the intermediate futures.</span>
<span class="kw">fn</span> <span class="ident">add</span><span class="op">&lt;</span><span class="lifetime">&#39;a</span>, <span class="ident">A</span>, <span class="ident">B</span><span class="op">&gt;</span>(<span class="ident">a</span>: <span class="ident">A</span>, <span class="ident">b</span>: <span class="ident">B</span>) <span class="op">-&gt;</span> <span class="ident">Box</span><span class="op">&lt;</span><span class="ident">Future</span><span class="op">&lt;</span><span class="ident">Item</span><span class="op">=</span><span class="ident">i32</span>, <span class="ident">Error</span><span class="op">=</span><span class="ident">A</span>::<span class="ident">Error</span><span class="op">&gt;</span> <span class="op">+</span> <span class="lifetime">&#39;a</span><span class="op">&gt;</span>
    <span class="kw">where</span> <span class="ident">A</span>: <span class="ident">Future</span><span class="op">&lt;</span><span class="ident">Item</span><span class="op">=</span><span class="ident">i32</span><span class="op">&gt;</span> <span class="op">+</span> <span class="lifetime">&#39;a</span>,
          <span class="ident">B</span>: <span class="ident">Future</span><span class="op">&lt;</span><span class="ident">Item</span><span class="op">=</span><span class="ident">i32</span>, <span class="ident">Error</span><span class="op">=</span><span class="ident">A</span>::<span class="ident">Error</span><span class="op">&gt;</span> <span class="op">+</span> <span class="lifetime">&#39;a</span>,
{
    <span class="ident">Box</span>::<span class="ident">new</span>(<span class="ident">a</span>.<span class="ident">join</span>(<span class="ident">b</span>).<span class="ident">map</span>(<span class="op">|</span>(<span class="ident">a</span>, <span class="ident">b</span>)<span class="op">|</span> <span class="ident">a</span> <span class="op">+</span> <span class="ident">b</span>))
}

<span class="comment">// Futures also allow chaining computations together, starting another after</span>
<span class="comment">// the previous finishes. Here we wait for the first computation to finish,</span>
<span class="comment">// and then decide what to do depending on the result.</span>
<span class="kw">fn</span> <span class="ident">download_timeout</span>(<span class="ident">url</span>: <span class="kw-2">&amp;</span><span class="ident">str</span>,
                    <span class="ident">timeout_dur</span>: <span class="ident">Duration</span>)
                    <span class="op">-&gt;</span> <span class="ident">Box</span><span class="op">&lt;</span><span class="ident">Future</span><span class="op">&lt;</span><span class="ident">Item</span><span class="op">=</span><span class="ident">Vec</span><span class="op">&lt;</span><span class="ident">u8</span><span class="op">&gt;</span>, <span class="ident">Error</span><span class="op">=</span><span class="ident">io</span>::<span class="ident">Error</span><span class="op">&gt;&gt;</span> {
    <span class="kw">use</span> <span class="ident">std</span>::<span class="ident">io</span>;
    <span class="kw">use</span> <span class="ident">std</span>::<span class="ident">net</span>::{<span class="ident">SocketAddr</span>, <span class="ident">TcpStream</span>};

    <span class="kw">type</span> <span class="ident">IoFuture</span><span class="op">&lt;</span><span class="ident">T</span><span class="op">&gt;</span> <span class="op">=</span> <span class="ident">Box</span><span class="op">&lt;</span><span class="ident">Future</span><span class="op">&lt;</span><span class="ident">Item</span><span class="op">=</span><span class="ident">T</span>, <span class="ident">Error</span><span class="op">=</span><span class="ident">io</span>::<span class="ident">Error</span><span class="op">&gt;&gt;</span>;

    <span class="comment">// First thing to do is we need to resolve our URL to an address. This</span>
    <span class="comment">// will likely perform a DNS lookup which may take some time.</span>
    <span class="kw">let</span> <span class="ident">addr</span> <span class="op">=</span> <span class="ident">resolve</span>(<span class="ident">url</span>);

    <span class="comment">// After we acquire the address, we next want to open up a TCP</span>
    <span class="comment">// connection.</span>
    <span class="kw">let</span> <span class="ident">tcp</span> <span class="op">=</span> <span class="ident">addr</span>.<span class="ident">and_then</span>(<span class="op">|</span><span class="ident">addr</span><span class="op">|</span> <span class="ident">connect</span>(<span class="kw-2">&amp;</span><span class="ident">addr</span>));

    <span class="comment">// After the TCP connection is established and ready to go, we&#39;re off to</span>
    <span class="comment">// the races!</span>
    <span class="kw">let</span> <span class="ident">data</span> <span class="op">=</span> <span class="ident">tcp</span>.<span class="ident">and_then</span>(<span class="op">|</span><span class="ident">conn</span><span class="op">|</span> <span class="ident">download</span>(<span class="ident">conn</span>));

    <span class="comment">// That all might take awhile, though, so let&#39;s not wait too long for it</span>
    <span class="comment">// to all come back. The `select` combinator here returns a future which</span>
    <span class="comment">// resolves to the first value that&#39;s ready plus the next future.</span>
    <span class="comment">//</span>
    <span class="comment">// Note we can also use the `then` combinator which is similar to</span>
    <span class="comment">// `and_then` above except that it receives the result of the</span>
    <span class="comment">// computation, not just the successful value.</span>
    <span class="comment">//</span>
    <span class="comment">// Again note that all the above calls to `and_then` and the below calls</span>
    <span class="comment">// to `map` and such require no allocations. We only ever allocate once</span>
    <span class="comment">// we hit the `Box::new()` call at the end here, which means we&#39;ve built</span>
    <span class="comment">// up a relatively involved computation with only one box, and even that</span>
    <span class="comment">// was optional!</span>

    <span class="kw">let</span> <span class="ident">data</span> <span class="op">=</span> <span class="ident">data</span>.<span class="ident">map</span>(<span class="prelude-val">Ok</span>);
    <span class="kw">let</span> <span class="ident">timeout</span> <span class="op">=</span> <span class="ident">timeout</span>(<span class="ident">timeout_dur</span>).<span class="ident">map</span>(<span class="prelude-val">Err</span>);

    <span class="kw">let</span> <span class="ident">ret</span> <span class="op">=</span> <span class="ident">data</span>.<span class="ident">select</span>(<span class="ident">timeout</span>).<span class="ident">then</span>(<span class="op">|</span><span class="ident">result</span><span class="op">|</span> {
        <span class="kw">match</span> <span class="ident">result</span> {
            <span class="comment">// One future succeeded, and it was the one which was</span>
            <span class="comment">// downloading data from the connection.</span>
            <span class="prelude-val">Ok</span>((<span class="prelude-val">Ok</span>(<span class="ident">data</span>), <span class="ident">_other_future</span>)) <span class="op">=&gt;</span> <span class="prelude-val">Ok</span>(<span class="ident">data</span>),

            <span class="comment">// The timeout fired, and otherwise no error was found, so</span>
            <span class="comment">// we translate this to an error.</span>
            <span class="prelude-val">Ok</span>((<span class="prelude-val">Err</span>(<span class="ident">_timeout</span>), <span class="ident">_other_future</span>)) <span class="op">=&gt;</span> {
                <span class="prelude-val">Err</span>(<span class="ident">io</span>::<span class="ident">Error</span>::<span class="ident">new</span>(<span class="ident">io</span>::<span class="ident">ErrorKind</span>::<span class="ident">Other</span>, <span class="string">&quot;timeout&quot;</span>))
            }

            <span class="comment">// A normal I/O error happened, so we pass that on through.</span>
            <span class="prelude-val">Err</span>((<span class="ident">e</span>, <span class="ident">_other_future</span>)) <span class="op">=&gt;</span> <span class="prelude-val">Err</span>(<span class="ident">e</span>),
        }
    });
    <span class="kw">return</span> <span class="ident">Box</span>::<span class="ident">new</span>(<span class="ident">ret</span>);

    <span class="kw">fn</span> <span class="ident">resolve</span>(<span class="ident">url</span>: <span class="kw-2">&amp;</span><span class="ident">str</span>) <span class="op">-&gt;</span> <span class="ident">IoFuture</span><span class="op">&lt;</span><span class="ident">SocketAddr</span><span class="op">&gt;</span> {
        <span class="comment">// ...</span>
    }

    <span class="kw">fn</span> <span class="ident">connect</span>(<span class="ident">hostname</span>: <span class="kw-2">&amp;</span><span class="ident">SocketAddr</span>) <span class="op">-&gt;</span> <span class="ident">IoFuture</span><span class="op">&lt;</span><span class="ident">TcpStream</span><span class="op">&gt;</span> {
        <span class="comment">// ...</span>
    }

    <span class="kw">fn</span> <span class="ident">download</span>(<span class="ident">stream</span>: <span class="ident">TcpStream</span>) <span class="op">-&gt;</span> <span class="ident">IoFuture</span><span class="op">&lt;</span><span class="ident">Vec</span><span class="op">&lt;</span><span class="ident">u8</span><span class="op">&gt;&gt;</span> {
        <span class="comment">// ...</span>
    }

    <span class="kw">fn</span> <span class="ident">timeout</span>(<span class="ident">stream</span>: <span class="ident">Duration</span>) <span class="op">-&gt;</span> <span class="ident">IoFuture</span><span class="op">&lt;</span>()<span class="op">&gt;</span> {
        <span class="comment">// ...</span>
    }
}</pre>
<p>Some more information can also be found in the <a href="https://github.com/rust-lang-nursery/futures-rs#futures-rs">README</a> for now, but
otherwise feel free to jump in to the docs below!</p>
</div><h2 id='reexports' class='section-header'><a href="#reexports">Re-exports</a></h2>
<table><tr><td><code>pub use future::<a class="trait" href="../futures/future/trait.Future.html" title="trait futures::future::Future">Future</a>;</code></td></tr><tr><td><code>pub use future::<a class="trait" href="../futures/future/trait.IntoFuture.html" title="trait futures::future::IntoFuture">IntoFuture</a>;</code></td></tr><tr><td><code>pub use stream::<a class="trait" href="../futures/stream/trait.Stream.html" title="trait futures::stream::Stream">Stream</a>;</code></td></tr><tr><td><code>pub use sink::<a class="trait" href="../futures/sink/trait.Sink.html" title="trait futures::sink::Sink">Sink</a>;</code></td></tr></table><h2 id='modules' class='section-header'><a href="#modules">Modules</a></h2>
<table>
                       <tr class=' module-item'>
                           <td><a class="mod" href="executor/index.html"
                                  title='mod futures::executor'>executor</a></td>
                           <td class='docblock-short'>
                                <p>Executors</p>

                           </td>
                       </tr>
                       <tr class=' module-item'>
                           <td><a class="mod" href="future/index.html"
                                  title='mod futures::future'>future</a></td>
                           <td class='docblock-short'>
                                <p>Futures</p>

                           </td>
                       </tr>
                       <tr class=' module-item'>
                           <td><a class="mod" href="prelude/index.html"
                                  title='mod futures::prelude'>prelude</a></td>
                           <td class='docblock-short'>
                                <p>A &quot;prelude&quot; for crates using the <code>futures</code> crate.</p>

                           </td>
                       </tr>
                       <tr class=' module-item'>
                           <td><a class="mod" href="sink/index.html"
                                  title='mod futures::sink'>sink</a></td>
                           <td class='docblock-short'>
                                <p>Asynchronous sinks</p>

                           </td>
                       </tr>
                       <tr class=' module-item'>
                           <td><a class="mod" href="stream/index.html"
                                  title='mod futures::stream'>stream</a></td>
                           <td class='docblock-short'>
                                <p>Asynchronous streams</p>

                           </td>
                       </tr>
                       <tr class=' module-item'>
                           <td><a class="mod" href="sync/index.html"
                                  title='mod futures::sync'>sync</a></td>
                           <td class='docblock-short'>
                                <p>Future-aware synchronization</p>

                           </td>
                       </tr>
                       <tr class=' module-item'>
                           <td><a class="mod" href="task/index.html"
                                  title='mod futures::task'>task</a></td>
                           <td class='docblock-short'>
                                <p>Tasks used to drive a future computation</p>

                           </td>
                       </tr>
                       <tr class=' module-item'>
                           <td><a class="mod" href="unsync/index.html"
                                  title='mod futures::unsync'>unsync</a></td>
                           <td class='docblock-short'>
                                <p>Future-aware single-threaded synchronization</p>

                           </td>
                       </tr></table><h2 id='macros' class='section-header'><a href="#macros">Macros</a></h2>
<table>
                       <tr class=' module-item'>
                           <td><a class="macro" href="macro.task_local.html"
                                  title='macro futures::task_local'>task_local</a></td>
                           <td class='docblock-short'>
                                <p>A macro to create a <code>static</code> of type <code>LocalKey</code></p>

                           </td>
                       </tr>
                       <tr class=' module-item'>
                           <td><a class="macro" href="macro.try_ready.html"
                                  title='macro futures::try_ready'>try_ready</a></td>
                           <td class='docblock-short'>
                                <p>A macro for extracting the successful type of a <code>Poll&lt;T, E&gt;</code>.</p>

                           </td>
                       </tr></table><h2 id='enums' class='section-header'><a href="#enums">Enums</a></h2>
<table>
                       <tr class=' module-item'>
                           <td><a class="enum" href="enum.Async.html"
                                  title='enum futures::Async'>Async</a></td>
                           <td class='docblock-short'>
                                <p>Return type of future, indicating whether a value is ready or not.</p>

                           </td>
                       </tr>
                       <tr class=' module-item'>
                           <td><a class="enum" href="enum.AsyncSink.html"
                                  title='enum futures::AsyncSink'>AsyncSink</a></td>
                           <td class='docblock-short'>
                                <p>The result of an asynchronous attempt to send a value to a sink.</p>

                           </td>
                       </tr></table><h2 id='types' class='section-header'><a href="#types">Type Definitions</a></h2>
<table>
                       <tr class=' module-item'>
                           <td><a class="type" href="type.Poll.html"
                                  title='type futures::Poll'>Poll</a></td>
                           <td class='docblock-short'>
                                <p>Return type of the <code>Future::poll</code> method, indicates whether a future's value
is ready or not.</p>

                           </td>
                       </tr>
                       <tr class=' module-item'>
                           <td><a class="type" href="type.StartSend.html"
                                  title='type futures::StartSend'>StartSend</a></td>
                           <td class='docblock-short'>
                                <p>Return type of the <code>Sink::start_send</code> method, indicating the outcome of a
send attempt. See <code>AsyncSink</code> for more details.</p>

                           </td>
                       </tr></table></section>
    <section id='search' class="content hidden"></section>

    <section class="footer"></section>

    <aside id="help" class="hidden">
        <div>
            <h1 class="hidden">Help</h1>

            <div class="shortcuts">
                <h2>Keyboard Shortcuts</h2>

                <dl>
                    <dt><kbd>?</kbd></dt>
                    <dd>Show this help dialog</dd>
                    <dt><kbd>S</kbd></dt>
                    <dd>Focus the search field</dd>
                    <dt><kbd>↑</kbd></dt>
                    <dd>Move up in search results</dd>
                    <dt><kbd>↓</kbd></dt>
                    <dd>Move down in search results</dd>
                    <dt><kbd>↹</kbd></dt>
                    <dd>Switch tab</dd>
                    <dt><kbd>&#9166;</kbd></dt>
                    <dd>Go to active search result</dd>
                    <dt><kbd>+</kbd></dt>
                    <dd>Expand all sections</dd>
                    <dt><kbd>-</kbd></dt>
                    <dd>Collapse all sections</dd>
                </dl>
            </div>

            <div class="infos">
                <h2>Search Tricks</h2>

                <p>
                    Prefix searches with a type followed by a colon (e.g.
                    <code>fn:</code>) to restrict the search to a given type.
                </p>

                <p>
                    Accepted types are: <code>fn</code>, <code>mod</code>,
                    <code>struct</code>, <code>enum</code>,
                    <code>trait</code>, <code>type</code>, <code>macro</code>,
                    and <code>const</code>.
                </p>

                <p>
                    Search functions by type signature (e.g.
                    <code>vec -> usize</code> or <code>* -> vec</code>)
                </p>
            </div>
        </div>
    </aside>

    

    <script>
        window.rootPath = "../";
        window.currentCrate = "futures";
    </script>
    <script src="../main.js"></script>
    <script defer src="../search-index.js"></script>
</body>
</html>