tokio/io/

stdout.rs

use crate::io::blocking::Blocking;
use crate::io::stdio_common::SplitByUtf8BoundaryIfWindows;
use crate::io::AsyncWrite;
use std::io;
use std::pin::Pin;
use std::task::Context;
use std::task::Poll;

cfg_io_std! {
    /// A handle to the standard output stream of a process.
    ///
    /// Concurrent writes to stdout must be executed with care: Only individual
    /// writes to this [`AsyncWrite`] are guaranteed to be intact. In particular
    /// you should be aware that writes using [`write_all`] are not guaranteed
    /// to occur as a single write, so multiple threads writing data with
    /// [`write_all`] may result in interleaved output.
    ///
    /// # Warning
    ///
    /// Each call to [`stdout()`] creates a **new** handle with its own
    /// internal state. Writes through different handles are not
    /// coordinated, so creating a new handle in a loop can cause output
    /// to appear out of order:
    ///
    /// ```no_run
    /// # use tokio::io::{self, AsyncWriteExt};
    /// # #[tokio::main]
    /// # async fn main() -> std::io::Result<()> {
    /// // WRONG: creates a new handle each iteration
    /// for i in 0..10 {
    ///     let mut out = io::stdout();
    ///     out.write_all(b"data").await?;
    ///     out.write_all(b"\n").await?;
    ///     // out is dropped here; its last write may still be
    ///     // running when the next iteration starts
    /// }
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// To preserve order, create one handle outside the loop and
    /// reuse it:
    ///
    /// ```no_run
    /// # use tokio::io::{self, AsyncWriteExt};
    /// # #[tokio::main]
    /// # async fn main() -> std::io::Result<()> {
    /// let mut out = io::stdout();
    /// for i in 0..10 {
    ///     out.write_all(b"data").await?;
    ///     out.write_all(b"\n").await?;
    /// }
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// Created by the [`stdout`] function.
    ///
    /// [`stdout`]: stdout()
    /// [`AsyncWrite`]: AsyncWrite
    /// [`write_all`]: crate::io::AsyncWriteExt::write_all()
    ///
    /// # Examples
    ///
    /// ```
    /// use tokio::io::{self, AsyncWriteExt};
    ///
    /// #[tokio::main]
    /// async fn main() -> io::Result<()> {
    ///     let mut stdout = io::stdout();
    ///     stdout.write_all(b"Hello world!").await?;
    ///     Ok(())
    /// }
    /// ```
    ///
    /// The following is an example of using `stdio` with loop.
    ///
    /// ```
    /// use tokio::io::{self, AsyncWriteExt};
    ///
    /// #[tokio::main]
    /// async fn main() {
    ///     let messages = vec!["hello", " world\n"];
    ///
    ///     // When you use `stdio` in a loop, it is recommended to create
    ///     // a single `stdio` instance outside the loop and call a write
    ///     // operation against that instance on each loop.
    ///     //
    ///     // Repeatedly creating `stdout` instances inside the loop and
    ///     // writing to that handle could result in mangled output since
    ///     // each write operation is handled by a different blocking thread.
    ///     let mut stdout = io::stdout();
    ///
    ///     for message in &messages {
    ///         stdout.write_all(message.as_bytes()).await.unwrap();
    ///         stdout.flush().await.unwrap();
    ///     }
    /// }
    /// ```
    #[derive(Debug)]
    pub struct Stdout {
        std: SplitByUtf8BoundaryIfWindows<Blocking<std::io::Stdout>>,
    }

    /// Constructs a new handle to the standard output of the current process.
    ///
    /// The returned handle allows writing to standard out from the within the
    /// Tokio runtime.
    ///
    /// Concurrent writes to stdout must be executed with care: Only individual
    /// writes to this [`AsyncWrite`] are guaranteed to be intact. In particular
    /// you should be aware that writes using [`write_all`] are not guaranteed
    /// to occur as a single write, so multiple threads writing data with
    /// [`write_all`] may result in interleaved output.
    ///
    /// Note that unlike [`std::io::stdout`], each call to this `stdout()`
    /// produces a new writer, so for example, this program does **not** flush stdout:
    ///
    /// ```no_run
    /// # use tokio::io::AsyncWriteExt;
    /// # #[tokio::main]
    /// # async fn main() -> std::io::Result<()> {
    /// tokio::io::stdout().write_all(b"aa").await?;
    /// tokio::io::stdout().flush().await?;
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// [`std::io::stdout`]: std::io::stdout
    /// [`AsyncWrite`]: AsyncWrite
    /// [`write_all`]: crate::io::AsyncWriteExt::write_all()
    ///
    /// # Examples
    ///
    /// ```
    /// use tokio::io::{self, AsyncWriteExt};
    ///
    /// #[tokio::main]
    /// async fn main() -> io::Result<()> {
    ///     let mut stdout = io::stdout();
    ///     stdout.write_all(b"Hello world!").await?;
    ///     Ok(())
    /// }
    /// ```
    ///
    /// The following is an example of using `stdio` with loop.
    ///
    /// ```
    /// use tokio::io::{self, AsyncWriteExt};
    ///
    /// #[tokio::main]
    /// async fn main() {
    ///     let messages = vec!["hello", " world\n"];
    ///
    ///     // When you use `stdio` in a loop, it is recommended to create
    ///     // a single `stdio` instance outside the loop and call a write
    ///     // operation against that instance on each loop.
    ///     //
    ///     // Repeatedly creating `stdout` instances inside the loop and
    ///     // writing to that handle could result in mangled output since
    ///     // each write operation is handled by a different blocking thread.
    ///     let mut stdout = io::stdout();
    ///
    ///     for message in &messages {
    ///         stdout.write_all(message.as_bytes()).await.unwrap();
    ///         stdout.flush().await.unwrap();
    ///     }
    /// }
    /// ```
    pub fn stdout() -> Stdout {
        let std = io::stdout();
        // SAFETY: The `Read` implementation of `std` does not read from the
        // buffer it is borrowing and correctly reports the length of the data
        // written into the buffer.
        let blocking = unsafe { Blocking::new(std) };
        Stdout {
            std: SplitByUtf8BoundaryIfWindows::new(blocking),
        }
    }
}

