Merge nodejs/master

Merge a1d34b3 as of 2017-08-25.
This is an automatically created merge. For any problems please
contact @kunalspathak.

GOVERNANCE.md

@@ -9,9 +9,21 @@ The [nodejs/node](https://github.com/nodejs/node) GitHub repository is
 maintained by Collaborators who are added by the CTC on an ongoing basis.
 
 Individuals identified by the CTC as making significant and valuable
-contributions are made Collaborators and given commit access to the project. If
-you make a significant contribution and are not considered for commit access,
-log an issue or contact a CTC member directly.
+contributions across any Node.js repository may be made Collaborators and given
+commit access to the project. Activities taken into consideration include (but
+are not limited to) the quality of:
+
+* code commits and pull requests
+* documentation commits and pull requests
+* comments on issues and pull requests
+* contributions to the Node.js website
+* assistance provided to end users and novice contributors
+* participation in Working Groups
+* other participation in the wider Node.js community
+
+If individuals making valuable contributions do not believe they have been
+considered for commit access, they may log an issue or contact a CTC member
+directly.
 
 Modifications of the contents of the nodejs/node repository are made on
 a collaborative basis. Anybody with a GitHub account may propose a

deps/v8/src/trap-handler/handler-shared.cc

@@ -23,7 +23,14 @@ namespace v8 {
 namespace internal {
 namespace trap_handler {
 
-THREAD_LOCAL bool g_thread_in_wasm_code = false;
+// We declare this as int rather than bool as a workaround for a glibc bug, in
+// which the dynamic loader cannot handle executables whose TLS area is only
+// 1 byte in size; see https://sourceware.org/bugzilla/show_bug.cgi?id=14898.
+THREAD_LOCAL int g_thread_in_wasm_code = false;
+
+static_assert(sizeof(g_thread_in_wasm_code) > 1,
+              "sizeof(thread_local_var) must be > 1, see "
+              "https://sourceware.org/bugzilla/show_bug.cgi?id=14898");
 
 size_t gNumCodeObjects = 0;
 CodeProtectionInfoListEntry* gCodeObjects = nullptr;

deps/v8/src/trap-handler/trap-handler.h

@@ -65,7 +65,7 @@ inline bool UseTrapHandler() {
   return FLAG_wasm_trap_handler && V8_TRAP_HANDLER_SUPPORTED;
 }
 
-extern THREAD_LOCAL bool g_thread_in_wasm_code;
+extern THREAD_LOCAL int g_thread_in_wasm_code;
 
 inline bool IsThreadInWasm() { return g_thread_in_wasm_code; }
 

doc/api/cli.md

@@ -352,15 +352,15 @@ added: v6.11.0
 -->
 
 Use OpenSSL's default CA store or use bundled Mozilla CA store as supplied by
-current NodeJS version. The default store is selectable at build-time.
+current Node.js version. The default store is selectable at build-time.
 
 Using OpenSSL store allows for external modifications of the store. For most
 Linux and BSD distributions, this store is maintained by the distribution
 maintainers and system administrators. OpenSSL CA store location is dependent on
 configuration of the OpenSSL library but this can be altered at runtime using
-environmental variables.
+environment variables.
 
-The bundled CA store, as supplied by NodeJS, is a snapshot of Mozilla CA store
+The bundled CA store, as supplied by Node.js, is a snapshot of Mozilla CA store
 that is fixed at release time. It is identical on all supported platforms.
 
 See `SSL_CERT_DIR` and `SSL_CERT_FILE`.
@@ -568,10 +568,35 @@ appended to if it does. If an error occurs while attempting to write the
 warning to the file, the warning will be written to stderr instead. This is
 equivalent to using the `--redirect-warnings=file` command-line flag.
 
+### `UV_THREADPOOL_SIZE=size`
+
+Set the number of threads used in libuv's threadpool to `size` threads.
+
+Asynchronous system APIs are used by Node.js whenever possible, but where they
+do not exist, libuv's threadpool is used to create asynchronous node APIs based
+on synchronous system APIs. Node.js APIs that use the threadpool are:
+
+- all `fs` APIs, other than the file watcher APIs and those that are explicitly
+  synchronous
+- `crypto.pbkdf2()`
+- `crypto.randomBytes()`, unless it is used without a callback
+- `crypto.randomFill()`
+- `dns.lookup()`
+- all `zlib` APIs, other than those that are explicitly synchronous
+
+Because libuv's threadpool has a fixed size, it means that if for whatever
+reason any of these APIs takes a long time, other (seemingly unrelated) APIs
+that run in libuv's threadpool will experience degraded performance. In order to
+mitigate this issue, one potential solution is to increase the size of libuv's
+threadpool by setting the `'UV_THREADPOOL_SIZE'` environment variable to a value
+greater than `4` (its current default value).  For more information, see the
+[libuv threadpool documentation][].
+
 [`--openssl-config`]: #cli_openssl_config_file
 [Buffer]: buffer.html#buffer_buffer
 [Chrome Debugging Protocol]: https://chromedevtools.github.io/debugger-protocol-viewer
 [REPL]: repl.html
 [SlowBuffer]: buffer.html#buffer_class_slowbuffer
 [debugger]: debugger.html
 [emit_warning]: process.html#process_process_emitwarning_warning_type_code_ctor
+[libuv threadpool documentation]: http://docs.libuv.org/en/latest/threadpool.html

doc/api/crypto.md

@@ -1559,6 +1559,10 @@ crypto.pbkdf2('secret', 'salt', 100000, 512, 'sha512', (err, derivedKey) => {
 An array of supported digest functions can be retrieved using
 [`crypto.getHashes()`][].
 
+Note that this API uses libuv's threadpool, which can have surprising and
+negative performance implications for some applications, see the
+[`UV_THREADPOOL_SIZE`][] documentation for more information.
+
 ### crypto.pbkdf2Sync(password, salt, iterations, keylen, digest)
 <!-- YAML
 added: v0.9.3
@@ -1717,11 +1721,16 @@ console.log(
   `${buf.length} bytes of random data: ${buf.toString('hex')}`);
 ```
 
-The `crypto.randomBytes()` method will block until there is sufficient entropy.
+The `crypto.randomBytes()` method will not complete until there is
+sufficient entropy available.
 This should normally never take longer than a few milliseconds. The only time
 when generating the random bytes may conceivably block for a longer period of
 time is right after boot, when the whole system is still low on entropy.
 
+Note that this API uses libuv's threadpool, which can have surprising and
+negative performance implications for some applications, see the
+[`UV_THREADPOOL_SIZE`][] documentation for more information.
+
 ### crypto.randomFillSync(buffer[, offset][, size])
 <!-- YAML
 added: v7.10.0
@@ -1782,6 +1791,10 @@ crypto.randomFill(buf, 5, 5, (err, buf) => {
 });
 ```
 
+Note that this API uses libuv's threadpool, which can have surprising and
+negative performance implications for some applications, see the
+[`UV_THREADPOOL_SIZE`][] documentation for more information.
+
 ### crypto.setEngine(engine[, flags])
 <!-- YAML
 added: v0.11.11
@@ -2207,6 +2220,7 @@ the `crypto`, `tls`, and `https` modules and are generally specific to OpenSSL.
 
 [`Buffer`]: buffer.html
 [`EVP_BytesToKey`]: https://www.openssl.org/docs/man1.0.2/crypto/EVP_BytesToKey.html
+[`UV_THREADPOOL_SIZE`]: cli.html#cli_uv_threadpool_size_size
 [`cipher.final()`]: #crypto_cipher_final_outputencoding
 [`cipher.update()`]: #crypto_cipher_update_data_inputencoding_outputencoding
 [`crypto.createCipher()`]: #crypto_crypto_createcipher_algorithm_password

doc/api/dns.md

@@ -620,15 +620,16 @@ but note that changing these files will change the behavior of _all other
 programs running on the same operating system_.
 
 Though the call to `dns.lookup()` will be asynchronous from JavaScript's
-perspective, it is implemented as a synchronous call to getaddrinfo(3) that
-runs on libuv's threadpool. Because libuv's threadpool has a fixed size, it
-means that if for whatever reason the call to getaddrinfo(3) takes a long
-time, other operations that could run on libuv's threadpool (such as filesystem
-operations) will experience degraded performance. In order to mitigate this
-issue, one potential solution is to increase the size of libuv's threadpool by
-setting the `'UV_THREADPOOL_SIZE'` environment variable to a value greater than
-`4` (its current default value). For more information on libuv's threadpool, see
-[the official libuv documentation][].
+perspective, it is implemented as a synchronous call to getaddrinfo(3) that runs
+on libuv's threadpool. This can have surprising negative performance
+implications for some applications, see the [`UV_THREADPOOL_SIZE`][]
+documentation for more information.
+
+Note that various networking APIs will call `dns.lookup()` internally to resolve
+host names. If that is an issue, consider resolving the hostname to and address
+using `dns.resolve()` and using the address instead of a host name. Also, some
+networking APIs (such as [`socket.connect()`][] and [`dgram.createSocket()`][])
+allow the default resolver, `dns.lookup()`, to be replaced.
 
 ### `dns.resolve()`, `dns.resolve*()` and `dns.reverse()`
 
@@ -644,10 +645,14 @@ They do not use the same set of configuration files than what [`dns.lookup()`][]
 uses. For instance, _they do not use the configuration from `/etc/hosts`_.
 
 [`Error`]: errors.html#errors_class_error
+[`UV_THREADPOOL_SIZE`]: cli.html#cli_uv_threadpool_size_size
+[`dgram.createSocket()`]: dgram.html#dgram_dgram_createsocket_options_callback
+[`dns.getServers()`]: #dns_dns_getservers
 [`dns.lookup()`]: #dns_dns_lookup_hostname_options_callback
 [`dns.resolve()`]: #dns_dns_resolve_hostname_rrtype_callback
 [`dns.resolve4()`]: #dns_dns_resolve4_hostname_options_callback
 [`dns.resolve6()`]: #dns_dns_resolve6_hostname_options_callback
+[`dns.resolveAny()`]: #dns_dns_resolveany_hostname_callback
 [`dns.resolveCname()`]: #dns_dns_resolvecname_hostname_callback
 [`dns.resolveMx()`]: #dns_dns_resolvemx_hostname_callback
 [`dns.resolveNaptr()`]: #dns_dns_resolvenaptr_hostname_callback
@@ -656,13 +661,12 @@ uses. For instance, _they do not use the configuration from `/etc/hosts`_.
 [`dns.resolveSoa()`]: #dns_dns_resolvesoa_hostname_callback
 [`dns.resolveSrv()`]: #dns_dns_resolvesrv_hostname_callback
 [`dns.resolveTxt()`]: #dns_dns_resolvetxt_hostname_callback
-[`dns.resolveAny()`]: #dns_dns_resolveany_hostname_callback
-[`dns.getServers()`]: #dns_dns_getservers
-[`dns.setServers()`]: #dns_dns_setservers_servers
 [`dns.reverse()`]: #dns_dns_reverse_ip_callback
+[`dns.setServers()`]: #dns_dns_setservers_servers
+[`socket.connect()`]: net.html#net_socket_connect_options_connectlistener
+[`util.promisify()`]: util.html#util_util_promisify_original
 [DNS error codes]: #dns_error_codes
 [Implementation considerations section]: #dns_implementation_considerations
+[rfc5952]: https://tools.ietf.org/html/rfc5952#section-6
 [supported `getaddrinfo` flags]: #dns_supported_getaddrinfo_flags
 [the official libuv documentation]: http://docs.libuv.org/en/latest/threadpool.html
-[`util.promisify()`]: util.html#util_util_promisify_original
-[rfc5952]: https://tools.ietf.org/html/rfc5952#section-6

doc/api/fs.md

@@ -100,6 +100,13 @@ example `fs.readdirSync('c:\\')` can potentially return a different result than
 `fs.readdirSync('c:')`. For more information, see
 [this MSDN page][MSDN-Rel-Path].
 
+## Threadpool Usage
+
+Note that all file system APIs except `fs.FSWatcher()` and those that are
+explicitly synchronous use libuv's threadpool, which can have surprising and
+negative performance implications for some applications, see the
+[`UV_THREADPOOL_SIZE`][] documentation for more information.
+
 ## WHATWG URL object support
 <!-- YAML
 added: v7.6.0
@@ -2845,6 +2852,7 @@ The following constants are meant for use with the [`fs.Stats`][] object's
 [`ReadDirectoryChangesW`]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa365465%28v=vs.85%29.aspx
 [`ReadStream`]: #fs_class_fs_readstream
 [`URL`]: url.html#url_the_whatwg_url_api
+[`UV_THREADPOOL_SIZE`]: cli.html#cli_uv_threadpool_size_size
 [`WriteStream`]: #fs_class_fs_writestream
 [`event ports`]: http://illumos.org/man/port_create
 [`fs.FSWatcher`]: #fs_class_fs_fswatcher

doc/api/intl.md

@@ -112,7 +112,7 @@ at runtime so that the JS methods would work for all ICU locales. Assuming the
 data file is stored at `/some/directory`, it can be made available to ICU
 through either:
 
-* The [`NODE_ICU_DATA`][] environmental variable:
+* The [`NODE_ICU_DATA`][] environment variable:
 
   ```shell
   env NODE_ICU_DATA=/some/directory node