diff options
Diffstat (limited to 'doc/api/v8.md')
| -rw-r--r-- | doc/api/v8.md | 44 |
1 files changed, 33 insertions, 11 deletions
diff --git a/doc/api/v8.md b/doc/api/v8.md index b745ac92ba..a589a0fbb1 100644 --- a/doc/api/v8.md +++ b/doc/api/v8.md @@ -1,17 +1,29 @@ # V8 - Stability: 2 - Stable +The `v8` module exposes APIs that are specific to the version of [V8][] +built into the Node.js binary. It can be accessed using: -This module exposes events and interfaces specific to the version of [V8][] -built with Node.js. These interfaces are subject to change by upstream and are -therefore not covered under the stability index. +```js +const v8 = require('v8'); +``` + +*Note*: The APIs and implementation are subject to change at any time. ## v8.getHeapStatistics() <!-- YAML added: v1.0.0 --> -Returns an object with the following properties +Returns an object with the following properties: + +* `total_heap_size` {number} +* `total_heap_size_executable` {number} +* `total_physical_size` {number} +* `total_available_size` {number} +* `used_heap_size` {number} +* `heap_size_limit` {number} + +For example: ```js { @@ -30,11 +42,19 @@ added: v6.0.0 --> Returns statistics about the V8 heap spaces, i.e. the segments which make up -the V8 heap. Order of heap spaces nor availability of a heap space can be -guaranteed as the statistics are provided via the V8 `GetHeapSpaceStatistics` -function. +the V8 heap. Neither the ordering of heap spaces, nor the availability of a +heap space can be guaranteed as the statistics are provided via the V8 +[`GetHeapSpaceStatistics`][] function and may change from one V8 version to the +next. + +The value returned is an array of objects containing the following properties: +* `space_name` {string} +* `space_size` {number} +* `space_used_size` {number} +* `space_available_size` {number} +* `physical_space_size` {number} -Example result: +For example: ``` [ @@ -81,9 +101,10 @@ Example result: added: v1.0.0 --> -Set additional V8 command line flags. Use with care; changing settings +The `v8.setFlagsFromString()` method can be used to programmatically set +V8 command line flags. This method should be used with care. Changing settings after the VM has started may result in unpredictable behavior, including -crashes and data loss. Or it may simply do nothing. +crashes and data loss; or it may simply do nothing. The V8 options available for a version of Node.js may be determined by running `node --v8-options`. An unofficial, community-maintained list of options @@ -100,3 +121,4 @@ setTimeout(function() { v8.setFlagsFromString('--notrace_gc'); }, 60e3); [V8]: https://developers.google.com/v8/ [here]: https://github.com/thlorenz/v8-flags/blob/master/flags-0.11.md +[`GetHeapSpaceStatistics`]: https://v8docs.nodesource.com/node-5.0/d5/dda/classv8_1_1_isolate.html#ac673576f24fdc7a33378f8f57e1d13a4 |