Merge nodejs/master

Merge 1e2905f as of 2017-06-16.
This is an automatically created merge. For any problems please
contact @kunalspathak.

BUILDING.md

@@ -65,7 +65,7 @@ Depending on host platform, the selection of toolchains may vary.
 
 #### Unix
 
-* GCC 4.8.5 or newer
+* GCC 4.9.4 or newer
 * Clang 3.4.2 or newer
 
 #### Windows
@@ -80,8 +80,8 @@ Depending on host platform, the selection of toolchains may vary.
 
 Prerequisites:
 
-* `gcc` and `g++` 4.8.5 or newer, or
-* `clang` and `clang++` 3.4.2 or newer
+* `gcc` and `g++` 4.9.4 or newer, or
+* `clang` and `clang++` 3.4.2 or newer (macOS: latest Xcode Command Line Tools)
 * Python 2.6 or 2.7
 * GNU Make 3.81 or newer
 

CHANGELOG.md

@@ -28,7 +28,7 @@ release.
 <tr>
     <td valign="top">
 <b><a href="doc/changelogs/CHANGELOG_V8.md#8.1.2">8.1.2</a></b><br/>
-<a href="doc/changelogs/CHANGELOG_V8.md#8.1.1">8.1.1</a>><br/>
+<a href="doc/changelogs/CHANGELOG_V8.md#8.1.1">8.1.1</a><br/>
 <a href="doc/changelogs/CHANGELOG_V8.md#8.1.0">8.1.0</a><br/>
 <a href="doc/changelogs/CHANGELOG_V8.md#8.0.0">8.0.0</a><br/>
     </td>

Makefile

@@ -924,6 +924,7 @@ lint:
 	@echo "Linting is not available through the source tarball."
 	@echo "Use the git repo instead:" \
 		"$ git clone https://github.com/nodejs/node.git"
+	exit 1
 
 lint-ci: lint
 endif

doc/api/async_hooks.md

@@ -192,8 +192,8 @@ Every new resource is assigned a unique ID.
 ###### `type`
 
 The `type` is a string that represents the type of resource that caused
-`init` to be called. Generally it will correspond the name of the resource's
-constructor.
+`init` to be called. Generally, it will correspond to the name of the
+resource's constructor.
 
 ```
 FSEVENTWRAP, FSREQWRAP, GETADDRINFOREQWRAP, GETNAMEINFOREQWRAP, HTTPPARSER,

doc/api/buffer.md

@@ -447,8 +447,8 @@ changes:
 * `size` {integer} The desired length of the new `Buffer`
 
 Allocates a new `Buffer` of `size` bytes.  If the `size` is larger than
-[`buffer.kMaxLength`] or smaller than 0, a [`RangeError`] will be thrown.
-A zero-length `Buffer` will be created if `size` is 0.
+[`buffer.constants.MAX_LENGTH`] or smaller than 0, a [`RangeError`] will be
+thrown. A zero-length `Buffer` will be created if `size` is 0.
 
 Prior to Node.js 8.0.0, the underlying memory for `Buffer` instances
 created in this way is *not initialized*. The contents of a newly created
@@ -528,8 +528,8 @@ console.log(buf);
 ```
 
 Allocates a new `Buffer` of `size` bytes.  If the `size` is larger than
-[`buffer.kMaxLength`] or smaller than 0, a [`RangeError`] will be thrown.
-A zero-length `Buffer` will be created if `size` is 0.
+[`buffer.constants.MAX_LENGTH`] or smaller than 0, a [`RangeError`] will be
+thrown. A zero-length `Buffer` will be created if `size` is 0.
 
 If `fill` is specified, the allocated `Buffer` will be initialized by calling
 [`buf.fill(fill)`][`buf.fill()`].
@@ -573,8 +573,8 @@ changes:
 * `size` {integer} The desired length of the new `Buffer`
 
 Allocates a new `Buffer` of `size` bytes.  If the `size` is larger than
-[`buffer.kMaxLength`] or smaller than 0, a [`RangeError`] will be thrown.
-A zero-length `Buffer` will be created if `size` is 0.
+[`buffer.constants.MAX_LENGTH`] or smaller than 0, a [`RangeError`] will be
+thrown. A zero-length `Buffer` will be created if `size` is 0.
 
 The underlying memory for `Buffer` instances created in this way is *not
 initialized*. The contents of the newly created `Buffer` are unknown and
@@ -619,8 +619,8 @@ added: v5.10.0
 * `size` {integer} The desired length of the new `Buffer`
 
 Allocates a new `Buffer` of `size` bytes.  If the `size` is larger than
-[`buffer.kMaxLength`] or smaller than 0, a [`RangeError`] will be thrown.
-A zero-length `Buffer` will be created if `size` is 0.
+[`buffer.constants.MAX_LENGTH`] or smaller than 0, a [`RangeError`] will be
+thrown. A zero-length `Buffer` will be created if `size` is 0.
 
 The underlying memory for `Buffer` instances created in this way is *not
 initialized*. The contents of the newly created `Buffer` are unknown and
