[doc/io] Add a warning about process blocking behavior

Bug:https://github.com/dart-lang/sdk/issues/50674
Change-Id: I770527b41260250f1badba3a4387029bb68888af
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/276621
Commit-Queue: Brian Quinlan <bquinlan@google.com>
Reviewed-by: Alexander Aprelev <aam@google.com>

sdk/lib/io/process.dart

diff --git a/sdk/lib/io/process.dart b/sdk/lib/io/process.dart
index aacdb79..e5160ad 100644
--- a/sdk/lib/io/process.dart
+++ b/sdk/lib/io/process.dart
@@ -216,6 +216,25 @@
 /// A `Process`'s streams are distinct from the top-level streams
 /// for the current program.
 ///
+/// **NOTE:**
+/// `stdin`, `stdout`, and `stderr` are implemented using pipes between
+/// the parent process and the spawned subprocess. These pipes have limited
+/// capacity. If the subprocess writes to stderr or stdout in excess of that
+/// limit without the output being read, the subprocess blocks waiting for
+/// the pipe buffer to accept more data. For example:
+///
+/// ```dart
+/// import 'dart:io';
+///
+/// main() async {
+///   var process = await Process.start('cat', ['largefile.txt']);
+///   // The following await statement will never complete because the
+///   // subprocess never exits since it is blocked waiting for its
+///   // stdout to be read.
+///   await process.stderr.forEach(print);
+/// }
+/// ```
+///
 /// ## Exit codes
 ///
 /// Call the [exitCode] method to get the exit code of the process.
@@ -413,9 +432,47 @@
       [ProcessSignal signal = ProcessSignal.sigterm]);
 
   /// The standard output stream of the process as a `Stream`.
+  ///
+  /// **NOTE:**
+  /// `stdin`, `stdout`, and `stderr` are implemented using pipes between
+  /// the parent process and the spawned subprocess. These pipes have limited
+  /// capacity. If the subprocess writes to stderr or stdout in excess of that
+  /// limit without the output being read, the subprocess blocks waiting for
+  /// the pipe buffer to accept more data. For example:
+  ///
+  /// ```dart
+  /// import 'dart:io';
+  ///
+  /// main() async {
+  ///   var process = await Process.start('cat', ['largefile.txt']);
+  ///   // The following await statement will never complete because the
+  ///   // subprocess never exits since it is blocked waiting for its
+  ///   // stdout to be read.
+  ///   await process.stderr.forEach(print);
+  /// }
+  /// ```
   Stream<List<int>> get stdout;
 
   /// The standard error stream of the process as a `Stream`.
+  ///
+  /// **NOTE:**
+  /// `stdin`, `stdout`, and `stderr` are implemented using pipes between
+  /// the parent process and the spawned subprocess. These pipes have limited
+  /// capacity. If the subprocess writes to stderr or stdout in excess of that
+  /// limit without the output being read, the subprocess blocks waiting for
+  /// the pipe buffer to accept more data. For example:
+  ///
+  /// ```dart
+  /// import 'dart:io';
+  ///
+  /// main() async {
+  ///   var process = await Process.start('cat', ['largefile.txt']);
+  ///   // The following await statement will never complete because the
+  ///   // subprocess never exits since it is blocked waiting for its
+  ///   // stdout to be read.
+  ///   await process.stderr.forEach(print);
+  /// }
+  /// ```
   Stream<List<int>> get stderr;
 
   /// The standard input stream of the process as an [IOSink].