@@ -164,6 +164,34 @@ readable.on('readable', function() {
164164Once the internal buffer is drained, a ` readable ` event will fire
165165again when more data is available.
166166
167+ The ` readable ` event is not emitted in the "flowing" mode with the
168+ sole exception of the last one, on end-of-stream.
169+
170+ The 'readable' event indicates that the stream has new information:
171+ either new data is available or the end of the stream has been reached.
172+ In the former case, ` .read() ` will return that data. In the latter case,
173+ ` .read() ` will return null. For instance, in the following example, ` foo.txt `
174+ is an empty file:
175+
176+ ``` javascript
177+ var fs = require (' fs'
178+ var rr = fs .createReadStream (' foo.txt'
179+ rr .on (' readable' function () {
180+ console .log (' readable:' rr .read ());
181+ });
182+ rr .on (' end' function () {
183+ console .log (' end'
184+ });
185+ ```
186+
187+ The output of running this script is:
188+
189+ ```
190+ bash-3.2$ node test.js
191+ readable: null
192+ end
193+ ```
194+
167195#### Event: 'data'
168196
169197* ` chunk ` {Buffer | String} The chunk of data.
@@ -221,7 +249,9 @@ returns it. If there is no data available, then it will return
221249` null ` .
222250
223251If you pass in a ` size ` argument, then it will return that many
224- bytes. If ` size ` bytes are not available, then it will return ` null ` .
252+ bytes. If ` size ` bytes are not available, then it will return ` null ` ,
253+ unless we've ended, in which case it will return the data remaining
254+ in the buffer.
225255
226256If you do not specify a ` size ` argument, then it will return all the
227257data in the internal buffer.
@@ -243,6 +273,9 @@ readable.on('readable', function() {
243273If this method returns a data chunk, then it will also trigger the
244274emission of a [ ` 'data' ` event] [ ] .
245275
276+ Note that calling ` readable.read([size]) ` after the ` end ` event has been
277+ triggered will return ` null ` . No runtime error will be raised.
278+
246279#### readable.setEncoding(encoding)
247280
248281* ` encoding ` {String} The encoding to use.
@@ -414,6 +447,9 @@ parser, which needs to "un-consume" some data that it has
414447optimistically pulled out of the source, so that the stream can be
415448passed on to some other party.
416449
450+ Note that ` stream.unshift(chunk) ` cannot be called after the ` end ` event
451+ has been triggered; a runtime error will be raised.
452+
417453If you find that you must often call ` stream.unshift(chunk) ` in your
418454programs, consider implementing a [ Transform] [ ] stream instead. (See API
419455for Stream Implementors, below.)
@@ -452,6 +488,13 @@ function parseHeader(stream, callback) {
452488 }
453489}
454490```
491+ Note that, unlike ` stream.push(chunk) ` , ` stream.unshift(chunk) ` will not
492+ end the reading process by resetting the internal reading state of the
493+ stream. This can cause unexpected results if ` unshift ` is called during a
494+ read (i.e. from within a ` _read ` implementation on a custom stream). Following
495+ the call to ` unshift ` with an immediate ` stream.push('') ` will reset the
496+ reading state appropriately, however it is best to simply avoid calling
497+ ` unshift ` while in the process of performing a read.
455498
456499#### readable.wrap(stream)
457500
@@ -883,6 +926,10 @@ SimpleProtocol.prototype._read = function(n) {
883926 // back into the read queue so that our consumer will see it.
884927 var b = chunk .slice (split);
885928 this .unshift (b);
929+ // calling unshift by itself does not reset the reading state
930+ // of the stream; since we're inside _read, doing an additional
931+ // push('') will reset the state appropriately.
932+ this .push (' '
886933
887934 // and let them know that we are done parsing the header.
888935 this .emit (' header' this .header );
@@ -922,24 +969,22 @@ initialized.
922969
923970* ` size ` {Number} Number of bytes to read asynchronously
924971
925- Note: ** Implement this function , but do NOT call it directly.**
972+ Note: ** Implement this method , but do NOT call it directly.**
926973
927- This function should NOT be called directly. It should be implemented
928- by child classes, and only called by the internal Readable class
929- methods.
974+ This method is prefixed with an underscore because it is internal to the
975+ class that defines it and should only be called by the internal Readable
976+ class methods. All Readable stream implementations must provide a _ read
977+ method to fetch data from the underlying resource.
930978
931- All Readable stream implementations must provide a ` _read ` method to
932- fetch data from the underlying resource.
933-
934- This method is prefixed with an underscore because it is internal to
935- the class that defines it, and should not be called directly by user
936- programs. However, you ** are** expected to override this method in
937- your own extension classes.
979+ When _ read is called, if data is available from the resource, ` _read ` should
980+ start pushing that data into the read queue by calling ` this.push(dataChunk) ` .
981+ ` _read ` should continue reading from the resource and pushing data until push
982+ returns false, at which point it should stop reading from the resource. Only
983+ when _ read is called again after it has stopped should it start reading
984+ more data from the resource and pushing that data onto the queue.
938985
939- When data is available, put it into the read queue by calling
940- ` readable.push(chunk) ` . If ` push ` returns false, then you should stop
941- reading. When ` _read ` is called again, you should start pushing more
942- data.
986+ Note: once the ` _read() ` method is called, it will not be called again until
987+ the ` push ` method is called.
943988
944989The ` size ` argument is advisory. Implementations where a "read" is a
945990single call that returns data can use this to know how much data to
@@ -955,19 +1000,16 @@ becomes available. There is no need, for example to "wait" until
9551000 Buffer encoding, such as ` 'utf8' ` or ` 'ascii' `
9561001* return {Boolean} Whether or not more pushes should be performed
9571002
958- Note: ** This function should be called by Readable implementors, NOT
1003+ Note: ** This method should be called by Readable implementors, NOT
9591004by consumers of Readable streams.**
9601005
961- The ` _read() ` function will not be called again until at least one
962- ` push(chunk) ` call is made.
963-
964- The ` Readable ` class works by putting data into a read queue to be
965- pulled out later by calling the ` read() ` method when the ` 'readable' `
966- event fires.
1006+ If a value other than null is passed, The ` push() ` method adds a chunk of data
1007+ into the queue for subsequent stream processors to consume. If ` null ` is
1008+ passed, it signals the end of the stream (EOF), after which no more data
1009+ can be written.
9671010
968- The ` push() ` method will explicitly insert some data into the read
969- queue. If it is called with ` null ` then it will signal the end of the
970- data (EOF).
1011+ The data added with ` push ` can be pulled out by calling the ` read() ` method
1012+ when the ` 'readable' ` event fires.
9711013
9721014This API is designed to be as flexible as possible. For example,
9731015you may be wrapping a lower-level source which has some sort of
@@ -1315,7 +1357,7 @@ for examples and testing, but there are occasionally use cases where
13151357it can come in handy as a building block for novel sorts of streams.
13161358
13171359
1318- ## Simplified Constructor API
1360+ ## Simplified Constructor API
13191361
13201362<!-- type=misc-->
13211363
0 commit comments