1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: clarify recommendations in stream.md

Browse Source 
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>
This commit is contained in:
Rich Trott 2022-03-31 20:12:30 -07:00
parent c9bb345b05
commit b71779517d
1 changed files with 6 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
doc/api/stream.md
View File

@ -556,8 +556,8 @@ The `writable.uncork()` method flushes all data buffered since
[`stream.cork()`][] was called. [`stream.cork()`][] was called.
When using [`writable.cork()`][] and `writable.uncork()` to manage the buffering 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 of writes to a stream, defer calls to `writable.uncork()` using
deferred using `process.nextTick()`. Doing so allows batching of all `process.nextTick()`. Doing so allows batching of all
`writable.write()` calls that occur within a given Node.js event loop phase. `writable.write()` calls that occur within a given Node.js event loop phase.
```js ```js
@ -736,7 +736,7 @@ stop until the [`'drain'`][] event is emitted.
While a stream is not draining, calls to `write()` will buffer `chunk`, and While a stream is not draining, calls to `write()` will buffer `chunk`, and
return false. Once all currently buffered chunks are drained (accepted for return false. Once all currently buffered chunks are drained (accepted for
delivery by the operating system), the `'drain'` event will be emitted. 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 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 is not draining is allowed, Node.js will buffer all written chunks until
maximum memory usage occurs, at which point it will abort unconditionally. maximum memory usage occurs, at which point it will abort unconditionally.
@ -896,10 +896,9 @@ to consume data from a single stream. Specifically, using a combination
of `on('data')`, `on('readable')`, `pipe()`, or async iterators could of `on('data')`, `on('readable')`, `pipe()`, or async iterators could
lead to unintuitive behavior. lead to unintuitive behavior.
Use of the `readable.pipe()` method is recommended for most users as it has been `readable.pipe()` provides the easiest way to consume stream data. Developers
implemented to provide the easiest way of consuming stream data. Developers that that require more fine-grained control over the transfer and generation of data
require more fine-grained control over the transfer and generation of data can can use the [`EventEmitter`][] and `readable.on('readable')`/`readable.read()`
use the [`EventEmitter`][] and `readable.on('readable')`/`readable.read()`
or the `readable.pause()`/`readable.resume()` APIs. or the `readable.pause()`/`readable.resume()` APIs.
#### Class: `stream.Readable` #### Class: `stream.Readable`