Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: clarify writable.cork method #30442

Closed
wants to merge 8 commits into from
Closed

doc: clarify writable.cork method #30442

Changes from 3 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
521adde
Clarify role of writable.cork()
GKJCJG Nov 12, 2019
a4c2e36
doc: Clarify role of writable.cork()
GKJCJG Nov 14, 2019
61d7d1f
Improving syntax minorly.
GKJCJG Nov 14, 2019
3fbb958
Simplify description of performance problems
GKJCJG Nov 17, 2019
5ba141a
Adopt suggestions from mcollina
GKJCJG Nov 21, 2019
845738c
removing forbidden strings and fixing link.
GKJCJG Nov 21, 2019
cde9d5f
Update doc/api/stream.md
GKJCJG Dec 3, 2019
c2b161a
Update doc/api/stream.md
GKJCJG Dec 3, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
12 changes: 7 additions & 5 deletions doc/api/stream.md
View file
Open in desktop
Expand Up @@ -358,11 +358,13 @@ 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.
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
Copy link
Member

@ronag ronag Nov 14, 2019 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Such buffering is usually inadvisable as it typically degrades performance

I don't think degraded performance is every advisable. This could be a bit more simple.

Such buffering typically degrades performance

Also it could be a bit more explicit. Why and how does it degrade performance? I would think it actually is just as likely to improve performance (if _writev is implemented) at a cost of latency and memory usage? Do we have any benchmarks to clarify this?

Hint, should probably mention latency and memory usage more explicitly.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for your suggestion regarding the phrasing. I have modified the sentence accordingly. Regarding the details of performance degradation due to buffering, I view these as beyond the scope of the current change. They are described in detail in https://nodejs.org/api/stream.html#stream_buffering and https://nodejs.org/api/stream.html#stream_writable_write_chunk_encoding_callback and referred to frequently throughout the description of the Stream API, and my intent is not to provide additional detail here, but only to improve the structure of a sentence that was not clearly interpretable as it stood.

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()`][].

Expand Down