Skip to content

Commit b9c8bff

Browse files
committed
adds more info based on feedback
Signed-off-by: Nell Shamrell <[email protected]>
1 parent 642935a commit b9c8bff

File tree

1 file changed

+29
-8
lines changed

1 file changed

+29
-8
lines changed

rfc-drafts/stream.md

+29-8
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,8 @@ pub trait Stream {
7575
Self: Unpin;
7676
}
7777
```
78+
* For information on why `Self: Unpin` is included in the `next`
79+
method, please see [this discussion on the draft RFC](https://github.com/rust-lang/wg-async-foundations/pull/15#discussion_r452482084).
7880

7981
The arguments to `poll_next` match that of the [`Future::poll`] method:
8082

@@ -130,9 +132,14 @@ where
130132

131133
We should also implement a next method, similar to [the implementation in the futures-util crate](https://docs.rs/futures-util/0.3.5/src/futures_util/stream/stream/next.rs.html#10-12).
132134

133-
In general, we have purposefully kept the core trait definition minimal. There are a number of useful extension methods that are available, for example, in the futures-stream crate, but we have not included them because they involve closure arguments, and we have not yet finalized the design of async closures.
135+
In general, we have purposefully kept the core trait definition minimal.
136+
There are a number of useful extension methods that are available, for example,
137+
in the futures-stream crate, but we have not included them because they involve
138+
closure arguments, and we have not yet finalized the design of async closures.
134139

135-
However, the core methods alone are extremely unergonomic. You can't even iterate over the items coming out of the stream. Therefore, we include a few minimal convenience methods that are not dependent on any unstable features. Most notably, next
140+
However, the core methods alone are extremely unergonomic. You can't even iterate
141+
over the items coming out of the stream. Therefore, we include a few minimal
142+
convenience methods that are not dependent on any unstable features. Most notably, next
136143

137144
```rust
138145
/// A future that advances the stream and returns the next value.
@@ -225,7 +232,8 @@ Why should we *not* do this?
225232

226233
## Where should stream live?
227234

228-
As mentioned above, `core::stream` is analogous to `core::future`. But, do we want to find some other naming scheme that can scale up to other future additions, such as io traits or channels?
235+
As mentioned above, `core::stream` is analogous to `core::future`. But, do we want to find
236+
some other naming scheme that can scale up to other future additions, such as io traits or channels?
229237

230238
# Prior art
231239
[prior-art]: #prior-art
@@ -439,6 +447,12 @@ pub trait Stream {
439447
}
440448
```
441449

450+
When drafting this RFC, there was [discussion](https://github.com/rust-lang/wg-async-foundations/pull/15#discussion_r451182595)
451+
about whether to implement from_stream for all T where `T: FromIterator` as well.
452+
`FromStream` is perhaps more general than `FromIterator` because the await point is allowed to suspend execution of the
453+
current function, but doesn't have too. Therefore, many (if not all) existing impls of `FromIterator` would work
454+
for `FromStream` as well. While this would be a good point for a future discussion, it is not in the scope of this RFC.
455+
442456
## Other Traits
443457

444458
Eventually, we may also want to add some (if not all) of the roster of traits we found useful for `Iterator`.
@@ -480,11 +494,16 @@ There has been much discussion around lending streams (also referred to as attac
480494
[Source](https://smallcultfollowing.com/babysteps/blog/2019/12/10/async-interview-2-cramertj-part-2/#the-need-for-streaming-streams-and-iterators)
481495

482496

483-
In a **lending** stream (also known as an "attached" stream), the `Item` that gets returned by `Stream` may be borrowed from `self`. It can only be used as long as the `self` reference remains live.
497+
In a **lending** stream (also known as an "attached" stream), the `Item` that gets
498+
returned by `Stream` may be borrowed from `self`. It can only be used as long as
499+
the `self` reference remains live.
484500

485-
In a **non-lending** stream (also known as a "detached" stream), the `Item` that gets returned by `Stream` is "detached" from self. This means it can be stored and moved about independently from `self`.
501+
In a **non-lending** stream (also known as a "detached" stream), the `Item` that
502+
gets returned by `Stream` is "detached" from self. This means it can be stored
503+
and moved about independently from `self`.
486504

487-
This RFC does not cover the addition of lending streams (streams as implemented through this RFC are all non-lending streams).
505+
This RFC does not cover the addition of lending streams (streams as implemented through
506+
this RFC are all non-lending streams).
488507

489508
We can add the `Stream` trait to the standard library now and delay
490509
adding in this distinction between the two types of streams - lending and
@@ -547,7 +566,8 @@ become non-lending ones?
547566

548567
**Coherence**
549568

550-
The impl above has a problem. As the Rust language stands today, we cannot cleanly convert impl Stream to impl LendingStream due to a coherence conflict.
569+
The impl above has a problem. As the Rust language stands today, we cannot cleanly convert
570+
impl Stream to impl LendingStream due to a coherence conflict.
551571

552572
If you have other impls like:
553573

@@ -569,7 +589,8 @@ Resolving this would require either an explicit “wrapper” step or else some
569589

570590
It should be noted that the same applies to Iterator, it is not unique to Stream.
571591

572-
These use cases for lending/non-lending streams need more thought, which is part of the reason it is out of the scope of this particular RFC.
592+
These use cases for lending/non-lending streams need more thought, which is part of the reason it
593+
is out of the scope of this particular RFC.
573594

574595
## Generator syntax
575596
[generator syntax]: #generator-syntax

0 commit comments

Comments
 (0)