vm: fix vm.measureMemory() and introduce execution option

https://github.com/nodejs/node-v8/pull/147 broke the
`vm.measureMemory()` API. It only created a `MeasureMemoryDelegate` and
without actually calling `v8::Isolate::MeasureMemory()` so the returned
promise will never resolve. This was not caught by the tests because
the promise resolvers were not wrapped with `common.mustCall()`.

This patch migrates the API properly and also introduce the newly
added execution option to the API. It also removes support for
specifying contexts to measure - instead we'll just return the
measurements for all contexts in the detailed mode, which is
what the `performance.measureMemory()` prototype in V8 currently does.
We can consider implementing our own `v8::MeasureMemoryDelegate`
to select the target context in `ShouldMeasure()` in the future,
but then we'll also need to implement `MeasurementComplete()`
to assemble the result. For now it's probably too early to do that.

Since this API is still experimental (and guarded with a warning),
such breakage should be acceptable.

Refs: https://github.com/nodejs/node-v8/pull/147

PR-URL: https://github.com/nodejs/node/pull/32988
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: Jiawen Geng <technicalcute@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>

1 files changed, 44 insertions, 18 deletions

diff --git a/doc/api/vm.md b/doc/api/vm.md
index 7957c9bb3e5..5bf0c6e62b7 100644
--- a/doc/api/vm.md
+++ b/doc/api/vm.md
@@ -303,15 +303,21 @@ added: v13.10.0
 
 > Stability: 1 - Experimental
 
-Measure the memory known to V8 and used by the current execution context
-or a specified context.
+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'`.
+  * `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'`
-  * `context` {Object} Optional. A [contextified][] object returned
-    by `vm.createContext()`. If not specified, measure the memory
-    usage of the current context where `vm.measureMemory()` is invoked.
+  * `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.
 
@@ -319,28 +325,48 @@ 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()` measures
-the memory reachable by V8 from a specific context, while
-`v8.getHeapSpaceStatistics()` measures the memory used by an instance
-of V8 engine, which can switch among multiple contexts that reference
-objects in the heap of one engine.
+`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 current context and return the result
-// in summary.
+// Measure the memory used by the main context.
 vm.measureMemory({ mode: 'summary' })
-  // Is the same as vm.measureMemory()
+  // This is the same as vm.measureMemory()
   .then((result) => {
     // The current format is:
-    // { total: { jsMemoryEstimate: 2211728, jsMemoryRange: [ 0, 2211728 ] } }
+    // {
+    //   total: {
+    //      jsMemoryEstimate: 2418479, jsMemoryRange: [ 2418479, 2745799 ]
+    //    }
+    // }
     console.log(result);
   });
 
-const context = vm.createContext({});
-vm.measureMemory({ mode: 'detailed' }, context)
+const context = vm.createContext({ a: 1 });
+vm.measureMemory({ mode: 'detailed', execution: 'eager' })
   .then((result) => {
-    // At the moment the detailed format is the same as the summary one.
+    // 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);
   });
 ```