stream: add StreamExt::fuse

[carllerche]

Provides an async equivalent to Iterator::fuse.

[hawkw]

I'm a little concerned that tokio::stream::StreamExt::fuse returning a stream that does not implement FusedStream, while futures::stream::StreamExt::fuse does, may trip people up? For example, if they import tokio's version ofStreamExt, and then try to call stream.fuse() and pass the stream into futures' select! macro.

If we're going to have an identical trait name and identical method name, we should at least ensure that it's clearly documented that this is substantially different from the futures crate's StreamExt::fuse...

[LucioFranco]

Agreed, but not sure what a better name might be?

[hawkw]

Agreed, but not sure what a better name might be?

Well, rather than changing the name, we could just have a large and obvious note in the docs? Not my favourite solution, but better than nothing.

[carllerche]

I don't think it is super critical to call out that it doesn't implement FuseStream... Fuse is picked as a name to match the std::Iterator::fuse impl.

[davidbarsky]

I don't think it is super critical to call out that it doesn't implement FuseStream... Fuse is picked as a name to match the std::Iterator::fuse impl.

I think it should be called out. Reading this PR made made me think it did implement the fuse in futures::stream::StreamExt.

[carllerche]

I tracked the question re: documenting the relation with FusedStream here: #1895