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: move vm.measureMemory() to expected location in doc #39211

Merged
merged 1 commit into from
Jul 3, 2021
Merged

doc: move vm.measureMemory() to expected location in doc #39211

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
152 changes: 76 additions & 76 deletions doc/api/vm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -302,82 +302,6 @@ console.log(globalVar);
// 1000
```

## `vm.measureMemory([options])`

<!-- YAML
added: v13.10.0
-->

> Stability: 1 - Experimental

Measure the memory known to V8 and used by all contexts known to the
current V8 isolate, or the main context.

* `options` {Object} Optional.
* `mode` {string} Either `'summary'` or `'detailed'`. In summary mode,
only the memory measured for the main context will be returned. In
detailed mode, the measure measured for all contexts known to the
current V8 isolate will be returned.
**Default:** `'summary'`
* `execution` {string} Either `'default'` or `'eager'`. With default
execution, the promise will not resolve until after the next scheduled
garbage collection starts, which may take a while (or never if the program
exits before the next GC). With eager execution, the GC will be started
right away to measure the memory.
**Default:** `'default'`
* Returns: {Promise} If the memory is successfully measured the promise will
resolve with an object containing information about the memory usage.

The format of the object that the returned Promise may resolve with is
specific to the V8 engine and may change from one version of V8 to the next.

The returned result is different from the statistics returned by
`v8.getHeapSpaceStatistics()` in that `vm.measureMemory()` measure the
memory reachable by each V8 specific contexts in the current instance of
the V8 engine, while the result of `v8.getHeapSpaceStatistics()` measure
the memory occupied by each heap space in the current V8 instance.

```js
const vm = require('vm');
// Measure the memory used by the main context.
vm.measureMemory({ mode: 'summary' })
// This is the same as vm.measureMemory()
.then((result) => {
// The current format is:
// {
// total: {
// jsMemoryEstimate: 2418479, jsMemoryRange: [ 2418479, 2745799 ]
// }
// }
console.log(result);
});

const context = vm.createContext({ a: 1 });
vm.measureMemory({ mode: 'detailed', execution: 'eager' })
.then((result) => {
// Reference the context here so that it won't be GC'ed
// until the measurement is complete.
console.log(context.a);
// {
// total: {
// jsMemoryEstimate: 2574732,
// jsMemoryRange: [ 2574732, 2904372 ]
// },
// current: {
// jsMemoryEstimate: 2438996,
// jsMemoryRange: [ 2438996, 2768636 ]
// },
// other: [
// {
// jsMemoryEstimate: 135736,
// jsMemoryRange: [ 135736, 465376 ]
// }
// ]
// }
console.log(result);
});
```

## Class: `vm.Module`
<!-- YAML
added:
Expand Down Expand Up @@ -1064,6 +988,82 @@ added: v0.11.7
Returns `true` if the given `object` object has been [contextified][] using
[`vm.createContext()`][].

## `vm.measureMemory([options])`

<!-- YAML
added: v13.10.0
-->

> Stability: 1 - Experimental

Measure the memory known to V8 and used by all contexts known to the
current V8 isolate, or the main context.

* `options` {Object} Optional.
* `mode` {string} Either `'summary'` or `'detailed'`. In summary mode,
only the memory measured for the main context will be returned. In
detailed mode, the measure measured for all contexts known to the
current V8 isolate will be returned.
**Default:** `'summary'`
* `execution` {string} Either `'default'` or `'eager'`. With default
execution, the promise will not resolve until after the next scheduled
garbage collection starts, which may take a while (or never if the program
exits before the next GC). With eager execution, the GC will be started
right away to measure the memory.
**Default:** `'default'`
* Returns: {Promise} If the memory is successfully measured the promise will
resolve with an object containing information about the memory usage.

The format of the object that the returned Promise may resolve with is
specific to the V8 engine and may change from one version of V8 to the next.

The returned result is different from the statistics returned by
`v8.getHeapSpaceStatistics()` in that `vm.measureMemory()` measure the
memory reachable by each V8 specific contexts in the current instance of
the V8 engine, while the result of `v8.getHeapSpaceStatistics()` measure
the memory occupied by each heap space in the current V8 instance.

```js
const vm = require('vm');
// Measure the memory used by the main context.
vm.measureMemory({ mode: 'summary' })
// This is the same as vm.measureMemory()
.then((result) => {
// The current format is:
// {
// total: {
// jsMemoryEstimate: 2418479, jsMemoryRange: [ 2418479, 2745799 ]
// }
// }
console.log(result);
});

const context = vm.createContext({ a: 1 });
vm.measureMemory({ mode: 'detailed', execution: 'eager' })
.then((result) => {
// Reference the context here so that it won't be GC'ed
// until the measurement is complete.
console.log(context.a);
// {
// total: {
// jsMemoryEstimate: 2574732,
// jsMemoryRange: [ 2574732, 2904372 ]
// },
// current: {
// jsMemoryEstimate: 2438996,
// jsMemoryRange: [ 2438996, 2768636 ]
// },
// other: [
// {
// jsMemoryEstimate: 135736,
// jsMemoryRange: [ 135736, 465376 ]
// }
// ]
// }
console.log(result);
});
```

## `vm.runInContext(code, contextifiedObject[, options])`
<!-- YAML
added: v0.3.1
Expand Down