Trait tokio_buf::BufStream

source · [−]
pub trait BufStream {
    type Item: Buf;
    type Error;
    fn poll_buf(&mut self) -> Poll<Option<Self::Item>, Self::Error>;

    fn size_hint(&self) -> SizeHint { ... }
}
Expand description

An asynchronous stream of bytes.

BufStream asynchronously yields values implementing Buf, i.e. byte buffers.

Associated Types

Values yielded by the BufStream.

Each item is a sequence of bytes representing a chunk of the total ByteStream.

The error type this BufStream might generate.

Required methods

Attempt to pull out the next buffer of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

Return value

There are several possible return values, each indicating a distinct stream state:

  • Ok(Async::NotReady) means that this stream’s next value is not ready yet. Implementations will ensure that the current task will be notified when the next value may be ready.

  • Ok(Async::Ready(Some(buf))) means that the stream has successfully produced a value, buf, and may produce further values on subsequent poll_buf calls.

  • Ok(Async::Ready(None)) means that the stream has terminated, and poll_buf should not be invoked again.

Panics

Once a stream is finished, i.e. Ready(None) has been returned, further calls to poll_buf may result in a panic or other “bad behavior”.

Provided methods

Returns the bounds on the remaining length of the stream.

The size hint allows the caller to perform certain optimizations that are dependent on the byte stream size. For example, collect uses the size hint to pre-allocate enough capacity to store the entirety of the data received from the byte stream.

When SizeHint::upper() returns Some with a value equal to SizeHint::lower(), this represents the exact number of bytes that will be yielded by the BufStream.

Implementation notes

While not enforced, implementations are expected to respect the values returned from SizeHint. Any deviation is considered an implementation bug. Consumers may rely on correctness in order to use the value as part of protocol impelmentations. For example, an HTTP library may use the size hint to set the content-length header.

However, size_hint must not be trusted to omit bounds checks in unsafe code. An incorrect implementation of size_hint() must not lead to memory safety violations.

Implementations on Foreign Types

Implementors