Skip to content

Commit

Permalink
doc: clarify Readable._read and Readable.push
Browse files Browse the repository at this point in the history
Minor clarifications around Readable._read and Readable.push
to make their implementation/usage easier to understand.

nodejs/node-v0.x-archive#14124 (comment)

Reviewed-By: James M Snell <jasnell@gmail.com>
PR-URL: nodejs/node-v0.x-archive#25591
  • Loading branch information
fresheneesz authored and jasnell committed Aug 4, 2015
1 parent 034b4d5 commit d0b54ea
Showing 1 changed file with 20 additions and 25 deletions.
45 changes: 20 additions & 25 deletions doc/api/stream.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -936,24 +936,22 @@ initialized.

* `size` {Number} Number of bytes to read asynchronously

Note: **Implement this function, but do NOT call it directly.**
Note: **Implement this method, but do NOT call it directly.**

This function should NOT be called directly. It should be implemented
by child classes, and only called by the internal Readable class
methods.
This method is prefixed with an underscore because it is internal to the
class that defines it and should only be called by the internal Readable
class methods. All Readable stream implementations must provide a _read
method to fetch data from the underlying resource.

All Readable stream implementations must provide a `_read` method to
fetch data from the underlying resource.
When _read is called, if data is available from the resource, `_read` should
start pushing that data into the read queue by calling `this.push(dataChunk)`.
`_read` should continue reading from the resource and pushing data until push
returns false, at which point it should stop reading from the resource. Only
when _read is called again after it has stopped should it start reading
more data from the resource and pushing that data onto the queue.

This method is prefixed with an underscore because it is internal to
the class that defines it, and should not be called directly by user
programs. However, you **are** expected to override this method in
your own extension classes.

When data is available, put it into the read queue by calling
`readable.push(chunk)`. If `push` returns false, then you should stop
reading. When `_read` is called again, you should start pushing more
data.
Note: once the `_read()` method is called, it will not be called again until
the `push` method is called.

The `size` argument is advisory. Implementations where a "read" is a
single call that returns data can use this to know how much data to
Expand All @@ -969,19 +967,16 @@ becomes available. There is no need, for example to "wait" until
Buffer encoding, such as `'utf8'` or `'ascii'`
* return {Boolean} Whether or not more pushes should be performed

Note: **This function should be called by Readable implementors, NOT
Note: **This method should be called by Readable implementors, NOT
by consumers of Readable streams.**

The `_read()` function will not be called again until at least one
`push(chunk)` call is made.

The `Readable` class works by putting data into a read queue to be
pulled out later by calling the `read()` method when the `'readable'`
event fires.
If a value other than null is passed, The `push()` method adds a chunk of data
into the queue for subsequent stream processors to consume. If `null` is
passed, it signals the end of the stream (EOF), after which no more data
can be written.

The `push()` method will explicitly insert some data into the read
queue. If it is called with `null` then it will signal the end of the
data (EOF).
The data added with `push` can be pulled out by calling the `read()` method
when the `'readable'`event fires.

This API is designed to be as flexible as possible. For example,
you may be wrapping a lower-level source which has some sort of
Expand Down

0 comments on commit d0b54ea

Please sign in to comment.