@@ -944,24 +944,22 @@ initialized.
944
944
945
945
* ` size ` {Number} Number of bytes to read asynchronously
946
946
947
- Note: ** Implement this function , but do NOT call it directly.**
947
+ Note: ** Implement this method , but do NOT call it directly.**
948
948
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.
952
953
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.
955
960
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.
965
963
966
964
The ` size ` argument is advisory. Implementations where a "read" is a
967
965
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
977
975
Buffer encoding, such as ` 'utf8' ` or ` 'ascii' `
978
976
* return {Boolean} Whether or not more pushes should be performed
979
977
980
- Note: ** This function should be called by Readable implementors, NOT
978
+ Note: ** This method should be called by Readable implementors, NOT
981
979
by consumers of Readable streams.**
982
980
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.
989
985
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.
993
988
994
989
This API is designed to be as flexible as possible. For example,
995
990
you may be wrapping a lower-level source which has some sort of
0 commit comments