doc: add comment about highWaterMark limit

Add a comment regarding memory limits and setting highWaterMark PR-URL: #33432 Reviewd-By: Colin Ihrig <[email protected]> Reviewed-By: Robert Nagy <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Ben Noordhuis <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Ruben Bridgewater <[email protected]>
nodejs · Jun 2, 2020 · e2484b2 · e2484b2
1 parent 8d47e8b
commit e2484b2
Showing 1 changed file with 5 additions and 0 deletions.
diff --git a/doc/api/stream.md b/doc/api/stream.md
@@ -93,6 +93,11 @@ A key goal of the `stream` API, particularly the [`stream.pipe()`][] method,
 is to limit the buffering of data to acceptable levels such that sources and
 destinations of differing speeds will not overwhelm the available memory.
 
+The `highWaterMark` option is a threshold, not a limit: it dictates the amount
+of data that a stream buffers before it stops asking for more data. It does not
+enforce a strict memory limitation in general. Specific stream implementations
+may choose to enforce stricter limits but doing so is optional.
+
 Because [`Duplex`][] and [`Transform`][] streams are both `Readable` and
 `Writable`, each maintains *two* separate internal buffers used for reading and
 writing, allowing each side to operate independently of the other while