Improve and expand documentation of pipes

- Reference UNIX, not just Linux
- Simplify some of the language
- Don't imply that pipes *only* work across multiple processes; instead,
  *suggest* that they're typically used across two or more separate
  processes.
- Specify that portable applications cannot use multiple readers or
  multiple writers for messages larger than a byte, due to potential
  interleaving.

Author: joshtriplett

library/std/src/pipe.rs

@@ -1,18 +1,26 @@
 //!  A cross-platform anonymous pipe.
 //!
-//! This module provides support for anonymous OS pipes, like [pipe] on Linux or [CreatePipe] on
-//! Windows.
+//! This module provides support for anonymous OS pipes, like [pipe] on UNIX/Linux or [CreatePipe]
+//! on Windows.
 //!
 //! # Behavior
 //!
-//! A pipe is a synchronous, unidirectional data channel between two or more processes, like an
-//! interprocess [`mpsc`](crate::sync::mpsc) provided by the OS. In particular:
+//! A pipe is a one-way data channel provided by the OS, which works across processes. A pipe is
+//! typically used to communicate between two or more separate processes, as there are better,
+//! faster ways to communicate within a single process.
+//!
+//! 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, but only one process will consume the data in the pipe.
+//! * [`PipeWriter`] can be shared, and multiple processes or threads can write to it at once, but
+//!   writes (above a target-specific threshold) may have their data interleaved.
+//! * [`PipeReader`] can be shared, and multiple processes or threads can read it at once. Any
+//!   given byte will only get consumed by one reader. There are no guarantees about data
+//!   interleaving.
+//! * Portable applications cannot assume any atomicity of messages larger than a single byte.
 //!
 //! # Capacity
 //!