doc: threadpool size, and APIs using the pool

[sam-github]

Not knowing which APIs use libuv's threadpool can lead to surprising
performance problems. Document the APIs, and also document
UV_THREADPOOL_SIZE, which can be used to fix problems.

Checklist

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

Affected core subsystem(s)

doc

[sam-github]

Did I get all the threadpool-using APIs, @bnoordhuis ?

[mscdex]

An asterisk or something should be added here to note this is only when a callback is supplied, which activates async mode.

[mscdex]

We're also missing the asynchronous zlib functions. For example:

• zlib.deflate()
• zlib.deflateRaw()
• zlib.inflate()
• zlib.inflateRaw()
• zlib.gzip()
• zlib.gunzip()
• zlib.unzip()

Also, we're missing crypto.pbkdf2().

There could be others I'm missing, so this might warrant a more thorough investigation to be extra sure this is all of them.

[mscdex]

Minor nit: this is really fs.*() with the exception of fs.*Sync().

[mscdex]

s/APIS/APIs/

[mscdex]

minor nit: s/on/in/

[mscdex]

It might be beneficial to add a short note that some functions accept a custom lookup function (e.g. net.Socket and now dgram both support this feature), so that you can more easily share a function that calls dns.resolve() instead.

[jasnell]

As @mscdex notes, the *Sync variants do not, correct?

[jasnell]

With the very recent addition of the Node implementation of v8::Platform, I believe the V8 microtask queue for Promises also now uses the libuv threadpool if I'm not mistaken. /cc @matthewloring

[mscdex]

If V8 is now using only the libuv threadpool, then that probably includes other things as well, at least the optimizer and GC...

[matthewloring]

The Node implementation of v8::Platform originally used the libuv threadpool but the final implementation manages its own independent pool of libuv threads. The size of that pool is configured here: https://github.com/nodejs/node/blob/master/src/node.cc#L261.

[jasnell]

@matthewloring ... Thank you for the clarification!! :-) It may still be worth mentioning that somehow!

[sam-github]

@jasnell@mscdex PTAL

@mscdex I searched for usage of uv_queue_work, I think this has all the thread pool APIs, thanks for the reminder about the kdf and zlib

@jasnell I don't know anything about the v8 threadpool, and it doesn't have any interaction with libuvs, I'll leave documenting it to someone else (if it needs docs, I'm not even sure if its existence is user visible).

[mscdex]

Minor nit: i think there should either be another comma after `dns.lookup()` or it should be placed in parentheses instead ('allow the default resolver (`dns.lookup()`) to be replaced').

[mscdex]

Just one more minor nit, but otherwise LGTM.

[jasnell]

That's fair @sam-github

I'd like to see if we can pull together a more comprehensive guide on this stuff as a separate doc.

This pr LGTM!

[sam-github]

Thanks for the reviews.