Skip to content
Permalink
Browse files

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: #30442
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Denys Otrishko <shishugi@gmail.com>
  • Loading branch information
GKJCJG authored and BridgeAR committed Nov 12, 2019
1 parent e2ef1a9 commit 33352c2433b8ef01bbbfba411bad79734d96c8f3
Showing with 10 additions and 7 deletions.
  1. +10 −7 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])`
<!-- YAML

0 comments on commit 33352c2

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