Trait tokio_buf::BufStream

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

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

An asynchronous stream of bytes.

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

Associated Types

type Item: Buf

Values yielded by the BufStream.

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

type Error

The error type this BufStream might generate.

Loading content...

Required methods

fn poll_buf(&mut self) -> Poll<Option<Self::Item>, Self::Error>

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".

Loading content...

Provided methods

fn size_hint(&self) -> SizeHint

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.

Loading content...

Implementations on Foreign Types

impl BufStream for String

type Item = Cursor<Vec<u8>>

type Error = Never

fn poll_buf(&mut self) -> Poll<Option<Self::Item>, Self::Error>

fn size_hint(&self) -> SizeHint

impl BufStream for &'static str

type Item = Cursor<&'static [u8]>

type Error = Never

fn poll_buf(&mut self) -> Poll<Option<Self::Item>, Self::Error>

fn size_hint(&self) -> SizeHint

impl BufStream for Vec<u8>

type Item = Cursor<Vec<u8>>

type Error = Never

fn poll_buf(&mut self) -> Poll<Option<Self::Item>, Self::Error>

fn size_hint(&self) -> SizeHint

impl BufStream for &'static [u8]

type Item = Cursor<&'static [u8]>

type Error = Never

fn poll_buf(&mut self) -> Poll<Option<Self::Item>, Self::Error>

fn size_hint(&self) -> SizeHint

impl BufStream for Bytes

type Item = Cursor<Bytes>

type Error = Never

fn poll_buf(&mut self) -> Poll<Option<Self::Item>, Self::Error>

fn size_hint(&self) -> SizeHint

impl BufStream for BytesMut

type Item = Cursor<BytesMut>

type Error = Never

fn poll_buf(&mut self) -> Poll<Option<Self::Item>, Self::Error>

fn size_hint(&self) -> SizeHint

Loading content...

Implementors

impl<T> BufStream for Limit<T> where
    T: BufStream, 

type Item = T::Item

type Error = LimitError<T::Error>

fn poll_buf(&mut self) -> Poll<Option<Self::Item>, Self::Error>

fn size_hint(&self) -> SizeHint

impl<T, U> BufStream for Chain<T, U> where
    T: BufStream,
    U: BufStream<Error = T::Error>, 

type Item = Either<T::Item, U::Item>

type Error = T::Error

fn poll_buf(&mut self) -> Poll<Option<Self::Item>, Self::Error>

fn size_hint(&self) -> SizeHint

Loading content...