@@ -2050,6 +2050,9 @@ added: v0.1.90
 Decodes `buf` to a string according to the specified character encoding in
 `encoding`. `start` and `end` may be passed to decode only a subset of `buf`.
 
+The maximum length of a string instance (in UTF-16 code units) is available
+as [`buffer.constants.MAX_STRING_LENGTH`][].
+
 Examples:
 
 ```js
@@ -2507,8 +2510,7 @@ added: v3.0.0
 
 * {integer} The largest size allowed for a single `Buffer` instance
 
-On 32-bit architectures, this value is `(2^30)-1` (~1GB).
-On 64-bit architectures, this value is `(2^31)-1` (~2GB).
+An alias for [`buffer.constants.MAX_LENGTH`][]
 
 Note that this is a property on the `buffer` module returned by
 `require('buffer')`, not on the `Buffer` global or a `Buffer` instance.
@@ -2599,8 +2601,8 @@ deprecated: v6.0.0
 * `size` {integer} The desired length of the new `SlowBuffer`
 
 Allocates a new `Buffer` of `size` bytes.  If the `size` is larger than
-[`buffer.kMaxLength`] or smaller than 0, a [`RangeError`] will be thrown.
-A zero-length `Buffer` will be created if `size` is 0.
+[`buffer.constants.MAX_LENGTH`] or smaller than 0, a [`RangeError`] will be
+thrown. A zero-length `Buffer` will be created if `size` is 0.
 
 The underlying memory for `SlowBuffer` instances is *not initialized*. The
 contents of a newly created `SlowBuffer` are unknown and may contain
@@ -2622,6 +2624,39 @@ buf.fill(0);
 console.log(buf);
 ```
 
