From 33352c2433b8ef01bbbfba411bad79734d96c8f3 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] 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. PR-URL: https://github.com/nodejs/node/pull/30442 Reviewed-By: Ruben Bridgewater Reviewed-By: Luigi Pinca Reviewed-By: Matteo Collina Reviewed-By: Anna Henningsen Reviewed-By: Denys Otrishko --- doc/api/stream.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/doc/api/stream.md b/doc/api/stream.md index 520572ea193991..57892943314845 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -358,13 +358,16 @@ 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, -implementations that implement the `writable._writev()` method can perform -buffered writes in a more optimized manner. - -See also: [`writable.uncork()`][]. +The primary intent of `writable.cork()` is to accommodate a situation in which +several small chunks are written to the stream in rapid succession. Instead of +immediately forwarding them to the underlying destination, `writable.cork()` +buffers all the chunks until `writable.uncork()` is called, which will pass them +all to `writable._writev()`, if present. This prevents a head-of-line blocking +situation where data is being buffered while waiting for the first small chunk +to be processed. However, use of `writable.cork()` without implementing +`writable._writev()` may have an adverse effect on throughput. + +See also: [`writable.uncork()`][], [`writable._writev()`][stream-_writev]. ##### `writable.destroy([error])`