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

doc: clarify stream errors while reading and writing

Browse Source 
Errors should be propagated through destroy(err). Anything else
is basically undefined behaviour.

PR-URL: https://github.com/nodejs/node/pull/29653
Refs: https://github.com/nodejs/node/issues/29584
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
This commit is contained in:
Robert Nagy 2019-09-22 16:10:35 +02:00 committed by Rich Trott
parent ccb524fa16
commit 7223ce2a9c
1 changed files with 18 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
doc/api/stream.md
View File

@ -1879,13 +1879,11 @@ or write buffered data before a stream ends.
#### Errors While Writing #### Errors While Writing
It is recommended that errors occurring during the processing of the Errors occurring during the processing of the [`writable._write()`][],
`writable._write()` and `writable._writev()` methods are reported by invoking [`writable._writev()`][] and [`writable._final()`] methods must be propagated
the callback and passing the error as the first argument. This will cause an by invoking the callback and passing the error as the first argument.
`'error'` event to be emitted by the `Writable`. Throwing an `Error` from within Throwing an `Error` from within these methods or manually emitting an `'error'`
`writable._write()` can result in unexpected and inconsistent behavior depending event results in undefined behavior.
on how the stream is being used. Using the callback ensures consistent and
predictable handling of errors.
If a `Readable` stream pipes into a `Writable` stream when `Writable` emits an If a `Readable` stream pipes into a `Writable` stream when `Writable` emits an
error, the `Readable` stream will be unpiped. error, the `Readable` stream will be unpiped.
@ -2159,25 +2157,23 @@ buffer. See [`readable.push('')`][] for more information.
#### Errors While Reading #### Errors While Reading
It is recommended that errors occurring during the processing of the Errors occurring during processing of the [`readable._read()`][] must be
`readable._read()` method are emitted using the `'error'` event rather than propagated through the [`readable.destroy(err)`][readable-_destroy] method.
being thrown. Throwing an `Error` from within `readable._read()` can result in Throwing an `Error` from within [`readable._read()`][] or manually emitting an
unexpected and inconsistent behavior depending on whether the stream is `'error'` event results in undefined behavior.
operating in flowing or paused mode. Using the `'error'` event ensures
consistent and predictable handling of errors.
<!-- eslint-disable no-useless-return -->
```js ```js
const { Readable } = require('stream'); const { Readable } = require('stream');
const myReadable = new Readable({ const myReadable = new Readable({
read(size) { read(size) {
if (checkSomeErrorCondition()) { const err = checkSomeErrorCondition();
process.nextTick(() => this.emit('error', err)); if (err) {
return; this.destroy(err);
} } else {
// Do some work. // Do some work.
} }
}
}); });
``` ```
@ -2776,6 +2772,7 @@ contain multi-byte characters.
[`process.stderr`]: process.html#process_process_stderr [`process.stderr`]: process.html#process_process_stderr
[`process.stdin`]: process.html#process_process_stdin [`process.stdin`]: process.html#process_process_stdin
[`process.stdout`]: process.html#process_process_stdout [`process.stdout`]: process.html#process_process_stdout
[`readable._read()`]: #stream_readable_read_size_1
[`readable.push('')`]: #stream_readable_push [`readable.push('')`]: #stream_readable_push
[`readable.setEncoding()`]: #stream_readable_setencoding_encoding [`readable.setEncoding()`]: #stream_readable_setencoding_encoding
[`stream.Readable.from()`]: #stream_stream_readable_from_iterable_options [`stream.Readable.from()`]: #stream_stream_readable_from_iterable_options
@ -2786,6 +2783,9 @@ contain multi-byte characters.
[`stream.uncork()`]: #stream_writable_uncork [`stream.uncork()`]: #stream_writable_uncork
[`stream.unpipe()`]: #stream_readable_unpipe_destination [`stream.unpipe()`]: #stream_readable_unpipe_destination
[`stream.wrap()`]: #stream_readable_wrap_stream [`stream.wrap()`]: #stream_readable_wrap_stream
[`writable._final()`]: #stream_writable_final_callback
[`writable._write()`]: #stream_writable_write_chunk_encoding_callback_1
[`writable._writev()`]: #stream_writable_writev_chunks_callback
[`writable.cork()`]: #stream_writable_cork [`writable.cork()`]: #stream_writable_cork
[`writable.end()`]: #stream_writable_end_chunk_encoding_callback [`writable.end()`]: #stream_writable_end_chunk_encoding_callback
[`writable.uncork()`]: #stream_writable_uncork [`writable.uncork()`]: #stream_writable_uncork