doc: clarify writable.cork method

[GKJCJG]

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

• documentation is changed or added
• commit message follows commit guidelines

[BridgeAR]

I like the new description. I personally would still keep something about the adverse performance impact around though.

[GKJCJG]

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.

[ronag]

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.

[GKJCJG]

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.

[ronag]

LGTM

P.S. I think there is a slight error in your PR description (see the markup for the second checkbox).

[ronag]

@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.

[mcollina]

I find the first/current version more correct than then the second one.

Specifically:

1. 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.
2. 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.
3. Do not use the term “drain”, as it recall a Writable stream term.

[lpinca]

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

It actually depends on the implementation of _writev() and I think this sentence

implementations that implement the writable._writev() method can perform buffered writes in a more optimized manner

with "can" is trying to address this.

[mcollina]

I think something like this is better reflect our implementations and its usage.

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 underlining destination, `writable.cork()`
buffers all the chunks until `writable.uncork()` is called, which will pass them all to  
`writable._writev()`, if present. This prevents an head-of-line blocking situation where data is being buffered while waiting for the first small chunk to be processed.

Note that using `writable.cork()` without implementing `writable._writev()` is likely to have an adverse effect on throughput.

[mcollina]

lgtm

[GKJCJG]

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]

@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.

[BridgeAR]

Lite-CI https://ci.nodejs.org/job/node-test-pull-request-lite-pipeline/4103/

[BridgeAR]

@GKJCJG please run the doc linter once (or the whole one make lint). Seems like there are two linter errors:

01:49:04  Running Markdown linter on docs...
01:49:33  �[4m�[33mdoc/api/stream.md�[39m�[24m
01:49:33    367:72  �[33mwarning�[39m  Remove trailing whitespace  no-trailing-spaces          remark-lint
01:49:33     371:1  �[33mwarning�[39m  Remove 1 line before node   no-consecutive-blank-lines  remark-lint

[BridgeAR]

Landed in e9695d9

@GKJCJG congratulations on your first commit to Node.js! 🎉

I pleased the linter and the commit message while landing.