[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>
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].
