Skip to content

Commit 33352c2

Browse files
GKJCJGBridgeAR
authored andcommitted
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>
1 parent e2ef1a9 commit 33352c2

File tree

1 file changed

+10
-7
lines changed

1 file changed

+10
-7
lines changed

doc/api/stream.md

+10-7
Original file line numberDiff line numberDiff line change
@@ -358,13 +358,16 @@ The `writable.cork()` method forces all written data to be buffered in memory.
358358
The buffered data will be flushed when either the [`stream.uncork()`][] or
359359
[`stream.end()`][stream-end] methods are called.
360360

361-
The primary intent of `writable.cork()` is to avoid a situation where writing
362-
many small chunks of data to a stream do not cause a backup in the internal
363-
buffer that would have an adverse impact on performance. In such situations,
364-
implementations that implement the `writable._writev()` method can perform
365-
buffered writes in a more optimized manner.
366-
367-
See also: [`writable.uncork()`][].
361+
The primary intent of `writable.cork()` is to accommodate a situation in which
362+
several small chunks are written to the stream in rapid succession. Instead of
363+
immediately forwarding them to the underlying destination, `writable.cork()`
364+
buffers all the chunks until `writable.uncork()` is called, which will pass them
365+
all to `writable._writev()`, if present. This prevents a head-of-line blocking
366+
situation where data is being buffered while waiting for the first small chunk
367+
to be processed. However, use of `writable.cork()` without implementing
368+
`writable._writev()` may have an adverse effect on throughput.
369+
370+
See also: [`writable.uncork()`][], [`writable._writev()`][stream-_writev].
368371

369372
##### `writable.destroy([error])`
370373
<!-- YAML

0 commit comments

Comments
 (0)