diff options
author | Rich Trott <rtrott@gmail.com> | 2022-03-31 20:12:30 -0700 |
---|---|---|
committer | Juan José Arboleda <soyjuanarbol@gmail.com> | 2022-04-06 12:25:52 -0500 |
commit | c036800ddc1850dceaed295e511907cbf8e3e5a2 (patch) | |
tree | a65cfc11f00cc622b24e1553b11736fb25ffbdb8 | |
parent | dcf0abf8c7993289665e1294c01bb5523813d05e (diff) | |
download | node-new-c036800ddc1850dceaed295e511907cbf8e3e5a2.tar.gz |
doc: clarify recommendations in stream.md
PR-URL: https://github.com/nodejs/node/pull/42555
Reviewed-By: Mestery <mestery@protonmail.com>
Reviewed-By: Tierney Cyren <hello@bnb.im>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Akhil Marsonya <akhil.marsonya27@gmail.com>
-rw-r--r-- | doc/api/stream.md | 13 |
1 files changed, 6 insertions, 7 deletions
diff --git a/doc/api/stream.md b/doc/api/stream.md index ff32f97622..09017dd728 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -546,8 +546,8 @@ The `writable.uncork()` method flushes all data buffered since [`stream.cork()`][] was called. When using [`writable.cork()`][] and `writable.uncork()` to manage the buffering -of writes to a stream, it is recommended that calls to `writable.uncork()` be -deferred using `process.nextTick()`. Doing so allows batching of all +of writes to a stream, defer calls to `writable.uncork()` using +`process.nextTick()`. Doing so allows batching of all `writable.write()` calls that occur within a given Node.js event loop phase. ```js @@ -703,7 +703,7 @@ stop until the [`'drain'`][] event is emitted. While a stream is not draining, calls to `write()` will buffer `chunk`, and return false. Once all currently buffered chunks are drained (accepted for delivery by the operating system), the `'drain'` event will be emitted. -It is recommended that once `write()` returns false, no more chunks be written +Once `write()` returns false, do not write more chunks until the `'drain'` event is emitted. While calling `write()` on a stream that is not draining is allowed, Node.js will buffer all written chunks until maximum memory usage occurs, at which point it will abort unconditionally. @@ -863,10 +863,9 @@ to consume data from a single stream. Specifically, using a combination of `on('data')`, `on('readable')`, `pipe()`, or async iterators could lead to unintuitive behavior. -Use of the `readable.pipe()` method is recommended for most users as it has been -implemented to provide the easiest way of consuming stream data. Developers that -require more fine-grained control over the transfer and generation of data can -use the [`EventEmitter`][] and `readable.on('readable')`/`readable.read()` +`readable.pipe()` provides the easiest way to consume stream data. Developers +that require more fine-grained control over the transfer and generation of data +can use the [`EventEmitter`][] and `readable.on('readable')`/`readable.read()` or the `readable.pause()`/`readable.resume()` APIs. #### Class: `stream.Readable` |