From 521addeec33a289b9be36e7c476ecec536366772 Mon Sep 17 00:00:00 2001 From: Colin Grant <43424668+GKJCJG@users.noreply.github.com> Date: Tue, 12 Nov 2019 10:29:39 -0600 Subject: [PATCH 1/8] Clarify role of writable.cork() The syntax of the sentence describing the role of writable.cork() was unclear. This rephrase aims to make the distinction between writing to the buffer and draining immediately to the underlying resource clearer. --- doc/api/stream.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/api/stream.md b/doc/api/stream.md index 066d85adc493e1..c48c5c3394399a 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -358,9 +358,9 @@ The `writable.cork()` method forces all written data to be buffered in memory. The buffered data will be flushed when either the [`stream.uncork()`][] or [`stream.end()`][stream-end] methods are called. -The primary intent of `writable.cork()` is to avoid a situation where writing -many small chunks of data to a stream do not cause a backup in the internal -buffer that would have an adverse impact on performance. In such situations, +The primary intent of `writable.cork()` is to accommodate a situation in which +it is more performant to write several small chunks to the internal buffer rather +than drain them immediately to the underlying destination. In such situations, implementations that implement the `writable._writev()` method can perform buffered writes in a more optimized manner. From a4c2e36d1824f76d84ef381c886db049bec99648 Mon Sep 17 00:00:00 2001 From: Colin Grant <43424668+GKJCJG@users.noreply.github.com> Date: Thu, 14 Nov 2019 15:09:35 -0600 Subject: [PATCH 2/8] doc: Clarify role of writable.cork() The syntax of the sentence describing the role of writable.cork() was unclear. This rephrase aims to make the distinction between writing to the buffer and draining immediately to the underlying destination clearer - while keeping performance considerations clearly in mind. --- doc/api/stream.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/doc/api/stream.md b/doc/api/stream.md index c48c5c3394399a..f65d247d5fb34e 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -359,10 +359,12 @@ The buffered data will be flushed when either the [`stream.uncork()`][] or [`stream.end()`][stream-end] methods are called. The primary intent of `writable.cork()` is to accommodate a situation in which -it is more performant to write several small chunks to the internal buffer rather -than drain them immediately to the underlying destination. In such situations, -implementations that implement the `writable._writev()` method can perform -buffered writes in a more optimized manner. +it is more performant to write several small chunks to the internal buffer +rather than drain them immediately to the underlying destination. Such +buffering is usually inadvisable as the buffer can rapidly consume available +memory, but where memory needs have been carefully considered, implementations +that implement the `writable._writev()` method can perform buffered writes in +a more optimized manner. See also: [`writable.uncork()`][]. From 61d7d1f31119ccaa23429f92e8fb56aef2e77d13 Mon Sep 17 00:00:00 2001 From: Colin Grant <43424668+GKJCJG@users.noreply.github.com> Date: Thu, 14 Nov 2019 16:11:04 -0600 Subject: [PATCH 3/8] Improving syntax minorly. --- doc/api/stream.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/api/stream.md b/doc/api/stream.md index f65d247d5fb34e..ef14d49cdbdc13 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -361,8 +361,8 @@ The buffered data will be flushed when either the [`stream.uncork()`][] or The primary intent of `writable.cork()` is to accommodate a situation in which it is more performant to write several small chunks to the internal buffer rather than drain them immediately to the underlying destination. Such -buffering is usually inadvisable as the buffer can rapidly consume available -memory, but where memory needs have been carefully considered, implementations +buffering is usually inadvisable as it typically degrades performance, but +where memory needs have been carefully considered, implementations that implement the `writable._writev()` method can perform buffered writes in a more optimized manner. From 3fbb958da0528f39ab857f7a05a5c4a9459f3918 Mon Sep 17 00:00:00 2001 From: Colin Grant <43424668+GKJCJG@users.noreply.github.com> Date: Sun, 17 Nov 2019 09:59:09 -0600 Subject: [PATCH 4/8] Simplify description of performance problems --- doc/api/stream.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/doc/api/stream.md b/doc/api/stream.md index ef14d49cdbdc13..95cbd4dfc7b18f 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -361,10 +361,9 @@ The buffered data will be flushed when either the [`stream.uncork()`][] or The primary intent of `writable.cork()` is to accommodate a situation in which it is more performant to write several small chunks to the internal buffer rather than drain them immediately to the underlying destination. Such -buffering is usually inadvisable as it typically degrades performance, but -where memory needs have been carefully considered, implementations -that implement the `writable._writev()` method can perform buffered writes in -a more optimized manner. +buffering typically degrades performance, but where memory needs have been +carefully considered, implementations that implement the `writable._writev()` +method can perform buffered writes in a more optimized manner. See also: [`writable.uncork()`][]. From 5ba141aa232faedda9049c130f253a6a92ab0333 Mon Sep 17 00:00:00 2001 From: Colin Grant <43424668+GKJCJG@users.noreply.github.com> Date: Thu, 21 Nov 2019 12:31:59 -0600 Subject: [PATCH 5/8] Adopt suggestions from mcollina More detailed explanation of underlying dynamics. --- doc/api/stream.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/doc/api/stream.md b/doc/api/stream.md index 95cbd4dfc7b18f..64bcdf53f92b0a 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -359,13 +359,17 @@ The buffered data will be flushed when either the [`stream.uncork()`][] or [`stream.end()`][stream-end] methods are called. The primary intent of `writable.cork()` is to accommodate a situation in which -it is more performant to write several small chunks to the internal buffer -rather than drain them immediately to the underlying destination. Such -buffering typically degrades performance, but where memory needs have been -carefully considered, implementations that implement the `writable._writev()` -method can perform buffered writes in a more optimized manner. +several small chunks are written to the stream in rapid succession. Instead of +immediately forwarding them to the underlining destination, `writable.cork()` +buffers all the chunks until `writable.uncork()` is called, which will pass +them all to `writable._writev()`, if present. This prevents an head-of-line +blocking situation where data is being buffered while waiting for the first +small chunk to be processed. -See also: [`writable.uncork()`][]. +Note that using `writable.cork()` without implementing `writable._writev()` is +likely to have an adverse effect on throughput. + +See also: [`writable.uncork()`][], [`writable._writev(chunks, callback)`][]. ##### writable.destroy(\[error\])