Skip to content

Commit

Permalink
doc: make sure that calls to .read() are looped
Browse files Browse the repository at this point in the history
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 <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: Ruben Bridgewater <[email protected]>
  • Loading branch information
mcollina authored and MylesBorins committed May 16, 2019
1 parent 82dd321 commit 530f005
Show file tree
Hide file tree
Showing 3 changed files with 35 additions and 20 deletions.
30 changes: 16 additions & 14 deletions doc/api/buffer.md
Original file line number Diff line number Diff line change
Expand Up @@ -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);
}
});
```

Expand Down Expand Up @@ -2558,15 +2559,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);
}
});
```

Expand Down
21 changes: 15 additions & 6 deletions doc/api/crypto.md
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down Expand Up @@ -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);
Expand Down Expand Up @@ -944,6 +945,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'));
Expand Down Expand Up @@ -1036,6 +1039,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'));
Expand Down Expand Up @@ -1678,6 +1683,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);
Expand Down Expand Up @@ -1718,6 +1725,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);
Expand Down
4 changes: 4 additions & 0 deletions doc/api/stream.md
Original file line number Diff line number Diff line change
Expand Up @@ -1012,6 +1012,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.
Expand Down

0 comments on commit 530f005

Please sign in to comment.