Add documentation for anonymous pipe module

Author: olishmollie

library/std/src/pipe.rs

@@ -1,20 +1,80 @@
-//! Module for anonymous pipe
+//!  A cross-platform anonymous pipe.
 //!
-//! ```
-//! #![feature(anonymous_pipe)]
+//! This module provides support for anonymous OS pipes, like [pipe] on Linux or [CreatePipe] on
+//! Windows, which can be used as synchronous communication channels between related processes.
+//!
+//! # Behavior
+//!
+//! A pipe can be thought of as a bounded, interprocess [`mpsc`](crate::sync::mpsc), provided by
+//! the OS, with a platform-dependent capacity. In particular:
+//!
+//! * A read on a [`PipeReader`] blocks until the pipe is non-empty.
+//! * A write on a [`PipeWriter`] blocks when the pipe is full.
+//! * When all copies of a [`PipeWriter`] are closed, a read on the corresponding [`PipeReader`]
+//!   returns EOF.
+//! * [`PipeReader`] can be shared (by copying the underlying file descriptor), but only one process
+//!   will consume data in the pipe at any given time. See [`PipeReader::try_clone`] for an example
+//!   of this.
+//!
+//! # Capacity
+//!
+//! Pipe capacity is platform-dependent. To quote the Linux [man page]:
+//!
+//! > Different  implementations have different limits for the pipe capacity. Applications should
+//! > not rely on a particular capacity: an application should be designed so that a reading process
+//! > consumes data as soon as it is available, so that a writing process does not remain blocked.
 //!
+//! # Examples
+//!
+//! ```no_run
+//! #![feature(anonymous_pipe)]
 //! # #[cfg(miri)] fn main() {}
 //! # #[cfg(not(miri))]
+//! # use std::process::Command;
+//! # use std::io::{Read, Write};
 //! # fn main() -> std::io::Result<()> {
-//! let (reader, writer) = std::pipe::pipe()?;
+//! let (mut ping_rx, ping_tx) = std::pipe::pipe()?;
+//! let (pong_rx, mut pong_tx) = std::pipe::pipe()?;
+//!
+//! let mut peer = Command::new("python")
+//! .args([
+//!     "-c",
+//!     "from os import close\n\
+//!      from sys import stdin, stdout\n\
+//!      stdout.write('ping')\n\
+//!      stdout.flush()\n\
+//!      close(stdout.fileno())\n\
+//!      msg = stdin.read()\n\
+//!      assert(msg == 'pong')"
+//! ])
+//! .stdin(pong_rx)
+//! .stdout(ping_tx)
+//! .spawn()?;
+//!
+//! let mut msg = String::new();
+//! // Block until peer's write end is closed.
+//! ping_rx.read_to_string(&mut msg)?;
+//! assert_eq!(&msg, "ping");
+//!
+//! pong_tx.write_all(b"pong")?;
+//! // Close to unblock peer's read end.
+//! drop(pong_tx);
+//!
+//! peer.wait()?;
 //! # Ok(())
 //! # }
 //! ```
-
+//! [pipe]: https://man7.org/linux/man-pages/man2/pipe.2.html
+//! [CreatePipe]: https://learn.microsoft.com/en-us/windows/win32/api/namedpipeapi/nf-namedpipeapi-createpipe
+//! [man page]: https://man7.org/linux/man-pages/man7/pipe.7.html
 use crate::io;
 use crate::sys::anonymous_pipe::{AnonPipe, pipe as pipe_inner};
 
 /// Create anonymous pipe that is close-on-exec and blocking.
+///
+/// # Examples
+///
+/// See the [module-level](crate::pipe) documentation for examples.
 #[unstable(feature = "anonymous_pipe", issue = "127154")]
 #[inline]
 pub fn pipe() -> io::Result<(PipeReader, PipeWriter)> {
@@ -33,6 +93,61 @@ pub struct PipeWriter(pub(crate) AnonPipe);
 
 impl PipeReader {
     /// Create a new [`PipeReader`] instance that shares the same underlying file description.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// #![feature(anonymous_pipe)]
+    /// # #[cfg(miri)] fn main() {}
+    /// # #[cfg(not(miri))]
+    /// # use std::process::Command;
+    /// # use std::io::{Read, Write};
+    /// # use std::fs::{self, File};
+    /// # fn main() -> std::io::Result<()> {
+    /// const NUM_SLOT: u8 = 2;
+    /// const NUM_PROC: u8 = 5;
+    /// const OUTPUT: &str = "output.txt";
+    ///
+    /// let jobserver = [b'|'; NUM_SLOT as usize];
+    /// let mut jobs = vec![];
+    /// let mut file = File::create_new(OUTPUT)?;
+    ///
+    /// let (reader, mut writer) = std::pipe::pipe()?;
+    ///
+    /// for j in 0..NUM_PROC {
+    ///     jobs.push(
+    ///         Command::new("python")
+    ///             .args([
+    ///                 "-c",
+    ///                 &format!(
+    ///                     "from sys import stdout, stdin\n\
+    ///                      stdin.read(1)\n\
+    ///                      with open('{}', 'a') as fp: fp.write('x')\n\
+    ///                      stdout.write(b'|'.decode())",
+    ///                      OUTPUT
+    ///                 ),
+    ///             ])
+    ///             .stdout(writer.try_clone()?)
+    ///             .stdin(reader.try_clone()?)
+    ///             .spawn()?,
+    ///     )
+    /// }
+    ///
+    /// writer.write_all(&jobserver)?;
+    ///
+    /// for mut job in jobs {
+    ///     job.wait()?;
+    /// }
+    ///
+    /// let mut buf = String::new();
+    /// file.read_to_string(&mut buf)?;
+    ///
+    /// fs::remove_file(OUTPUT)?;
+    ///
+    /// assert_eq!(buf, "x".repeat(NUM_PROC.into()));
+    /// # Ok(())
+    /// # }
+    /// ```
     #[unstable(feature = "anonymous_pipe", issue = "127154")]
     pub fn try_clone(&self) -> io::Result<Self> {
         self.0.try_clone().map(Self)
@@ -41,6 +156,37 @@ impl PipeReader {
 
 impl PipeWriter {
     /// Create a new [`PipeWriter`] instance that shares the same underlying file description.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// #![feature(anonymous_pipe)]
+    /// # #[cfg(miri)] fn main() {}
+    /// # #[cfg(not(miri))]
+    /// # use std::process::Command;
+    /// # use std::io::Read;
+    /// # fn main() -> std::io::Result<()> {
+    /// let (mut reader, writer) = std::pipe::pipe()?;
+    ///
+    /// let mut peer = Command::new("python")
+    /// .args([
+    ///     "-c",
+    ///     "from sys import stdout, stderr\n\
+    ///      stdout.write('foo')\n\
+    ///      stderr.write('bar')"
+    /// ])
+    /// .stdout(writer.try_clone()?)
+    /// .stderr(writer)
+    /// .spawn()?;
+    ///
+    /// let mut msg = String::new();
+    /// reader.read_to_string(&mut msg)?;
+    /// assert_eq!(&msg, "foobar");
+    ///
+    /// peer.wait()?;
+    /// # Ok(())
+    /// # }
+    /// ```
     #[unstable(feature = "anonymous_pipe", issue = "127154")]
     pub fn try_clone(&self) -> io::Result<Self> {
         self.0.try_clone().map(Self)