- 
- {{ page.title | escape }}
+
+ {{ content }}
+
+
+
- 
-
- Zero-cost asynchronous programming in Rust -
+## Developing locally - - -- - Documentation - | - Website - -
- -`futures-rs` is a library providing the foundations for asynchronous programming in Rust. -It includes key trait definitions like `Stream`, as well as utilities like `join!`, -`select!`, and various futures combinator methods which enable expressive asynchronous -control flow. - -## Usage - -Add this to your `Cargo.toml`: - -```toml -[dependencies] -futures = "0.3" ``` - -The current `futures` requires Rust 1.68 or later. - -### Feature `std` - -Futures-rs works without the standard library, such as in bare metal environments. -However, it has a significantly reduced API surface. To use futures-rs in -a `#[no_std]` environment, use: - -```toml -[dependencies] -futures = { version = "0.3", default-features = false } +> bundle install +> bundle exec jekyll serve ``` - -## License - -Licensed under either of [Apache License, Version 2.0](LICENSE-APACHE) or -[MIT license](LICENSE-MIT) at your option. - -Unless you explicitly state otherwise, any contribution intentionally submitted -for inclusion in the work by you, as defined in the Apache-2.0 license, shall -be dual licensed as above, without any additional terms or conditions. diff --git a/_config.yml b/_config.yml new file mode 100644 index 0000000000..11f12e2c8a --- /dev/null +++ b/_config.yml @@ -0,0 +1,32 @@ +title: Futures-rs +baseurl: "/futures-rs" +url: "https://rust-lang-nursery.github.io" + +# Build settings +markdown: kramdown +kramdown: + syntax_highlighter: rouge + syntax_highlighter_opts: + default_lang: rust + css_class: 'highlight' + span: + line_numbers: false + block: + line_numbers: false +theme: minima +plugins: + - jekyll-feed +exclude: + - target # From Rust + +# Exclude from processing. +# The following items will not be processed, by default. Create a custom list +# to override the default setting. +# exclude: +# - Gemfile +# - Gemfile.lock +# - node_modules +# - vendor/bundle/ +# - vendor/cache/ +# - vendor/gems/ +# - vendor/ruby/ diff --git a/_includes/footer.html b/_includes/footer.html new file mode 100644 index 0000000000..4b1862e9a0 --- /dev/null +++ b/_includes/footer.html @@ -0,0 +1,9 @@ + diff --git a/_includes/header.html b/_includes/header.html new file mode 100644 index 0000000000..05d0aa94ce --- /dev/null +++ b/_includes/header.html @@ -0,0 +1,26 @@ +
+ {%- assign default_paths = site.pages | map: "path" -%}
+ {%- assign page_paths = site.header_pages | default: default_paths -%}
+
+ {%- if page.layout != "home" -%}
+
+ 
+
+ {%- endif -%}
+
+
+
+
+ API Docs
+
+
+
+ 
+ Code
+
+
+
+ {%- endif -%}
+
+
+
+
+ API Docs
+
+
+
+
+ Code
+
+
+
diff --git a/_layouts/default.html b/_layouts/default.html
new file mode 100644
index 0000000000..f3a6daa32d
--- /dev/null
+++ b/_layouts/default.html
@@ -0,0 +1,12 @@
+
+
+ {%- include head.html -%}
+
+
+ {%- include header.html -%}
+
+ {{ content }}
+
+ {%- include footer.html -%}
+
+
diff --git a/_layouts/home.html b/_layouts/home.html
new file mode 100644
index 0000000000..b811de0589
--- /dev/null
+++ b/_layouts/home.html
@@ -0,0 +1,43 @@
+---
+layout: default
+---
+
+
+
+
+
+
diff --git a/_layouts/post.html b/_layouts/post.html
new file mode 100644
index 0000000000..07f9c0d9af
--- /dev/null
+++ b/_layouts/post.html
@@ -0,0 +1,53 @@
+---
+layout: default
+---
+
+
+
+
+
+
diff --git a/_posts/2018-07-18-new-website.md b/_posts/2018-07-18-new-website.md
new file mode 100644
index 0000000000..2bb4022100
--- /dev/null
+++ b/_posts/2018-07-18-new-website.md
@@ -0,0 +1,17 @@
+---
+layout: post
+title: "New Website"
+author: "Josef Brandl"
+author_github: "MajorBreakfast"
+date: 2018-07-19 16:00
+categories: blog
+---
+
+
+## Welcome!
+
+Futures-rs now has a website and a logo. We hope you like it! This site contains our brand new blog with which we plan to keep you up-to-date about the project.
+
+Enjoy reading!
+
+*BTW The logo was inspired by a movie, we'll leave it up to the reader to guess which one :)*
diff --git a/_posts/2018-07-19-futures-0.3.0-alpha.1.md b/_posts/2018-07-19-futures-0.3.0-alpha.1.md
new file mode 100644
index 0000000000..79f4366412
--- /dev/null
+++ b/_posts/2018-07-19-futures-0.3.0-alpha.1.md
@@ -0,0 +1,155 @@
+---
+layout: post
+title: "Futures 0.3.0-alpha.1"
+subtitle: "Our first alpha"
+author: "Aaron Turon"
+author_github: "aturon"
+date: 2018-07-19 17:00
+categories: blog
+---
+
+Welcome to the inaugural post of the new futures-rs blog!
+
+After several months of work, we’re happy to announce an *alpha* release of the new edition of futures-rs, version 0.3. The immediate goal of this work is to support async/await notation ([with borrowing](http://aturon.github.io/2018/04/24/async-borrowing/)) in Rust itself, which has entailed significant changes to the futures crate.
+
+## TL;DR
+- The 0.3.0-alpha.1 release is available in the new `futures-preview` family of crates.
+- It requires a nightly compiler, and works with rustc’s new support for async/await notation.
+- Tokio and Hyper support is not yet available for 0.3.0-alpha.1, but that’s the next area of work.
+- Neither the futures crate nor async/await notation will be stabilized for the initial release of the Rust 2018 Edition.
+- Futures 0.1 continues to be maintained and is the primary way to write production async code today. We plan to continue maintaining 0.1 for some time after 0.3.0 is released, as well.
+
+In short, this alpha release sets the stage for kicking off integration and documentation, but is not yet widely usable.
+
+## The futures-preview crate
+
+We’re publishing a 0.3.0-alpha.1 release of futures today, but rather than doing it within the existing `futures` crate, we’re publishing within the new `futures-preview` family of crates. This allows us to more clearly signal that this version is a work in progress, and to keep crates.io and docs.rs pages pointing to the 0.1 series.
+
+In other words:
+
+
+- Futures 0.1 is the production-ready way to use futures today, and is actively maintained.
+- Ongoing work for async/await will live in the `futures-preview` crates until it is ready to be promoted to 0.3.0.
+
+## What is futures 0.3?
+### Async/await
+
+With futures 0.3 alpha, it is possible to use the new `async`/`await` notation that recently landed in nightly:
+
+```toml
+cargo-features = ["edition"]
+
+[package]
+edition = "2018"
+```
+
+```rust
+#![feature(async_await, await_macro)]
+
+use futures::executor::block_on;
+use futures::future::{self, FutureExt};
+
+fn main() {
+ block_on(async {
+ let fut = future::lazy(|_| vec![0, 1, 2, 3]);
+ let shared1 = fut.shared();
+ let shared2 = shared1.clone();
+
+ assert_eq!(await!(shared1).len(), 4);
+ assert_eq!(await!(shared2).len(), 4);
+ })
+}
+```
+
+The notation works as described in [the corresponding RFC](https://github.com/rust-lang/rfcs/pull/2394); more documentation for it is forthcoming. There are several open questions on this notation, but these are largely on hold until we have achieved integration with Tokio and Hyper, at which point more serious code can be written against the library.
+
+While we had originally hoped to ship async/await notation as part of Rust 2018, there’s no chance at this point of having adequate feedback and confidence to do so in time. However, the [Networking WG](https://github.com/rust-lang-nursery/net-wg/) plans to continue pushing hard in this space up to and after the Rust 2018 launch, to provide the strongest story on *nightly* Rust that we can, and to get us on a path for stabilization.
+
+### Ecosystem integration
+
+As of this writing, futures 0.3.0-alpha.1 is not integrated in any way with other libraries like Tokio or Hyper. Achieving such integration is a crucial part of getting real experience with the design and ultimately heading toward stabilization. The Futures Team intends to work closely with the Tokio Team to determine the best way forward here — either a shim crate for compatibility with futures 0.1, or direct integration via a feature-flag.
+
+This integration is our main next area of work, and we’d love to have help! If you’re interested in getting involved, drop by the #wg-net channel on [Discord](https://discord.gg/rust-lang).
+
+### Crate structure and relation to `std`
+
+To support the built-in async/await notation, the `Future` trait and associated machinery had to [move into the standard library](https://github.com/rust-lang/rfcs/pull/2418). As such, the futures 0.3.0-alpha.1 release just re-exports those definitions, and then adds a host of useful extras, including streams, sinks, I/O traits, and the various combinators.
+
+The overall organization of the crate is similar to the 0.2 release:
+
+
+[`futures-core-preview`](https://crates.io/crates/futures-core-preview)
+: This crate re-exports the futures-related items from `std`, and defines `Stream`, `TryFuture` and `TryStream`.
+
+[`futures-executor-preview`](https://crates.io/crates/futures-executor-preview)
+: This crate provides basic executors (a thread pool and a thread-local executor).
+
+[`futures-io-preview`](https://crates.io/crates/futures-io-preview)
+: This crate defines core traits for I/O.
+
+[`futures-sink-preview`](https://crates.io/crates/futures-sink-preview)
+: This crate defines the core `Sink` trait.
+
+[`futures-channel-preview`](https://crates.io/crates/futures-channel-preview)
+: This crate defines basic `Sync` channels with end points implementing `Future`, `Stream` or `Sink`.
+
+[`futures-util-preview`](https://crates.io/crates/futures-util-preview)
+: This crate defines a collection of extension traits with useful adapters (aka combinators).
+
+[`futures-preview`](https://crates.io/crates/futures-preview)
+: This crate is a “facade” combining and re-exporting all of the above crates for convenience.
+
+You can read more about the rationale for the breakdown into multiple crates in the [0.2 notes](http://aturon.github.io/2018/02/27/futures-0-2-RC/).
+
+### Changes from 0.2
+
+*Note: Changes between 0.1 and 0.2 are outlined in the [0.2 notes](http://aturon.github.io/2018/02/27/futures-0-2-RC/).*
+
+Aside from some minor structural changes, there are two major changes from the 0.2 release:
+
+- Using pinned types to support borrowing within async blocks.
+- Factoring out the `Error` type into separate traits (`TryFuture` and `TryStream`).
+
+Both of these changes are described and motivated in detail in [the companion RFC](https://github.com/rust-lang/rfcs/pull/2418).
+
+The RFC, however, covers only the core `Future` trait and executor system. The bulk of the work in 0.3.0-alpha.1 has been pushing through these ideas through the rest of the crates, adapting the combinators and other traits to fit with pinning and the ability to borrow across yield points. For example, the [revised](https://github.com/rust-lang-nursery/futures-rs/blob/0.3/futures-util/src/io/mod.rs#L67-L74) `AsyncReadExt` trait now provides a `read` method that operates on borrowed data, just like in the `Read` trait in `std`:
+
+```rust
+trait AsyncReadExt: AsyncRead {
+ /// Tries to read some bytes directly into the given `buf` in asynchronous
+ /// manner, returning a future type.
+ ///
+ /// The returned future will resolve to the number of bytes read once the read
+ /// operation is completed.
+ fn read<'a>(&'a mut self, buf: &'a mut [u8]) -> Read<'a, Self> {
+ Read::new(self, buf)
+ }
+}
+```
+
+In contrast, the 0.1-style API must operate on *owned* buffers, which are threaded through the futures code. You can learn more about how this all works in [this blog post on borrowing and async/await](http://aturon.github.io/2018/04/24/async-borrowing/).
+
+## The road ahead
+
+While futures 0.3.0-alpha.1 is a major milestone, we still have a *ton* of work to do! The immediate next steps include:
+
+
+- Work out the integration story for Tokio, Hyper, and other important crates.
+- Write documentation for async/await notation.
+- Flesh out the migration path from futures 0.1 code.
+- Generally gain experience and feedback using this new design and async/await notation, so that we can get on track for stabilization.
+
+More generally, the futures team plans on communicating via this blog much more regularly about progress and ways to get involved. And now that the alpha is at the door, the broader [Networking WG](https://github.com/rust-lang-nursery/net-wg/) is hoping to reboot, bring in a lot more people, and start focusing on ecosystem concerns.
+
+As always, if you’re interested in getting involved in this space, reach out on #wg-net on [Discord](https://discord.gg/rust-lang).
+
+## Thank you!
+
+This alpha release is the result of work by a growing set of people contributing to the futures crate (some of whom have joined the team officially):
+
+- [@aturon](https://github.com/aturon)
+- [@cramertj](https://github.com/cramertj)
+- [@MajorBreakfast](https://github.com/MajorBreakfast)
+- [@Nemo157](https://github.com/Nemo157)
+- [@ngg](https://github.com/ngg)
+- [@tinaun](https://github.com/tinaun)
diff --git a/_posts/2018-07-30-futures-0.3.0-alpha.2.md b/_posts/2018-07-30-futures-0.3.0-alpha.2.md
new file mode 100644
index 0000000000..3b0413bba4
--- /dev/null
+++ b/_posts/2018-07-30-futures-0.3.0-alpha.2.md
@@ -0,0 +1,66 @@
+---
+layout: post
+title: "Futures 0.3.0-alpha.2"
+subtitle: "Task definition, `Try` impl for `Poll`"
+author: "Josef Brandl"
+author_github: "MajorBreakfast"
+date: 2018-07-30
+categories: blog
+---
+
+`0.3.0-alpha.2` requires a recent nightly (2018-07-29 or newer):
+```sh
+$ rustup update
+```
+
+## What's new?
+
+### Refined definition for "task"
+
+The documentation for the [`Executor`](https://doc.rust-lang.org/nightly/std/task/trait.Executor.html) trait was updated. It now defines a "task executor" like this:
+
+> Futures are polled until completion by tasks, a kind of lightweight "thread". A *task executor* is responsible for the creation of these tasks and the coordination of their execution on real operating system threads. In particular, whenever a task signals that it can make further progress via a wake-up notification, it is the responsibility of the task executor to put the task into a queue to continue executing it, i.e. polling the future in it, later.
+
+The notable difference to before is that the term "task" no longer refers to the future that the task runs. Instead, from now on, the term "task" only refers to the concept of a lightweight thread, a kind of thread that doesn't directly correspond to a thread provided by the operating system. This concept is sometimes also referred to as "green thread" - We, however, do not use either of these terms because they tend to cause confusion with real operating system threads. Instead, we call this concept a "task" and the thing that runs them a "task executor" or often just "executor".
+
+### `Try` impl for `Poll`
+
+`Poll>` now implements the [`Try`](https://doc.rust-lang.org/std/ops/trait.Try.html) trait. This means you can now do this:
+
+```rust
+fn poll(mut self: PinMut, cx: &mut task::Context) -> Poll> {
+ let poll: Poll> = self.future().poll();
+ let poll: Poll = poll?; // Returns early if there's an error
+ let ok_value: T = ready!(poll); // Returns early if the value is pending
+
+ // Or short:
+ let ok_value = ready!(self.future().poll()?);
+}
+```
+
+Additionally `Try` was also implemented for `Poll>>` to make the `?`-operator useful in `Stream::poll` implentations:
+
+```rust
+fn poll_next(mut self: PinMut, cx: &mut task::Context) -> Poll>> {
+ let poll: Poll>> = self.stream().poll_next();
+ let poll: Poll> = poll?; // Returns early if there's an error
+ let ok_item: Option = ready!(poll); // Returns early if the value is pending
+
+ // Or short:
+ let ok_item = ready!(self.stream().poll_next()?);
+}
+```
+
+You can find additional details about this change in the [pull request](https://github.com/rust-lang/rust/pull/52721).
+
+### Changes to futures-rs
+
+We revived the [changelog](https://github.com/rust-lang-nursery/futures-rs/blob/master/CHANGELOG.md)!
+
+No major changes happened to the futures crate since the last release. There were, however, numerous little changes. Take a look at the [changelog](https://github.com/rust-lang-nursery/futures-rs/blob/master/CHANGELOG.md) to get an overview.
+
+## What are we currently working on?
+
+### Compatiblity layer for futures 0.1
+
+We are currently working on an officially supported compatibility layer between `0.1` and `0.3`. This shim will make it possible to mix `0.1` futures with those from the 0.3 branch. The plan is to make it possible to use crates from the existing futures `0.1` ecosystem together with async functions and futures from the `0.3` crate. Additionally, this compatibility layer will also make it possible to gradually migrate exisiting applications and libraries to `0.3`. If you're curious, take a look the [compatibility layer PR](https://github.com/rust-lang-nursery/futures-rs/pull/1119) and the [issue](https://github.com/rust-lang-nursery/net-wg/issues/26) in the net-wg repository.
diff --git a/_posts/2018-08-15-futures-0.3.0-alpha.3.md b/_posts/2018-08-15-futures-0.3.0-alpha.3.md
new file mode 100644
index 0000000000..41dbb027bd
--- /dev/null
+++ b/_posts/2018-08-15-futures-0.3.0-alpha.3.md
@@ -0,0 +1,127 @@
+---
+layout: post
+title: "Futures 0.3.0-alpha.3"
+subtitle: "Compatibility layer, spawn improvements and `pin-utils` crate"
+author: "Josef Brandl"
+author_github: "MajorBreakfast"
+date: 2018-08-15
+categories: blog
+---
+
+`0.3.0-alpha.3` requires a recent nightly (2018-08-13 or newer):
+```sh
+$ rustup update
+```
+
+## Compatibility layer
+
+A compatibility layer between 0.3 and 0.1 was developed. It is now possible to convert an 0.3 future into an 0.1 future and vice versa. Similar conversions for streams and sinks are also supported. Additionally, it is now possible to run 0.3 futures and async functions on Tokio's executor. We have a dedicated blog post coming up that explains this in more detail.
+
+## Spawning
+
+### `Spawn` trait
+
+The `std::task::Executor` trait is now called `std::task::Spawn`. We chose to rename the trait to `Spawn` because the functionality exposed by this trait is not the ability to execute, but the ability to spawn.
+
+As a consequence of this renaming, some functions on `Context` were adjusted:
+```rust
+impl<'a> Context<'a> {
+ pub fn new(local_waker: &'a LocalWaker, spawner: &'a mut dyn Spawn) -> Context<'a> { ... }
+
+ pub fn spawner(&mut self) -> &mut dyn Spawn { ... }
+
+ pub fn with_spawner<'b, Sp: Spawn>(&'b mut self, spawner: &'b mut Sp) -> Context<'b> { ... }
+
+ // ...
+}
+```
+
+### Spawn macros
+
+This release of futures-rs introduces the `spawn!` and `spawn_with_handle!` macros for use in async functions, closures and blocks. Both macros let you spawn a task that polls the given future to completion. The task is spawned via the current context's spawner.
+
+`spawn!` lets you spawn futures with `Output = ()`:
+
+```rust
+#![feature(async_await, await_macro, futures_api)]
+use futures::spawn;
+
+spawn!(future).unwrap();
+```
+
+`spawn_with_handle!` lets you spawn futures with any `Output: Send` type and returns a future that resolves to the output of the spawned future:
+
+```rust
+use futures::spawn_with_handle;
+
+let join_handle = spawn_with_handle!(future).unwrap();
+let output = await!(join_handle);
+```
+
+`spawn!` is slightly cheaper than `spawn_with_handle!` since it doesn't need to provide a way to get the output.
+
+Should spawning fail, a `SpawnError` error is returned which contains information about why it failed.
+
+So what futures can be spawned? There are some requirements: The future needs to be `Send` and `'static` and the output needs to be `Send`. Here's why:
+- The `'static` lifetime means that the future cannot contain any non-static references. This is required so that the spawned task can be run independently to the task that spawns it.
+- The `Send` bounds mean that the future and its output can be sent to other threads. This is required so that multithreaded executors can run the spawned task on any thread they choose.
+
+Note: You can still execute non-`Send`, non-`'static` futures concurrently via the `join!` macro.
+
+### Spawn methods
+
+For use outside of async functions, there's also something new: The `SpawnExt` trait. It provides the methods `spawn` and `spawn_with_handle`:
+
+```rust
+use futures::task::SpawnExt;
+
+// spawn()
+spawner.spawn(future).unwrap();
+
+// spawn_with_handle()
+let join_handle = spawner.spawn_with_handle(future).unwrap();
+```
+
+Inside `poll`, you can use these methods by accessing the context's spawner via `Context::spawner`:
+
+```rust
+fn poll(self: PinMut, cx: &mut task::Context) -> Poll {
+ cx.spawner().spawn(future).unwrap();
+}
+```
+
+### The plan: `spawn` with `dyn Future`
+
+We plan to eventually replace `SpawnExt::spawn` with `Spawn::spawn`. This method will live directly in the `Spawn` trait defined in libcore. It's signature will look like this:
+
+```rust
+fn spawn(
+ &mut self,
+ future: dyn Future
+ 
+
+
+
+
+
+
+ Zero-cost asynchronous programming in Rust
+
+
+ {{ content }}
+
+ {%- if site.posts.size > 0 -%}
+
diff --git a/_layouts/page.html b/_layouts/page.html
new file mode 100644
index 0000000000..01e4b2a93b
--- /dev/null
+++ b/_layouts/page.html
@@ -0,0 +1,14 @@
+---
+layout: default
+---
+Blog Posts
+-
+ {%- for post in site.posts -%}
+
-
+ {%- assign date_format = site.minima.date_format | default: "%b %-d, %Y" -%}
+
+
+ + {{ post.title | markdownify }} + +
+{{ post.subtitle | markdownify }}+
+ {%- endfor -%}
+
+
+ 
+ RSS Feed
+
+
+ {%- endif -%}
+
+
+ RSS Feed
+
+ {{ page.title | escape }}
+ +
+ {{ content }}
+
+
+
+
+
+
+
+