doc: clarify async iterator leak #28997
Conversation
nodejs-github-bot
added
doc
ronag
force-pushed
the
doc-async-iterator
branch
4 times, most recently
from
8a6b51d to
5fb5109
Compare
|
@Trott flaky V8 compile, please restart? |
doc/api/stream.md
Outdated
| @@ -2499,6 +2499,14 @@ and async iterators are provided below. | |||
| })(); | |||
| ``` | |||
|
|
|||
| Async iterators register a permanent error handler. If the iterator is not | |||
| fully consumed, any unhandled stream error will be swallowed. When consuming | |||
| streams using async iterators any errors emitted after `'end'` or `'close'` | |||
There was a problem hiding this comment.
| streams using async iterators any errors emitted after `'end'` or `'close'` | |
| streams using async iterators, any errors emitted after `'end'` or `'close'` |
|
@nodejs/streams |
There was a problem hiding this comment.
I don't think we should land this change.
When a stream is async iterated it will always exit the iteration in a destroyed state, i.e. break or throw will call destroy() on the stream. As a result, we cannot create multiple streams one after the other.
Moreover, creating multiple parallel AsyncIterators out of the same stream is problematic and should not be done: the behavior is going to be very unpredictable (which of the two iterators will get the data? only one will).
What should be documented is that, because it's left in a destroyed state, there will be a 'error' event handler attached to prevent further exceptions to crash the process.
|
Isn’t it possible to create multiple iterators? i.e when using the iterator API directly and not through a for loop? Should we maybe throw if a second iterative is created? |
The semantics of that are currently not what somebody is going to expect. The two iterators are going to compete for the chunks (as they use |
Hence, should we throw if a secondary iterator is created? Also possibly add a note in the docs? |
ronag
force-pushed
the
doc-async-iterator
branch
from
5fb5109 to
952d08a
Compare
|
Updated description in accordance with @mcollina's previous suggestion. |
|
Throwing if there's an attempt to create a second iterator would make sense to me. What do you think @mcollina? |
ronag
force-pushed
the
doc-async-iterator
branch
from
952d08a to
e4de3f0
Compare
|
@Trott: This fails because I didn't rebase master. However, since it's a simple doc change I don't think it's worth a rebase? |
| @@ -2502,6 +2502,9 @@ and async iterators are provided below. | |||
| })(); | |||
| ``` | |||
|
|
|||
| Async iterators register a permanent error handler on the stream to prevent any | |||
| unhandled post-destroy errors. | |||
There was a problem hiding this comment.
Not sure that what I"m about to suggest is a good idea, so I'll defer to everyone else's judgment:
Is it worth re-wording to make it clear that this means the destroy() method?
| unhandled post-destroy errors. | |
| unhandled errors after `destroy()` executes. |
I'm not sure that's an improvement to be honest, but maybe?
|
Landed in d7a4ace |
Clarifies that creating multiple async iterators from the same stream can lead to event listener leak. PR-URL: nodejs#28997 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Clarifies that creating multiple async iterators from the same stream can lead to event listener leak. PR-URL: #28997 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Clarifies that creating multiple async iterators from the same stream can lead to event listener leak.
Checklist