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

doc: explain stream.finished cleanup

Browse Source 
PR-URL: https://github.com/nodejs/node/pull/28935
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
This commit is contained in:
Robert Nagy 2019-08-02 08:59:44 +02:00 committed by Rich Trott
parent b82ffd9526
commit 4c40a640ea
1 changed files with 20 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
doc/api/stream.md
View File

@ -1481,6 +1481,8 @@ added: v10.0.0
**Default**: `true`. **Default**: `true`.
* `callback` {Function} A callback function that takes an optional error * `callback` {Function} A callback function that takes an optional error
argument. argument.
* Returns: {Function} A cleanup function which removes all registered
listeners.
A function to get notified when a stream is no longer readable, writable A function to get notified when a stream is no longer readable, writable
or has experienced an error or a premature close event. or has experienced an error or a premature close event.
@ -1521,6 +1523,20 @@ run().catch(console.error);
rs.resume(); // Drain the stream. rs.resume(); // Drain the stream.
``` ```
`stream.finished()` leaves dangling event listeners (in particular
`'error'`, `'end'`, `'finish'` and `'close'`) after `callback` has been
invoked. The reason for this is so that unexpected `'error'` events (due to
incorrect stream implementations) do not cause unexpected crashes.
If this is unwanted behavior then the returned cleanup function needs to be
invoked in the callback:
```js
const cleanup = finished(...streams, (err) => {
cleanup();
// ...
});
```
### stream.pipeline(...streams, callback) ### stream.pipeline(...streams, callback)
<!-- YAML <!-- YAML
added: v10.0.0 added: v10.0.0
@ -1574,6 +1590,10 @@ async function run() {
run().catch(console.error); run().catch(console.error);
``` ```
`stream.pipeline()` leaves dangling event listeners on the streams
after the `callback` has been invoked. In the case of reuse of streams after
failure, this can cause event listener leaks and swallowed errors.
### stream.Readable.from(iterable, [options]) ### stream.Readable.from(iterable, [options])
<!-- YAML <!-- YAML
added: v12.3.0 added: v12.3.0