Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: general improvements to v8.md copy #6829

Closed
wants to merge 3 commits into from
Closed

doc: general improvements to v8.md copy #6829

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cb4e88b
doc: general improvements to v8.md copy
jasnell May 18, 2016
b5115c6
Address nits
jasnell May 18, 2016
27ca0c6
Address nits
jasnell May 18, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 33 additions & 11 deletions doc/api/v8.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This isn't, and shouldn't be true...

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The current documentation says:

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Given that this edit is a restatement of the existing notice, if we want to change this and declare that the v8 module is covered by the stability index, then we can do that in a separate PR.


## 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
{
Expand All @@ -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:

```
[
Expand Down Expand Up @@ -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
Expand All @@ -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