pub trait BufStream {
type Item: Buf;
type Error;
// Required method
fn poll_buf(&mut self) -> Poll<Option<Self::Item>, Self::Error>;
// Provided method
fn size_hint(&self) -> SizeHint { ... }
}Expand description
An asynchronous stream of bytes.
BufStream asynchronously yields values implementing Buf, i.e. byte
buffers.
Required Associated Types§
Required Methods§
Sourcefn poll_buf(&mut self) -> Poll<Option<Self::Item>, Self::Error>
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 subsequentpoll_bufcalls. -
Ok(Async::Ready(None))means that the stream has terminated, andpoll_bufshould 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§
Sourcefn size_hint(&self) -> SizeHint
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.