Explain pinning in README #26
Conversation
| pin_mut!(s); // needed for iteration | ||
| // Stream must be pinned before iteration. It can be done with Box::pin, | ||
| // but the pin_mut macro is more efficient. See "Pinning" section. | ||
| pin_mut!(s); |
There was a problem hiding this comment.
minor nit, could we possibly change this to https://docs.rs/tokio/0.2.11/tokio/macro.pin.html happy to do this in another PR but would be good to point to the tokio version.
| @@ -32,7 +32,9 @@ async fn main() { | |||
| } | |||
| }; | |||
|
|
|||
| pin_mut!(s); // needed for iteration | |||
| // Stream must be pinned before iteration. It can be done with Box::pin, | |||
There was a problem hiding this comment.
I would probably say something along the lines of stack pinning via tokio::pin is much more efficient but this can also be achieved by hoisting the item via Box::pin.
| @@ -60,7 +62,7 @@ fn zero_to_three() -> impl Stream<Item = u32> { | |||
| #[tokio::main] | |||
| async fn main() { | |||
| let s = zero_to_three(); | |||
| pin_mut!(s); // needed for iteration | |||
| pin_mut!(s); // Pinning is needed for iteration | |||
There was a problem hiding this comment.
Since, impl Stream above doesn't retrun a impl Stream + Unpin we must ensure that the stream is Unpin to await something on it.
Might be good to explain that.
| @@ -135,6 +137,20 @@ fn bind_and_accept(addr: SocketAddr) | |||
| } | |||
| ``` | |||
|
|
|||
| ## Pinning | |||
|
|
|||
| If you wrap the stream in `Box::pin`, the callers won't need to pin it before iterating it. This is more convenient for the callers, but adds a cost of using dynamic dispatch. | |||
There was a problem hiding this comment.
Would be good to explain that Unpin gets auto added in impl Trait just like how Send gets leaked since that could be confusing.
|
Should we just get this merged? |
Fixes #25