Skip to content

Commit

Permalink
doc: readable event clarification
Browse files Browse the repository at this point in the history
per nodejs/node-v0.x-archive#14597

Indicate that `'readable'` indicates only that data can
be read from the stream, not that there is actually data
to be consumed. `readable.read([size])` can still return
null. Includes an example that illustrates the point.

Reviewed-By: James M Snell <jasnell@gmail.com>
PR-URL: nodejs/node-v0.x-archive#25591
  • Loading branch information
jasnell committed Aug 4, 2015
1 parent b6378f0 commit 881d9be
Showing 1 changed file with 26 additions and 0 deletions.
26 changes: 26 additions & 0 deletions doc/api/stream.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -167,6 +167,32 @@ again when more data is available.
The `readable` event is not emitted in the "flowing" mode with the
sole exception of the last one, on end-of-stream.

Note that the `'readable'` event indicates only that data *can* be
read from the stream. It does not indicate whether there is actual
data to be consumed. The callback passed to handle the `'readable'`
event must be prepared to handle a `null` response from
`readable.read([size])`. For instance, in the following example, `foo.txt`
is an empty file:

```javascript
var fs = require('fs');
var rr = fs.createReadStream('foo.txt');
rr.on('readable', function() {
console.log('readable:', rr.read());
});
rr.on('end', function() {
console.log('end');
});
```

The output of running this script is:

```
bash-3.2$ node test.js
readable: null
end
```

#### Event: 'data'

* `chunk` {Buffer | String} The chunk of data.
Expand Down

0 comments on commit 881d9be

Please sign in to comment.