#[cfg(unix)]
mod sys {
    use std::os::unix::io::{AsFd, AsRawFd, BorrowedFd, RawFd};

    use super::Stdout;

    impl AsRawFd for Stdout {
        fn as_raw_fd(&self) -> RawFd {
            std::io::stdout().as_raw_fd()
        }
    }

    impl AsFd for Stdout {
        fn as_fd(&self) -> BorrowedFd<'_> {
            unsafe { BorrowedFd::borrow_raw(self.as_raw_fd()) }
        }
    }
}

cfg_windows! {
    use crate::os::windows::io::{AsHandle, BorrowedHandle, AsRawHandle, RawHandle};

    impl AsRawHandle for Stdout {
        fn as_raw_handle(&self) -> RawHandle {
            std::io::stdout().as_raw_handle()
        }
    }

    impl AsHandle for Stdout {
        fn as_handle(&self) -> BorrowedHandle<'_> {
            unsafe { BorrowedHandle::borrow_raw(self.as_raw_handle()) }
        }
    }
}

impl AsyncWrite for Stdout {
    fn poll_write(
        mut self: Pin<&mut Self>,
        cx: &mut Context<'_>,
        buf: &[u8],
    ) -> Poll<io::Result<usize>> {
        Pin::new(&mut self.std).poll_write(cx, buf)
    }

    fn poll_flush(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), io::Error>> {
        Pin::new(&mut self.std).poll_flush(cx)
    }

    fn poll_shutdown(
        mut self: Pin<&mut Self>,
        cx: &mut Context<'_>,
    ) -> Poll<Result<(), io::Error>> {
        Pin::new(&mut self.std).poll_shutdown(cx)
    }
}