[−][src]Trait tokio_buf::BufStream
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.
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 subsequentpoll_buf
calls. -
Ok(Async::Ready(None))
means that the stream has terminated, andpoll_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
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.
Implementations on Foreign Types
impl BufStream for String
[src]
type Item = Cursor<Vec<u8>>
type Error = Never
fn poll_buf(&mut self) -> Poll<Option<Self::Item>, Self::Error>
[src]
fn size_hint(&self) -> SizeHint
[src]
impl BufStream for &'static str
[src]
type Item = Cursor<&'static [u8]>
type Error = Never
fn poll_buf(&mut self) -> Poll<Option<Self::Item>, Self::Error>
[src]
fn size_hint(&self) -> SizeHint
[src]
impl BufStream for Vec<u8>
[src]
type Item = Cursor<Vec<u8>>
type Error = Never
fn poll_buf(&mut self) -> Poll<Option<Self::Item>, Self::Error>
[src]
impl BufStream for &'static [u8]
[src]
type Item = Cursor<&'static [u8]>
type Error = Never
fn poll_buf(&mut self) -> Poll<Option<Self::Item>, Self::Error>
[src]
impl BufStream for Bytes
[src]
type Item = Cursor<Bytes>
type Error = Never
fn poll_buf(&mut self) -> Poll<Option<Self::Item>, Self::Error>
[src]
impl BufStream for BytesMut
[src]
type Item = Cursor<BytesMut>
type Error = Never
fn poll_buf(&mut self) -> Poll<Option<Self::Item>, Self::Error>
[src]
Implementors
impl<T> BufStream for Limit<T> where
T: BufStream,
[src]
T: BufStream,
type Item = T::Item
type Error = LimitError<T::Error>
fn poll_buf(&mut self) -> Poll<Option<Self::Item>, Self::Error>
[src]
impl<T, U> BufStream for Chain<T, U> where
T: BufStream,
U: BufStream<Error = T::Error>,
[src]
T: BufStream,
U: BufStream<Error = T::Error>,