Prepare for 0.3.0 release in conjunction with Rust 1.39

[cramertj]

This is intended to serve as a tracking issue for things that need to be resolved before the 0.3.0 release which will be published alongside Rust 1.39. This release will remove the -preview suffixes from all the current crates and release them under futures and futures-*.

[Matthias247]

I think @LucioFranco already raised the question in context of the release on zulip. But I would also be interested to know what the concrete idea for stabilization of the individual parts of this crate is. I think there contents with a variety of maturity and usefulness, and having a plan on what is intended to be long-term maintained and what not sounds great!

The answer could obviously be: everything. But that could it make it potentially harder to evolve the library than having a smaller content.

Here is my personal wishlist for stabilization:

Must haves

The join! and select! macros as well as all their dependencies (which is FusedFuture at the moment). Used them in all programs, whether it's std or not.

Nice to have

• All the extension traits on Futures, and e.g. thinks like join_all. I think the use-cases for those things got a lot smaller with the introduction of async_await. However those things seem fairly stable and useable for lots of people, so they are good to have.
• Synchronization primitives and channels. I think when this project initially started they were all awesome and a must-have to write any real world projects with futures. But now it seems like have at least 4 crates which implement the same things (futures-rs, tokio, async-std, futures-intrusive) - the first 3 probably in a very similar fashion. With each additional variant the motivation to long-term maintain a stable crate with those features seems lower. However since most applications will need something like a oneshot future and since the API surface is well fairly well understood it seems reasonable to provide those.

Not sure / lower-priority

• futures-io. Not sure if the ecosystem has already converged on traits for this. Afaik Tokio has their own versions. GATs might make it at some point of time possible to model things with futures instead of direct _poll() methods. And I personally would also require the traits to be no-std compatible (error type).
• Stream/Sink. Also not sure whether we should see those stable as is, or if they won't be superseded medium-term by other things once GATs and other features become available.
• Executors. Great to get something out of the box when just taking futures-rs as a dependency. However I think most applications will in the end use executors of different libraries that are also integrated with IO reactors or represent the GUI mainloop.

[taiki-e]

I think it is necessary to decide the crate name of futures-test (see #1169 (comment)).

EDIT: this seems solved.

(There are many other things, but I will comment later.)

[yoshuawuyts]

To provide feedback from async-std's side of things: I think things are looking really good! We primarily rely on futures-core and futures-io, so my feedback is mostly about that. This is an unordered list of things I think we may want to consider before the release:

---

• Remove Stream impl from VecDeque in futures-core? #1879 - Stream is currently implemented on VecDeque which is the only one, and feels slightly out of place.
• Remove Stream impl from VecDeque in futures-core? #1879 (comment) - IntoStream and FromStream for std::collections can only be implemented as part of futures-core; which is currently limiting some of our implementations. This may be worth adding to futures-core.
• add IntoFuture async-rs/async-std#259 - In RFC2394 await is meant to call IntoFuture, but currently it doesn't. I couldn't find any mention that plans had deviated, so I'm assuming async/await currently doesn't do this because we're still in MVP state. To that extent it may be a good idea to introduce this trait in futures-core first.
• Merge futures-io into futures-core #1688 - Should AsyncRead and AsyncWrite be part of futures-core? For async-std we'd still need to pull in futures-io for the BufRead trait, but overall I think this may be a question worth answering.

edit: Also as for a timeline to release 0.3.0; could we maybe plan to do this at least a week before 1.39 hits stable? This would give us time to update all of our crates so the moment things stabilize we're all set and updated. I suspect a lot of people will want to try out async/await, and in order for them to have a good first impression we probably must allow the ecosystem to have a bit of time to prepare.

edit: A PR to std has been made to add IntoFuture: rust-lang/rust#65244

---

Overall I'm feeling quite good about the current state of futures! I believe we're closing in on 400 days of futures-preview@0.3.0-alpha, and excited to finally be back on regular releases!

cc/ @stjepang

[theduke]

• async-rs/async-std#259 - In RFC2394 await is meant to call IntoFuture, but currently it doesn't. I couldn't find any mention that plans had deviated, so I'm assuming async/await currently doesn't do this because we're still in MVP state. To that extent it may be a good idea to introduce this trait in futures-core first.

I asked about this on Zulip here. Not a very solid answer there, it was just dropped at some point.
This should really be remedied IMO, but it will apparently require someone to push for it.

Executors. Great to get something out of the box when just taking futures-rs as a dependency.

I'd argue for definitely dropping those from the main futures crate. I always saw futures as a core library, and getting executors automatically was somewhat weird to me. There are some use-cases for simple and light weight executors, but imo they should be a separate crate.

[theduke]

Another note on crate organization: similar to the complexity reduction in tokio, I'd love to see futures collapsed into a single crate, with optional things handled via features.

[Nemo157]

See #1356 and #1688 about collapsing the crates, the reason for the majority of the boundaries are about semver stability.

[seanmonstar]

Here's my perspective:

• futures-core
  • Remove Spawn, LocalSpawn, SpawnError, and put them in futures-executor somehow. Separate Spawn/LocalSpawn from futures-core? #1830
  • Remove FutureObj and LocalFutureObj (they seem only needed for Spawn and friends?).
  • Remove AtomicWaker. It's only exposed in a doc(hidden) task::__internal module, but it doesn't seem like we need to compile it if only after the core traits.
• futures-executor
  • Possibly remove ThreadPool. There's probably more efficient executors. But maybe it's useful to be able to use quickly... If so, then at least make it optional (default off), so we don't need to compile it unless asked for.
• futures-util
  • Make the lock stuff optional. Well, more specifically, as slab is already optional, fix the issues if you disable it (turn off Mutex and FutureExt::shared).
• futures
  • While not flattening all the crates into this one is a good idea for stability, I'd like to see the main crate "feel" flattened, such that a user can just depend on futures and enable the features they want, instead of depending on the internal crates individually. (Add more optional features to the main futures crate #1875)
• In general:
  • The unstable optional feature may be a little too easy for a user to unknowingly depend on. A user could depend on futures, and some 3rd library, and the 3rd one could enable unstable, and the user can rely on "unstable" APIs without opting in. Maybe the danger here isn't that big a deal in practice. Or maybe we should consider what rayon did: require the end user to opt-in to unstable features via RUSTFLAGS="--cfg futures_unstable".

[taiki-e]

It's only exposed in a doc(hidden) task::__internal module, but it doesn't seem like we need to compile it if only after the core traits.

This is because both futures-channel and futures-util require AtomicWaker. But I think there are some crates that do not need combinators like futures-channel but need AtomicWaker, so it is maybe good to separate this.

Also, I was thinking of adding a new crate as a solution for #1830 (comment).
Personally, I think it might be a good idea to add a crate that provides "items contained in the futures::task module except for *Ext trait".

[seanmonstar]

So, I can't tell if suggested feedback in this issue should be incorporated or not, but we only have a little more than a week to do so if desired.

[cramertj]

@seanmonstar a number of the above issues have been handled already-- i'm adding issues to the 0.3 release milestone in an effort to triage and resolve remaining issues before the release. If you have more things you'd like to see captured, please open an issue and I'll make sure that it gets attention! Thanks for all your help listing things here and making sure we're on track for next week's release :)