Skip to content
Permalink
Browse files

doc: make sure that calls to .read() are looped

The 'readable' event assumes that calls to readable.read() happens
within that event handler until readable.read() returns null.

Fixes: #20503
PR-URL: #25375
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
  • Loading branch information...
mcollina authored and addaleax committed Jan 7, 2019
1 parent 837ca76 commit 67782613bb8005db582535d8fffdf94f72de790b
Showing with 35 additions and 20 deletions.
  1. +16 −14 doc/api/buffer.md
  2. +15 −6 doc/api/crypto.md
  3. +4 −0 doc/api/stream.md
@@ -641,15 +641,16 @@ then copying out the relevant bits.
const store = [];
socket.on('readable', () => {
const data = socket.read();
let data;
while (null !== (data = readable.read())) {
// Allocate for retained data
const sb = Buffer.allocUnsafeSlow(10);
// Allocate for retained data
const sb = Buffer.allocUnsafeSlow(10);
// Copy the data into the new allocation
data.copy(sb, 0, 0, 10);
// Copy the data into the new allocation
data.copy(sb, 0, 0, 10);
store.push(sb);
store.push(sb);
}
});
```

@@ -2561,15 +2562,16 @@ un-pooled `Buffer` instance using `SlowBuffer` then copy out the relevant bits.
const store = [];
socket.on('readable', () => {
const data = socket.read();
let data;
while (null !== (data = readable.read())) {
// Allocate for retained data
const sb = SlowBuffer(10);
// Allocate for retained data
const sb = SlowBuffer(10);
// Copy the data into the new allocation
data.copy(sb, 0, 0, 10);
// Copy the data into the new allocation
data.copy(sb, 0, 0, 10);
store.push(sb);
store.push(sb);
}
});
```

@@ -200,9 +200,10 @@ const cipher = crypto.createCipheriv(algorithm, key, iv);
let encrypted = '';
cipher.on('readable', () => {
const data = cipher.read();
if (data)
encrypted += data.toString('hex');
let chunk;
while (null !== (chunk = cipher.read())) {
encrypted += chunk.toString('hex');
}
});
cipher.on('end', () => {
console.log(encrypted);
@@ -383,9 +384,9 @@ const decipher = crypto.createDecipheriv(algorithm, key, iv);
let decrypted = '';
decipher.on('readable', () => {
const data = decipher.read();
if (data)
decrypted += data.toString('utf8');
while (null !== (chunk = decipher.read())) {
decrypted += chunk.toString('utf8');
}
});
decipher.on('end', () => {
console.log(decrypted);
@@ -941,6 +942,8 @@ const crypto = require('crypto');
const hash = crypto.createHash('sha256');
hash.on('readable', () => {
// Only one element is going to be produced by the
// hash stream.
const data = hash.read();
if (data) {
console.log(data.toString('hex'));
@@ -1033,6 +1036,8 @@ const crypto = require('crypto');
const hmac = crypto.createHmac('sha256', 'a secret');
hmac.on('readable', () => {
// Only one element is going to be produced by the
// hash stream.
const data = hmac.read();
if (data) {
console.log(data.toString('hex'));
@@ -1762,6 +1767,8 @@ const hash = crypto.createHash('sha256');
const input = fs.createReadStream(filename);
input.on('readable', () => {
// Only one element is going to be produced by the
// hash stream.
const data = input.read();
if (data)
hash.update(data);
@@ -1807,6 +1814,8 @@ const hmac = crypto.createHmac('sha256', 'a secret');
const input = fs.createReadStream(filename);
input.on('readable', () => {
// Only one element is going to be produced by the
// hash stream.
const data = input.read();
if (data)
hmac.update(data);
@@ -1011,6 +1011,10 @@ readable.on('readable', () => {
});
```

Note that the `while` loop is necessary when processing data with
`readable.read()`. Only after `readable.read()` returns `null`,
[`'readable'`]() will be emitted.

A `Readable` stream in object mode will always return a single item from
a call to [`readable.read(size)`][stream-read], regardless of the value of the
`size` argument.

0 comments on commit 6778261

Please sign in to comment.
You can’t perform that action at this time.