doc: stdout/stderr can block when directed to file

[bnoordhuis]

Update the documentation for process.stdout and process.stdout to
clarify that writes can block when stdio is redirected to a file. In
all other cases, it's non-blocking.

[bnoordhuis]

For anyone wondering why stdio to file is a special case: asynchronous file writes need to be done from another thread. Applications that log a lot can easily overwhelm the thread pool.

[ChALkeR]

@bnoordhuis

Applications that log a lot can easily overwhelm the thread pool.

See also #1741 — without redirecting, applications that log a lot can consume all the memory.

[bnoordhuis]

Things get a lot worse when everything has to go through the thread pool first, though. Can I get a LGTM?

[Fishrock123]

Umm, can we at least list some cases when it does and doesn't block?

[bnoordhuis]

I don't mind expanding if you can give me some pointers on what you want it to look like.

It's nuanced, though. Writes to a file don't normally block because of write-back caching, so you don't want to give off an impression that stdio-to-file is always bad.

[bnoordhuis]

@Fishrock123 Ping?

[Fishrock123]

Writes to a file don't normally block because of write-back caching, so you don't want to give off an impression that stdio-to-file is always bad.

Given this causes people grief time and again as seen by various issues, maybe you could add some info in like this?

When it blocks to regular terminal stdout or not is probably the most important, followed by redirected to a file. I think it's worth explaining in good detail here, if possible.

[bnoordhuis]

@Fishrock123 Updated, PTAL.

[Fishrock123]

Ugh, maybe my memory is failing but I thought it was blocking in more instances too? :/

otherwise LGTM.

[MylesBorins]

landed in lts-v4.x-staging as 38a5ae1