Skip to content

Commit 4952e2b

Browse files
fresheneeszjasnell
authored andcommitted
doc: clarify Readable._read and Readable.push
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
1 parent 14000b9 commit 4952e2b

File tree

1 file changed

+20
-25
lines changed

1 file changed

+20
-25
lines changed

doc/api/stream.markdown

+20-25
Original file line numberDiff line numberDiff line change
@@ -944,24 +944,22 @@ initialized.
944944

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

947-
Note: **Implement this function, but do NOT call it directly.**
947+
Note: **Implement this method, but do NOT call it directly.**
948948

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

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

956-
This method is prefixed with an underscore because it is internal to
957-
the class that defines it, and should not be called directly by user
958-
programs. However, you **are** expected to override this method in
959-
your own extension classes.
960-
961-
When data is available, put it into the read queue by calling
962-
`readable.push(chunk)`. If `push` returns false, then you should stop
963-
reading. When `_read` is called again, you should start pushing more
964-
data.
961+
Note: once the `_read()` method is called, it will not be called again until
962+
the `push` method is called.
965963

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

980-
Note: **This function should be called by Readable implementors, NOT
978+
Note: **This method should be called by Readable implementors, NOT
981979
by consumers of Readable streams.**
982980

983-
The `_read()` function will not be called again until at least one
984-
`push(chunk)` call is made.
985-
986-
The `Readable` class works by putting data into a read queue to be
987-
pulled out later by calling the `read()` method when the `'readable'`
988-
event fires.
981+
If a value other than null is passed, The `push()` method adds a chunk of data
982+
into the queue for subsequent stream processors to consume. If `null` is
983+
passed, it signals the end of the stream (EOF), after which no more data
984+
can be written.
989985

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

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

0 commit comments

Comments
 (0)