Repository navigation
doc: Unclear relationship between _read and stream.push return value #38586
Description
Activity
- changed the title
[-]doc: Readable stream `_read(size)` stream.push [/-][+]doc: Unclear relationship between `_read` and `stream.push` return value[/+]on May 7, 2021 You should pay attention to
.push()'s return value no matter where you call it because you don't know when the internal buffer will fill up. Even the size argument passed to_read()is labeled as "advisory" (which is not documented as being the exact number of bytes left to fill the internal buffer) and you can also push more data than that value anyway (especially where it's more convenient/efficient to grab in larger chunks from upstream).Paying attention to the return value is most important if it's possible for
.push()to be called more than once in your_read()handler because if.push()returnedtrueafter the first call, there's no point in calling it again because then you're just unnecessarily increasing memory usage of the stream at that point.That makes a little more sense. How would one utilize the return value of
stream.push(...)if they only call it once from the_readfunction? The stream shouldn't be trying to read more data if the buffer is full, right? If it is, how can we tell when it's okay to read more data in without pushing?The stream shouldn't be trying to read more data if the buffer is full, right?
Without checking, I believe this is the case, yes.
Reacted by Shaun KeysOk, I think I know enough to start working on a pull request then, since someone will have to check it before it makes it into production, regardless. I've never updated node's documentation before though. Is it just the
.mdfiles in the docs folder?Is it just the
.mdfiles in the docs folder?Yes that's correct. You can use
make test-doc -jto run the linter and tests on your local machine, andmake docserve -jto preview the HTML rendered version.- added a commit that references this issue
on May 18, 2021 - added a commit that references this issue
on Jun 11, 2021 - added a commit that references this issue
on May 22, 2026
📗 API Reference Docs Problem
Location
Section of the site where the content exists
Affected URL(s):
Description
Concise explanation of the problem
The documentation for implementing a readable stream indicates that the
_readfunction should continue reading from the resource untilstream.pushreturns false. When I implemented my stream this way, I saw the opposite behavior.stream._readwas called every time it ranstream.push(...), resulting in hundreds of concurrent read operations.More Detail
I quickly noticed a memory leak in my application, because
readable._readwas getting called every time I ranreadable.push(...)(when the buffer was belowhighWaterMark), which meant there may be hundreds of concurrent read operations on the same resource. I would like to reword this section to eliminate this ambiguity and clarify that the_readfunction may be called multiple times before reaching thehighWaterMark.I would be interested in contributing to this, but I would want some clarification first. Why would we need to listen to the result of
stream.push(...)if_readdoesn't get called when the buffer is full? For edge cases where data is pushed outside the_readfunction,stream.push(...)'s return value is documented here, but it doesn't seem to have a use from within_read.submit a pull request.