@@ -936,24 +936,22 @@ initialized.
936936
937937* ` size ` {Number} Number of bytes to read asynchronously
938938
939- Note: ** Implement this function , but do NOT call it directly.**
939+ Note: ** Implement this method , but do NOT call it directly.**
940940
941- This function should NOT be called directly. It should be implemented
942- by child classes, and only called by the internal Readable class
943- methods.
941+ This method is prefixed with an underscore because it is internal to the
942+ class that defines it and should only be called by the internal Readable
943+ class methods. All Readable stream implementations must provide a _ read
944+ method to fetch data from the underlying resource.
944945
945- All Readable stream implementations must provide a ` _read ` method to
946- fetch data from the underlying resource.
946+ When _ read is called, if data is available from the resource, ` _read ` should
947+ start pushing that data into the read queue by calling ` this.push(dataChunk) ` .
948+ ` _read ` should continue reading from the resource and pushing data until push
949+ returns false, at which point it should stop reading from the resource. Only
950+ when _ read is called again after it has stopped should it start reading
951+ more data from the resource and pushing that data onto the queue.
947952
948- This method is prefixed with an underscore because it is internal to
949- the class that defines it, and should not be called directly by user
950- programs. However, you ** are** expected to override this method in
951- your own extension classes.
952-
953- When data is available, put it into the read queue by calling
954- ` readable.push(chunk) ` . If ` push ` returns false, then you should stop
955- reading. When ` _read ` is called again, you should start pushing more
956- data.
953+ Note: once the ` _read() ` method is called, it will not be called again until
954+ the ` push ` method is called.
957955
958956The ` size ` argument is advisory. Implementations where a "read" is a
959957single call that returns data can use this to know how much data to
@@ -969,19 +967,16 @@ becomes available. There is no need, for example to "wait" until
969967 Buffer encoding, such as ` 'utf8' ` or ` 'ascii' `
970968* return {Boolean} Whether or not more pushes should be performed
971969
972- Note: ** This function should be called by Readable implementors, NOT
970+ Note: ** This method should be called by Readable implementors, NOT
973971by consumers of Readable streams.**
974972
975- The ` _read() ` function will not be called again until at least one
976- ` push(chunk) ` call is made.
977-
978- The ` Readable ` class works by putting data into a read queue to be
979- pulled out later by calling the ` read() ` method when the ` 'readable' `
980- event fires.
973+ If a value other than null is passed, The ` push() ` method adds a chunk of data
974+ into the queue for subsequent stream processors to consume. If ` null ` is
975+ passed, it signals the end of the stream (EOF), after which no more data
976+ can be written.
981977
982- The ` push() ` method will explicitly insert some data into the read
983- queue. If it is called with ` null ` then it will signal the end of the
984- data (EOF).
978+ The data added with ` push ` can be pulled out by calling the ` read() ` method
979+ when the ` 'readable' ` event fires.
985980
986981This API is designed to be as flexible as possible. For example,
987982you may be wrapping a lower-level source which has some sort of
0 commit comments