From 530f005d7da31dfc343343b3715896e004a2a466 Mon Sep 17 00:00:00 2001
From: Matteo Collina <hello@matteocollina.com>
Date: Mon, 7 Jan 2019 15:37:34 +0100
Subject: [PATCH] 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: https://github.com/nodejs/node/issues/20503
PR-URL: https://github.com/nodejs/node/pull/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>
---
 doc/api/buffer.md | 30 ++++++++++++++++--------------
 doc/api/crypto.md | 21 +++++++++++++++------
 doc/api/stream.md |  4 ++++
 3 files changed, 35 insertions(+), 20 deletions(-)

diff --git a/doc/api/buffer.md b/doc/api/buffer.md
index 97fc170c02c9c6..73405ea95412f9 100644
--- a/doc/api/buffer.md
+++ b/doc/api/buffer.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);
+  }
 });
 ```
 
@@ -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);
+  }
 });
 ```
 
diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index 79d30b580d8cba..b58f4ad0804021 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -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);
@@ -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'));
@@ -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'));
@@ -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);
@@ -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);
diff --git a/doc/api/stream.md b/doc/api/stream.md
index 70c43e73666db0..ca85ec69d86fd0 100644
--- a/doc/api/stream.md
+++ b/doc/api/stream.md
@@ -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.