tokio_buf/
lib.rs

1#![doc(html_root_url = "https://docs.rs/tokio-buf/0.1.1")]
2#![deny(missing_docs, missing_debug_implementations, unreachable_pub)]
3#![cfg_attr(test, deny(warnings))]
4
5//! Asynchronous stream of bytes.
6//!
7//! This crate contains the `BufStream` trait and a number of combinators for
8//! this trait. The trait is similar to `Stream` in the `futures` library, but
9//! instead of yielding arbitrary values, it only yields types that implement
10//! `Buf` (i.e, byte collections).
11
12extern crate bytes;
13#[cfg(feature = "util")]
14extern crate either;
15#[allow(unused)]
16#[macro_use]
17extern crate futures;
18
19mod never;
20mod size_hint;
21mod str;
22mod u8;
23#[cfg(feature = "util")]
24pub mod util;
25
26pub use self::size_hint::SizeHint;
27#[doc(inline)]
28#[cfg(feature = "util")]
29pub use util::BufStreamExt;
30
31use bytes::Buf;
32use futures::Poll;
33
34/// An asynchronous stream of bytes.
35///
36/// `BufStream` asynchronously yields values implementing `Buf`, i.e. byte
37/// buffers.
38pub trait BufStream {
39    /// Values yielded by the `BufStream`.
40    ///
41    /// Each item is a sequence of bytes representing a chunk of the total
42    /// `ByteStream`.
43    type Item: Buf;
44
45    /// The error type this `BufStream` might generate.
46    type Error;
47
48    /// Attempt to pull out the next buffer of this stream, registering the
49    /// current task for wakeup if the value is not yet available, and returning
50    /// `None` if the stream is exhausted.
51    ///
52    /// # Return value
53    ///
54    /// There are several possible return values, each indicating a distinct
55    /// stream state:
56    ///
57    /// - `Ok(Async::NotReady)` means that this stream's next value is not ready
58    /// yet. Implementations will ensure that the current task will be notified
59    /// when the next value may be ready.
60    ///
61    /// - `Ok(Async::Ready(Some(buf)))` means that the stream has successfully
62    /// produced a value, `buf`, and may produce further values on subsequent
63    /// `poll_buf` calls.
64    ///
65    /// - `Ok(Async::Ready(None))` means that the stream has terminated, and
66    /// `poll_buf` should not be invoked again.
67    ///
68    /// # Panics
69    ///
70    /// Once a stream is finished, i.e. `Ready(None)` has been returned, further
71    /// calls to `poll_buf` may result in a panic or other "bad behavior".
72    fn poll_buf(&mut self) -> Poll<Option<Self::Item>, Self::Error>;
73
74    /// Returns the bounds on the remaining length of the stream.
75    ///
76    /// The size hint allows the caller to perform certain optimizations that
77    /// are dependent on the byte stream size. For example, `collect` uses the
78    /// size hint to pre-allocate enough capacity to store the entirety of the
79    /// data received from the byte stream.
80    ///
81    /// When `SizeHint::upper()` returns `Some` with a value equal to
82    /// `SizeHint::lower()`, this represents the exact number of bytes that will
83    /// be yielded by the `BufStream`.
84    ///
85    /// # Implementation notes
86    ///
87    /// While not enforced, implementations are expected to respect the values
88    /// returned from `SizeHint`. Any deviation is considered an implementation
89    /// bug. Consumers may rely on correctness in order to use the value as part
90    /// of protocol impelmentations. For example, an HTTP library may use the
91    /// size hint to set the `content-length` header.
92    ///
93    /// However, `size_hint` must not be trusted to omit bounds checks in unsafe
94    /// code. An incorrect implementation of `size_hint()` must not lead to
95    /// memory safety violations.
96    fn size_hint(&self) -> SizeHint {
97        SizeHint::default()
98    }
99}
tokio_buf/lib.rs

tokio_buf/
lib.rs
