doc: clarify writable.cork method #30442
Conversation
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.
nodejs-github-bot
added
doc
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.
|
Thanks for the feedback. I think it is good to make sure that performance considerations are kept clearly in mind. I've added some verbiage to that effect. |
GKJCJG
changed the title
doc/api/stream.md
Outdated
| 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 |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
|
@GKJCJG Please fix your commits though. The first commit needs to have a correctly formatted message (you can see the linting rules in the travis failure). Will make life easier for whoever lands this change. |
GKJCJG
changed the title
GKJCJG
changed the title
There was a problem hiding this comment.
I find the first/current version more correct than then the second one.
Specifically:
- it is more performant to work in batches (_writev), in all cases where a native resource is involved as it minimizes the JS/C++ transitions. It’s not the buffering of small chunks that’s costly, but rather the overahead of processing them one-by-one.
- Buffering is the key function of streams, and it’s needed to perform backpressure/control flow. The new text implies it’s bad and something to normally avoid and I disagree.
- Do not use the term “drain”, as it recall a Writable stream term.
It actually depends on the implementation of
with "can" is trying to address this. |
|
I think something like this is better reflect our implementations and its usage. |
More detailed explanation of underlying dynamics.
GKJCJG
changed the title
Co-Authored-By: Anna Henningsen <[email protected]>
Co-Authored-By: Anna Henningsen <[email protected]>
|
Travis CI keeps failing at the check of the commit message, but it seems as though it's still using the very first commit message I used before I added the "doc" prefix. Any suggestions for satisfying its commit message linting? |
addaleax
added
the
author ready
|
@GKJCJG Please ignore it. I know it’s super annoying that Travis complains, but whoever merges this will take care of fixing the commit message. |
|
@GKJCJG please run the doc linter once (or the whole one |
BridgeAR
removed
the
author ready
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 <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Denys Otrishko <[email protected]>
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 <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Denys Otrishko <[email protected]>
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 <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Denys Otrishko <[email protected]>
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 <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Denys Otrishko <[email protected]>
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.
Checklist