tokio/io/util/
sink.rs

1use crate::io::util::poll_proceed_and_make_progress;
2use crate::io::AsyncWrite;
3
4use std::fmt;
5use std::io;
6use std::pin::Pin;
7use std::task::{ready, Context, Poll};
8
9cfg_io_util! {
10    /// An async writer which will move data into the void.
11    ///
12    /// This struct is generally created by calling [`sink`][sink]. Please
13    /// see the documentation of `sink()` for more details.
14    ///
15    /// This is an asynchronous version of [`std::io::Sink`][std].
16    ///
17    /// [sink]: sink()
18    /// [std]: std::io::Sink
19    pub struct Sink {
20        _p: (),
21    }
22
23    /// Creates an instance of an async writer which will successfully consume all
24    /// data.
25    ///
26    /// All calls to [`poll_write`] on the returned instance will return
27    /// `Poll::Ready(Ok(buf.len()))` and the contents of the buffer will not be
28    /// inspected.
29    ///
30    /// This is an asynchronous version of [`std::io::sink`][std].
31    ///
32    /// [`poll_write`]: crate::io::AsyncWrite::poll_write()
33    /// [std]: std::io::sink
34    ///
35    /// # Examples
36    ///
37    /// ```
38    /// use tokio::io::{self, AsyncWriteExt};
39    ///
40    /// # #[tokio::main(flavor = "current_thread")]
41    /// # async fn main() -> io::Result<()> {
42    /// let buffer = vec![1, 2, 3, 5, 8];
43    /// let num_bytes = io::sink().write(&buffer).await?;
44    /// assert_eq!(num_bytes, 5);
45    /// Ok(())
46    /// # }
47    /// ```
48    pub fn sink() -> Sink {
49        Sink { _p: () }
50    }
51}
52
53impl AsyncWrite for Sink {
54    #[inline]
55    fn poll_write(
56        self: Pin<&mut Self>,
57        cx: &mut Context<'_>,
58        buf: &[u8],
59    ) -> Poll<Result<usize, io::Error>> {
60        ready!(crate::trace::trace_leaf(cx));
61        ready!(poll_proceed_and_make_progress(cx));
62        Poll::Ready(Ok(buf.len()))
63    }
64
65    #[inline]
66    fn is_write_vectored(&self) -> bool {
67        true
68    }
69
70    #[inline]
71    fn poll_write_vectored(
72        self: Pin<&mut Self>,
73        cx: &mut Context<'_>,
74        bufs: &[io::IoSlice<'_>],
75    ) -> Poll<Result<usize, io::Error>> {
76        ready!(crate::trace::trace_leaf(cx));
77        ready!(poll_proceed_and_make_progress(cx));
78        Poll::Ready(Ok(bufs.iter().map(|b| b.len()).sum()))
79    }
80
81    #[inline]
82    fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), io::Error>> {
83        ready!(crate::trace::trace_leaf(cx));
84        ready!(poll_proceed_and_make_progress(cx));
85        Poll::Ready(Ok(()))
86    }
87
88    #[inline]
89    fn poll_shutdown(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), io::Error>> {
90        ready!(crate::trace::trace_leaf(cx));
91        ready!(poll_proceed_and_make_progress(cx));
92        Poll::Ready(Ok(()))
93    }
94}
95
96impl fmt::Debug for Sink {
97    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
98        f.pad("Sink { .. }")
99    }
100}
101
102#[cfg(test)]
103mod tests {
104    use super::*;
105
106    #[test]
107    fn assert_unpin() {
108        crate::is_unpin::<Sink>();
109    }
110}
tokio/io/util/sink.rs

tokio/io/util/
sink.rs
