Add Isolate::SetIdle and CpuProfiler bindings (denoland#2001)

Expose v8::Isolate::SetIdle, along with the CpuProfiler static helpers
CollectSample and UseDetailedSourcePositionsForProfiling.

SetIdle lets embedders inform V8 when they are idle so the CPU profiler
attributes idle samples to the (idle) node instead of counting them as
running code. Without it, tools like Chrome DevTools report ~100% CPU for
a program that is merely parked waiting for I/O.

Author: bartlomieju

src/binding.cc

@@ -189,6 +189,10 @@ void v8__Isolate__LowMemoryNotification(v8::Isolate* isolate) {
   isolate->LowMemoryNotification();
 }
 
+void v8__Isolate__SetIdle(v8::Isolate* isolate, bool is_idle) {
+  isolate->SetIdle(is_idle);
+}
+
 void v8__Isolate__GetHeapStatistics(v8::Isolate* isolate,
                                     v8::HeapStatistics* s) {
   isolate->GetHeapStatistics(s);
@@ -3876,6 +3880,20 @@ void v8__HeapProfiler__TakeHeapSnapshot(v8::Isolate* isolate,
   const_cast<v8::HeapSnapshot*>(snapshot)->Delete();
 }
 
+void v8__CpuProfiler__CollectSample(v8::Isolate* isolate,
+                                    const uint64_t* trace_id) {
+  if (trace_id == nullptr) {
+    v8::CpuProfiler::CollectSample(isolate);
+  } else {
+    v8::CpuProfiler::CollectSample(isolate, *trace_id);
+  }
+}
+
+void v8__CpuProfiler__UseDetailedSourcePositionsForProfiling(
+    v8::Isolate* isolate) {
+  v8::CpuProfiler::UseDetailedSourcePositionsForProfiling(isolate);
+}
+
 }  // extern "C"
 
 // v8::ValueSerializer::Delegate

src/isolate.rs

@@ -623,6 +623,14 @@ unsafe extern "C" {
   fn v8__Isolate__MemoryPressureNotification(this: *mut RealIsolate, level: u8);
   fn v8__Isolate__ClearKeptObjects(isolate: *mut RealIsolate);
   fn v8__Isolate__LowMemoryNotification(isolate: *mut RealIsolate);
+  fn v8__Isolate__SetIdle(isolate: *mut RealIsolate, is_idle: bool);
+  fn v8__CpuProfiler__CollectSample(
+    isolate: *mut RealIsolate,
+    trace_id: *const u64,
+  );
+  fn v8__CpuProfiler__UseDetailedSourcePositionsForProfiling(
+    isolate: *mut RealIsolate,
+  );
   fn v8__Isolate__GetHeapStatistics(
     this: *mut RealIsolate,
     s: *mut v8__HeapStatistics,
@@ -1333,6 +1341,49 @@ impl Isolate {
     unsafe { v8__Isolate__LowMemoryNotification(self.as_real_ptr()) }
   }
 
+  /// Tells the VM whether the embedder is currently idle or not.
+  ///
+  /// This is consulted by V8's CPU profiler: samples taken while the embedder
+  /// is idle (for instance, blocked waiting for I/O in the event loop) are
+  /// attributed to the "(idle)" node instead of being counted as running code.
+  /// Embedders that don't call this end up reporting ~100% CPU usage in tools
+  /// like Chrome DevTools even when the program is doing nothing.
+  ///
+  /// Must be called on the isolate's own thread while no JavaScript is
+  /// executing (e.g. right before parking the event loop, and again with
+  /// `false` once it resumes).
+  #[inline(always)]
+  pub fn set_idle(&mut self, is_idle: bool) {
+    unsafe { v8__Isolate__SetIdle(self.as_real_ptr(), is_idle) }
+  }
+
+  /// Synchronously collect a CPU profiling sample in all CPU profilers
+  /// attached to this isolate. This does not affect the number of ticks
+  /// recorded for the current top node.
+  ///
+  /// When `trace_id` is `Some`, the sample is tagged with that identifier,
+  /// which is useful to associate the sample with a trace event.
+  #[inline(always)]
+  pub fn collect_cpu_profiler_sample(&mut self, trace_id: Option<u64>) {
+    let trace_id_ptr = match &trace_id {
+      Some(id) => id as *const u64,
+      None => std::ptr::null(),
+    };
+    unsafe { v8__CpuProfiler__CollectSample(self.as_real_ptr(), trace_id_ptr) }
+  }
+
+  /// Generate more detailed source positions for code objects. This results in
+  /// better accuracy when mapping CPU profiling samples back to script source,
+  /// at the cost of some additional memory and CPU overhead.
+  #[inline(always)]
+  pub fn use_detailed_source_positions_for_profiling(&mut self) {
+    unsafe {
+      v8__CpuProfiler__UseDetailedSourcePositionsForProfiling(
+        self.as_real_ptr(),
+      )
+    }
+  }
+
   /// Get statistics about the heap memory usage.
   #[inline(always)]
   pub fn get_heap_statistics(&mut self) -> HeapStatistics {

tests/test_api.rs

@@ -8097,6 +8097,42 @@ fn low_memory_notification() {
   isolate.low_memory_notification();
 }
 
+#[test]
+fn set_idle() {
+  let _setup_guard = setup::parallel_test();
+
+  let mut isolate = v8::Isolate::new(Default::default());
+  // Toggling the idle state must not affect the ability to run code.
+  isolate.set_idle(true);
+  isolate.set_idle(false);
+
+  v8::scope!(let scope, &mut isolate);
+  let context = v8::Context::new(scope, Default::default());
+  let scope = &mut v8::ContextScope::new(scope, context);
+  let value = eval(scope, "1 + 1").unwrap();
+  assert_eq!(value.uint32_value(scope).unwrap(), 2);
+}
+
+#[test]
+fn cpu_profiler_bindings() {
+  let _setup_guard = setup::parallel_test();
+
+  let mut isolate = v8::Isolate::new(Default::default());
+  isolate.use_detailed_source_positions_for_profiling();
+
+  v8::scope!(let scope, &mut isolate);
+  let context = v8::Context::new(scope, Default::default());
+  let scope = &mut v8::ContextScope::new(scope, context);
+
+  // Collecting a sample without any profiler attached is a no-op but must be
+  // safe to call, both with and without a trace id.
+  scope.collect_cpu_profiler_sample(None);
+  scope.collect_cpu_profiler_sample(Some(42));
+
+  let value = eval(scope, "1 + 1").unwrap();
+  assert_eq!(value.uint32_value(scope).unwrap(), 2);
+}
+
 // Clippy thinks the return value doesn't need to be an Option, it's unaware
 // of the mapping that MapFnFrom<F> does for ResolveModuleCallback.
 #[allow(clippy::unnecessary_wraps)]