+
+## Buffer Constants
+<!-- YAML
+added: REPLACEME
+-->
+
+Note that `buffer.constants` is a property on the `buffer` module returned by
+`require('buffer')`, not on the `Buffer` global or a `Buffer` instance.
+
+### buffer.constants.MAX_LENGTH
+<!-- YAML
+added: REPLACEME
+-->
+
+* {integer} The largest size allowed for a single `Buffer` instance
+
+On 32-bit architectures, this value is `(2^30)-1` (~1GB).
+On 64-bit architectures, this value is `(2^31)-1` (~2GB).
+
+This value is also available as [`buffer.kMaxLength`][].
+
+### buffer.constants.MAX_STRING_LENGTH
+<!-- YAML
+added: REPLACEME
+-->
+
+* {integer} The largest length allowed for a single `string` instance
+
+Represents the largest `length` that a `string` primitive can have, counted
+in UTF-16 code units.
+
+This value may depend on the JS engine that is being used.
+
 [`ArrayBuffer#slice()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer/slice
 [`ArrayBuffer`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer
 [`Buffer.alloc()`]: #buffer_class_method_buffer_alloc_size_fill_encoding
@@ -2652,6 +2687,8 @@ console.log(buf);
 [`buf.slice()`]: #buffer_buf_slice_start_end
 [`buf.values()`]: #buffer_buf_values
 [`buffer.kMaxLength`]: #buffer_buffer_kmaxlength
+[`buffer.constants.MAX_LENGTH`]: #buffer_buffer_constants_max_length
+[`buffer.constants.MAX_STRING_LENGTH`]: #buffer_buffer_constants_max_string_length
 [`util.inspect()`]: util.html#util_util_inspect_object_options
 [RFC1345]: https://tools.ietf.org/html/rfc1345
 [RFC4648, Section 5]: https://tools.ietf.org/html/rfc4648#section-5

doc/api/n-api.md

@@ -406,11 +406,12 @@ added: v8.0.0
 -->
 ```C
 NODE_EXTERN napi_status napi_create_error(napi_env env,
-                                          const char* msg,
+                                          napi_value msg,
                                           napi_value* result);
 ```
 - `[in] env`: The environment that the API is invoked under.
-- `[in] msg`: C string representing the text to be associated with.
+- `[in] msg`: napi_value that references a JavaScript String to be
+used as the message for the Error.
 - `[out] result`: `napi_value` representing the error created.
 
 Returns `napi_ok` if the API succeeded.
@@ -423,11 +424,12 @@ added: v8.0.0
 -->
 ```C
 NODE_EXTERN napi_status napi_create_type_error(napi_env env,
-                                               const char* msg,
+                                               napi_value msg,
                                                napi_value* result);
 ```
 - `[in] env`: The environment that the API is invoked under.
-- `[in] msg`: C string representing the text to be associated with.
+- `[in] msg`: napi_value that references a JavaScript String to be
+used as the message for the Error.
 - `[out] result`: `napi_value` representing the error created.
 
 Returns `napi_ok` if the API succeeded.
@@ -445,7 +447,8 @@ NODE_EXTERN napi_status napi_create_range_error(napi_env env,
                                                 napi_value* result);
 ```
 - `[in] env`: The environment that the API is invoked under.
-- `[in] msg`: C string representing the text to be associated with.
+- `[in] msg`: napi_value that references a JavaScript String to be
+used as the message for the Error.
 - `[out] result`: `napi_value` representing the error created.
 
 Returns `napi_ok` if the API succeeded.
@@ -562,16 +565,17 @@ for (int i = 0; i < 1000000; i++) {
 ```
 
 When nesting scopes, there are cases where a handle from an
-inner scope needs  to live beyond the lifespan of that scope. N-API supports an
+inner scope needs to live beyond the lifespan of that scope. N-API supports an
 'escapable scope' in order to support this case. An escapable scope
-allows one or more handles to be 'promoted' so that they 'escape' the
-current scope and the lifespan of the handle(s) changes from the current
+allows one handle to be 'promoted' so that it 'escapes' the
+current scope and the lifespan of the handle changes from the current
 scope to that of the outer scope.
 
 The methods available to open/close escapable scopes are
 [`napi_open_escapable_handle_scope`][] and [`napi_close_escapable_handle_scope`][].
 
-The request to promote a handle is made through the [`napi_escape_handle`][].
+The request to promote a handle is made through [`napi_escape_handle`][] which
+can only be called once.
 
 #### napi_open_handle_scope
 <!-- YAML
@@ -618,7 +622,7 @@ NODE_EXTERN napi_status
 
 Returns `napi_ok` if the API succeeded.
 
-This API open a new scope from which objects can be promoted
+This API open a new scope from which one object can be promoted
 to the outer scope.
 
 #### napi_close_escapable_handle_scope
@@ -657,9 +661,9 @@ Object in the outer scope.
 
 Returns `napi_ok` if the API succeeded.
 
-This API promotes the handle to the JavaScript object so that it valid
-for the lifetime of the outer scope.
-
+This API promotes the handle to the JavaScript object so that it is valid
+for the lifetime of the outer scope. It can only be called once per scope.
+If it is called more than once an error will be returned.
 
 ### References to objects with a lifespan longer than that of the native method
 In some cases an addon will need to be able to create and reference objects
@@ -1212,13 +1216,13 @@ added: v8.0.0
 -->
 ```C
 napi_status napi_create_symbol(napi_env env,
-                               const char* description,
+                               napi_value description,
                                napi_value* result)
 ```
 
 - `[in] env`: The environment that the API is invoked under.
-- `[in] description`: Null-terminated character buffer representing a
-UTF8-encoded string to describe the symbol.
+- `[in] description`: Optional napi_value which refers to a JavaScript
+String to be set as the description for the symbol.
 - `[out] result`: A `napi_value` representing a JavaScript Symbol.
 
 Returns `napi_ok` if the API succeeded.
@@ -1299,8 +1303,8 @@ napi_status napi_create_string_utf16(napi_env env,
 
 - `[in] env`: The environment that the API is invoked under.
 - `[in] str`: Character buffer representing a UTF16-LE-encoded string.
-- `[in] length`: The length of the string in characters, or -1 if it is
-null-terminated.
+- `[in] length`: The length of the string in two-byte code units, or -1 if
+it is null-terminated.
 - `[out] result`: A `napi_value` representing a JavaScript String.
 
 Returns `napi_ok` if the API succeeded.
@@ -1311,6 +1315,31 @@ The JavaScript String type is described in
 [Section 6.1.4](https://tc39.github.io/ecma262/#sec-ecmascript-language-types-string-type)
 of the ECMAScript Language Specification.
 
+#### *napi_create_string_latin1*
+<!-- YAML
+added: v8.0.0
+-->
+```C
+NAPI_EXTERN napi_status napi_create_string_latin1(napi_env env,
+                                                  const char* str,
+                                                  size_t length,
+                                                  napi_value* result);
+```
+
+- `[in] env`: The environment that the API is invoked under.
+- `[in] str`: Character buffer representing a latin1-encoded string.
+- `[in] length`: The length of the string in bytes, or -1 if it is
+null-terminated.
+- `[out] result`: A `napi_value` representing a JavaScript String.
+
+Returns `napi_ok` if the API succeeded.
+
+This API creates a JavaScript String object from a latin1-encoded C string.
+
+The JavaScript String type is described in
+[Section 6.1.4](https://tc39.github.io/ecma262/#sec-ecmascript-language-types-string-type)
+of the ECMAScript Language Specification.
+
 #### *napi_create_string_utf8*
 <!-- YAML
 added: v8.0.0
@@ -1323,8 +1352,8 @@ napi_status napi_create_string_utf8(napi_env env,
 ```
 
 - `[in] env`: The environment that the API is invoked under.
-- `[in] s`: Character buffer representing a UTF8-encoded string.
-- `[in] length`: The length of the string in characters, or -1 if it is
+- `[in] str`: Character buffer representing a UTF8-encoded string.
+- `[in] length`: The length of the string in bytes, or -1 if it is
 null-terminated.
 - `[out] result`: A `napi_value` representing a JavaScript String.