io: update tokio::io::stdout documentation (#6674)

tokio/src/io/stdout.rs

@@ -33,6 +33,31 @@ cfg_io_std! {
  /// 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>>,
@@ -64,6 +89,31 @@ cfg_io_std! {
  /// 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();
  Stdout {