doc: clarify readable._read() and pipe() error behavior#62196
Open
kovan wants to merge 1 commit intonodejs:mainfrom
Open
doc: clarify readable._read() and pipe() error behavior#62196kovan wants to merge 1 commit intonodejs:mainfrom
kovan wants to merge 1 commit intonodejs:mainfrom
Conversation
- Rewrite readable._read() description to resolve contradictory statements about when _read() is called relative to push(). The new text clarifies that: push() may be called multiple times until it returns false; _read() will not be called again until push() provides non-empty data; and if data is not immediately available, push() should be called asynchronously when data arrives. - Clarify pipe() error caveat to specify that when the source stream is destroyed or emits an error, the destination is not closed automatically. Recommend stream.pipeline() for automatic cleanup. Verified against source: - lib/internal/streams/readable.js: kReading flag set before _read(), cleared in push(); maybeReadMore_ loops while kReading is unset - pipe() only listens for 'error' on destination, not on source Fixes: nodejs#42291 Fixes: nodejs#45072 Fixes: nodejs#46908 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
nodejs-github-bot
added
doc
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Rewrite
readable._read()description — the existing text containedthree statements that appeared contradictory and confused implementors
(see stream.readable._read() description is unclear #42291). The new text clearly explains:
push()may be calledmultiple times within
_read()until it returnsfalse;_read()willnot be called again until
push()provides non-empty data; and if data isnot immediately available,
push()should be called asynchronously whendata arrives (see doc, stream: incomplete readable._read description #45072, where mcollina confirmed this is how it works)
Clarify
readable.pipe()error caveat — the existing wording "if theReadable stream emits an error" was ambiguous about what triggers the
behavior (see Potentially wrong docs in readable.pipe(destination) about not cleaning up writable #46908). Clarified to include
destroy()and added arecommendation to use
stream.pipeline()for automatic cleanup, sincepipe()does not listen for errors on the source streamAll changes verified against
lib/internal/streams/readable.js:kReadingflag is set before_read()(line 740), cleared inpush()(line 506);
maybeReadMore_loops whilekReadingis unset (line 896)pipe()only attaches an'error'listener ondest(line 1047), noton
srcFixes: #42291
Fixes: #45072
Fixes: #46908