Stream RFC

[tmandry]

As drafted in #10

[nellshamrell]

Doing research on this now :)

[yoshuawuyts]

I was working on a crate today that models the browsers History API, and found that the concept of a DoubleEndedStream would be a great tool to model it: the history API is asynchronous and can can be navigated by going forward and backward through "the history stack". Under "future possibilities" it's probably worth mentioning we should explore not only IntoStream and FromStream which have clear tie-ins to language features. But we should also look towards filling out the roster of traits we found useful for Iterator.

Under async_std::stream we've shown it's possible to create async counterparts to the traits in std::iter. I'm not sure if it's worth mentioning every one of these, but we've successfully been able to implement the following traits:

DoubleEndedStream  # A stream able to yield elements from both ends.
ExactSizeStream    # A stream that knows its exact length.
Extend             # Extends a collection with the contents of a stream.
FromStream         # Conversion from a Stream.
FusedStream        # A stream that always continues to yield None when exhausted.
IntoStream         # Conversion into a Stream.
Product            # Trait to represent types that can be created by multiplying the elements of a stream.
Stream             # An asynchronous stream of values.
Sum                # Trait to represent types that can be created by summing up a stream.

[nellshamrell]

Got quite a bit more in place with #13.

To do on the next iteration:

• [x] More information about generators
• [x] Sketch out what IntoStream trait would look like
• [x] Sketch out what FromStream trait would look like

[nikomatsakis]

Some notes about attached vs detached streams and how interconversion might work (and what hurdles we know of, mostly a question of coherence) can be found in this hackmd:

https://hackmd.io/gHqlQBTiSrexwb-ppRPn-A

Discussion from this point on Zulip

[nikomatsakis]

Some concerns that should block opening the RFC

• [x] (Minor) Resolve the name question of attached vs lending
• [x] Add next method to the stream so it can be used for something
• [x] Add impls for Box<T> and other fundamental types
• [x] Clarify that because of this coherence conflict we can't, as language stands today, cleanly convert impl Stream to impl LendingStream

[nellshamrell]

Hello everyone!

#15 Seems to be in decent shape. Let's list any blockers we see to opening this up on the rust-lang/rfcs repo (I want us to get more concrete about them so we can address them directly whenever possible)

[nikomatsakis]

The main two things I would like to see added to the RFC:

• An explanation for why the next method requires Self: Unpin.
• Some coverage about generator syntax that explains that:
  • if we want [async] gen fn to support borrowing across a yield, it will need to have a pinned receiver
  • since stream requires that, this means that async gen fn() -> impl Stream is fairly easy, but async for x in y syntax or whatever would presumably want to pin
  • for iterator, it's a bit trickier, because the iterator trait does not require pinning, and therefore a gen fn either has to disallow borrowing or we need some kind of cleverness we have not yet come up with to "adapt" the return value of a gen fn to become an Iterator

Related conversation

[tmandry]

Stream RFC is open: https://github.com/rust-lang/rfcs/pull/2996