Crate tokio_stream

Stream utilities for Tokio.

A Stream is an asynchronous sequence of values. It can be thought of as an asynchronous version of the standard library’s Iterator trait.

This crate provides helpers to work with them. For examples of usage and a more in-depth description of streams you can also refer to the streams tutorial on the tokio website.

Iterating over a Stream

Due to similarities with the standard library’s Iterator trait, some new users may assume that they can use for in syntax to iterate over a Stream, but this is unfortunately not possible. Instead, you can use a while let loop as follows:

use tokio_stream::{self as stream, StreamExt};

#[tokio::main]
async fn main() {
    let mut stream = stream::iter(vec![0, 1, 2]);

    while let Some(value) = stream.next().await {
        println!("Got {}", value);
    }
}

Returning a Stream from a function

A common way to stream values from a function is to pass in the sender half of a channel and use the receiver as the stream. This requires awaiting both futures to ensure progress is made. Another alternative is the async-stream crate, which contains macros that provide a yield keyword and allow you to return an impl Stream.

Conversion to and from AsyncRead/AsyncWrite

It is often desirable to convert a Stream into an AsyncRead, especially when dealing with plaintext formats streamed over the network. The opposite conversion from an AsyncRead into a Stream is also another commonly required feature. To enable these conversions, tokio-util provides the StreamReader and ReaderStream types when the io feature is enabled.

Re-exports

• pub use futures_core::Stream;

Modules

• adapters
  Adapters for Streams created by methods in StreamExt.
• wrappers
  Wrappers for Tokio types that implement Stream.

Structs

• Elapsed
  Error returned by Timeout and TimeoutRepeating.
• Empty
  Stream for the empty function.
• Iter
  Stream for the iter function.
• Once
  Stream for the once function.
• Pending
  Stream for the pending function.
• StreamMap
  Combine many streams into one, indexing each source stream with a unique key.
• StreamNotifyClose
  A Stream that wraps the values in an Option.

Traits

• FromStream
  Convert from a Stream.
• StreamExt
  An extension trait for the Stream trait that provides a variety of convenient combinator functions.

Functions

• empty
  Creates a stream that yields nothing.
• iter
  Converts an Iterator into a Stream which is always ready to yield the next value.
• once
  Creates a stream that emits an element exactly once.
• pending
  Creates a stream that is never ready