feat: add PlatformImpl trait for custom platform callbacks (#1924)

fraidev · bartlomieju · web-flow · commit 778b15948d3e · 2026-03-09T15:37:23.000-03:00
Add a trait-based API (following the V8InspectorClientImpl pattern) that lets embedders hook into platform virtual methods. A CustomPlatform C++ class subclasses DefaultPlatform and delegates on_foreground_task_posted and on_isolate_shutdown to a Rust PlatformImpl trait object.

This allows embedders like Deno to receive notifications when V8 background threads post foreground tasks, enabling event-driven wakeups instead of polling.

---------

Co-authored-by: Bartek Iwańczuk &lt;biwanczuk@gmail.com&gt;
diff --git a/src/binding.cc b/src/binding.cc
@@ -4,6 +4,8 @@
 #include <cstddef>
 #include <cstdint>
 #include <cstdio>
+#include <map>
+#include <mutex>
 #include <thread>
 
 #include "cppgc/allocation.h"
@@ -3010,6 +3012,144 @@ v8::StartupData v8__SnapshotCreator__CreateBlob(
   return self->CreateBlob(function_code_handling);
 }
 
+// Rust-side callbacks for trait-based CustomPlatform (PlatformImpl trait).
+// Each callback corresponds to a C++ virtual method on TaskRunner or Platform.
+// `context` is a pointer to the Rust Box<dyn PlatformImpl>.
+extern "C" {
+void v8__Platform__CustomPlatform__BASE__PostTask(void* context, void* isolate);
+void v8__Platform__CustomPlatform__BASE__PostNonNestableTask(void* context,
+                                                             void* isolate);
+void v8__Platform__CustomPlatform__BASE__PostDelayedTask(
+    void* context, void* isolate, double delay_in_seconds);
+void v8__Platform__CustomPlatform__BASE__PostNonNestableDelayedTask(
+    void* context, void* isolate, double delay_in_seconds);
+void v8__Platform__CustomPlatform__BASE__PostIdleTask(void* context,
+                                                      void* isolate);
+void v8__Platform__CustomPlatform__BASE__DROP(void* context);
+}
+
+// TaskRunner wrapper that intercepts all PostTask* virtual methods, forwards
+// tasks to the default platform's queue, and notifies Rust via the
+// corresponding PlatformImpl trait method.
+class CustomTaskRunner final : public v8::TaskRunner {
+ public:
+  CustomTaskRunner(std::shared_ptr<v8::TaskRunner> wrapped, void* context,
+                   v8::Isolate* isolate)
+      : wrapped_(std::move(wrapped)), context_(context), isolate_(isolate) {}
+
+  bool IdleTasksEnabled() override { return wrapped_->IdleTasksEnabled(); }
+  bool NonNestableTasksEnabled() const override {
+    return wrapped_->NonNestableTasksEnabled();
+  }
+  bool NonNestableDelayedTasksEnabled() const override {
+    return wrapped_->NonNestableDelayedTasksEnabled();
+  }
+
+ protected:
+  void PostTaskImpl(std::unique_ptr<v8::Task> task,
+                    const v8::SourceLocation& location) override {
+    wrapped_->PostTask(std::move(task), location);
+    v8__Platform__CustomPlatform__BASE__PostTask(context_,
+                                                 static_cast<void*>(isolate_));
+  }
+  void PostNonNestableTaskImpl(std::unique_ptr<v8::Task> task,
+                               const v8::SourceLocation& location) override {
+    wrapped_->PostNonNestableTask(std::move(task), location);
+    v8__Platform__CustomPlatform__BASE__PostNonNestableTask(
+        context_, static_cast<void*>(isolate_));
+  }
+  void PostDelayedTaskImpl(std::unique_ptr<v8::Task> task,
+                           double delay_in_seconds,
+                           const v8::SourceLocation& location) override {
+    wrapped_->PostDelayedTask(std::move(task), delay_in_seconds, location);
+    v8__Platform__CustomPlatform__BASE__PostDelayedTask(
+        context_, static_cast<void*>(isolate_),
+        delay_in_seconds > 0 ? delay_in_seconds : 0.0);
+  }
+  void PostNonNestableDelayedTaskImpl(
+      std::unique_ptr<v8::Task> task, double delay_in_seconds,
+      const v8::SourceLocation& location) override {
+    wrapped_->PostNonNestableDelayedTask(std::move(task), delay_in_seconds,
+                                         location);
+    v8__Platform__CustomPlatform__BASE__PostNonNestableDelayedTask(
+        context_, static_cast<void*>(isolate_),
+        delay_in_seconds > 0 ? delay_in_seconds : 0.0);
+  }
+  void PostIdleTaskImpl(std::unique_ptr<v8::IdleTask> task,
+                        const v8::SourceLocation& location) override {
+    wrapped_->PostIdleTask(std::move(task), location);
+    v8__Platform__CustomPlatform__BASE__PostIdleTask(
+        context_, static_cast<void*>(isolate_));
+  }
+
+ private:
+  std::shared_ptr<v8::TaskRunner> wrapped_;
+  void* context_;
+  v8::Isolate* isolate_;
+};
+
+// Platform subclass that wraps each isolate's TaskRunner to notify Rust
+// when foreground tasks are posted. Follows the inspector API pattern.
+//
+// NotifyIsolateShutdown is NOT intercepted here because it is not virtual
+// on DefaultPlatform — V8's free function does static_cast<DefaultPlatform*>
+// and calls it directly, bypassing any override. Isolate cleanup must be
+// handled on the Rust side (e.g. in the isolate's Drop impl).
+class CustomPlatform : public v8::platform::DefaultPlatform {
+  using IdleTaskSupport = v8::platform::IdleTaskSupport;
+
+ public:
+  CustomPlatform(int thread_pool_size, IdleTaskSupport idle_task_support,
+                 bool unprotected, void* context)
+      : DefaultPlatform(thread_pool_size, idle_task_support),
+        unprotected_(unprotected),
+        context_(context) {}
+
+  // SAFETY: The platform is single-owner (via unique_ptr). The destructor
+  // runs after all isolates have been disposed and no more task runner
+  // callbacks can fire, so DROP does not race with other callbacks.
+  ~CustomPlatform() override {
+    v8__Platform__CustomPlatform__BASE__DROP(context_);
+  }
+
+  std::shared_ptr<v8::TaskRunner> GetForegroundTaskRunner(
+      v8::Isolate* isolate, v8::TaskPriority priority) override {
+    auto original = DefaultPlatform::GetForegroundTaskRunner(isolate, priority);
+    std::lock_guard<std::mutex> lock(mutex_);
+    auto key = std::make_pair(isolate, priority);
+    auto it = runners_.find(key);
+    if (it != runners_.end()) {
+      auto runner = it->second.lock();
+      if (runner) return runner;
+    }
+    auto custom =
+        std::make_shared<CustomTaskRunner>(original, context_, isolate);
+    runners_[key] = custom;
+    return custom;
+  }
+
+  // When unprotected, disable thread-isolated allocations (same as
+  // UnprotectedDefaultPlatform). Required when isolates may be created on
+  // threads other than the one that called v8::V8::Initialize (e.g. worker
+  // threads in Deno).
+  v8::ThreadIsolatedAllocator* GetThreadIsolatedAllocator() override {
+    if (unprotected_) return nullptr;
+    return DefaultPlatform::GetThreadIsolatedAllocator();
+  }
+
+ private:
+  bool unprotected_;
+  void* context_;
+  std::mutex mutex_;
+  // weak_ptr so runners are kept alive only while V8 holds a reference.
+  // When V8 drops its shared_ptr (e.g. on isolate shutdown), the weak_ptr
+  // expires and a fresh wrapper is created if GetForegroundTaskRunner is
+  // called again. This avoids preventing cleanup of the underlying runner.
+  std::map<std::pair<v8::Isolate*, v8::TaskPriority>,
+           std::weak_ptr<CustomTaskRunner>>
+      runners_;
+};
+
 class UnprotectedDefaultPlatform : public v8::platform::DefaultPlatform {
   using IdleTaskSupport = v8::platform::IdleTaskSupport;
   using InProcessStackDumping = v8::platform::InProcessStackDumping;
@@ -3063,6 +3203,21 @@ v8::Platform* v8__Platform__NewSingleThreadedDefaultPlatform(
       .release();
 }
 
+v8::Platform* v8__Platform__NewCustomPlatform(int thread_pool_size,
+                                              bool idle_task_support,
+                                              bool unprotected, void* context) {
+  if (thread_pool_size < 1) {
+    thread_pool_size = std::thread::hardware_concurrency();
+  }
+  thread_pool_size = std::max(std::min(thread_pool_size, 16), 1);
+  return std::make_unique<CustomPlatform>(
+             thread_pool_size,
+             idle_task_support ? v8::platform::IdleTaskSupport::kEnabled
+                               : v8::platform::IdleTaskSupport::kDisabled,
+             unprotected, context)
+      .release();
+}
+
 bool v8__Platform__PumpMessageLoop(v8::Platform* platform, v8::Isolate* isolate,
                                    bool wait_for_work) {
   return v8::platform::PumpMessageLoop(
diff --git a/src/lib.rs b/src/lib.rs
@@ -137,6 +137,8 @@ pub use microtask::MicrotaskQueue;
 pub use module::*;
 pub use object::*;
 pub use platform::Platform;
+pub use platform::PlatformImpl;
+pub use platform::new_custom_platform;
 pub use platform::new_default_platform;
 pub use platform::new_single_threaded_default_platform;
 pub use platform::new_unprotected_default_platform;
diff --git a/src/platform.rs b/src/platform.rs
@@ -22,6 +22,12 @@ unsafe extern "C" {
   fn v8__Platform__NewSingleThreadedDefaultPlatform(
     idle_task_support: bool,
   ) -> *mut Platform;
+  fn v8__Platform__NewCustomPlatform(
+    thread_pool_size: int,
+    idle_task_support: bool,
+    unprotected: bool,
+    context: *mut std::ffi::c_void,
+  ) -> *mut Platform;
   fn v8__Platform__DELETE(this: *mut Platform);
 
   fn v8__Platform__PumpMessageLoop(
@@ -60,6 +66,129 @@ unsafe extern "C" {
 #[derive(Debug)]
 pub struct Platform(Opaque);
 
+/// Trait for customizing platform behavior, following the same pattern as
+/// [`V8InspectorClientImpl`](crate::inspector::V8InspectorClientImpl).
+///
+/// Implement this trait to receive callbacks for overridden C++ virtual
+/// methods on the `DefaultPlatform` and its per-isolate `TaskRunner`.
+///
+/// The C++ `CustomPlatform` wraps each isolate's `TaskRunner` so that
+/// every `PostTask` / `PostDelayedTask` / etc. call is forwarded to the
+/// default implementation *and* notifies Rust through the corresponding
+/// trait method.
+///
+/// All methods have default no-op implementations; override only what
+/// you need.
+///
+/// Implementations must be `Send + Sync` as callbacks may fire from any
+/// thread.
+#[allow(unused_variables)]
+pub trait PlatformImpl: Send + Sync {
+  // ---- TaskRunner virtual methods ----
+
+  /// Called when `TaskRunner::PostTask` is invoked for the given isolate.
+  ///
+  /// The task itself has already been forwarded to the default platform's
+  /// queue and will be executed by `PumpMessageLoop`. This callback is a
+  /// notification that a new task is available.
+  ///
+  /// May be called from ANY thread (V8 background threads, etc.).
+  fn post_task(&self, isolate_ptr: *mut std::ffi::c_void) {}
+
+  /// Called when `TaskRunner::PostNonNestableTask` is invoked.
+  ///
+  /// Same semantics as [`post_task`](Self::post_task).
+  fn post_non_nestable_task(&self, isolate_ptr: *mut std::ffi::c_void) {}
+
+  /// Called when `TaskRunner::PostDelayedTask` is invoked.
+  ///
+  /// The task has been forwarded to the default runner's delayed queue.
+  /// `delay_in_seconds` is the delay before the task should execute.
+  /// Embedders should schedule a wake-up after this delay.
+  ///
+  /// May be called from ANY thread.
+  fn post_delayed_task(
+    &self,
+    isolate_ptr: *mut std::ffi::c_void,
+    delay_in_seconds: f64,
+  ) {
+  }
+
+  /// Called when `TaskRunner::PostNonNestableDelayedTask` is invoked.
+  ///
+  /// Same semantics as [`post_delayed_task`](Self::post_delayed_task).
+  fn post_non_nestable_delayed_task(
+    &self,
+    isolate_ptr: *mut std::ffi::c_void,
+    delay_in_seconds: f64,
+  ) {
+  }
+
+  /// Called when `TaskRunner::PostIdleTask` is invoked.
+  ///
+  /// Same semantics as [`post_task`](Self::post_task).
+  fn post_idle_task(&self, isolate_ptr: *mut std::ffi::c_void) {}
+}
+
+// FFI callbacks called from C++ CustomPlatform/CustomTaskRunner.
+// `context` is a raw pointer to a `Box<dyn PlatformImpl>`.
+
+#[unsafe(no_mangle)]
+unsafe extern "C" fn v8__Platform__CustomPlatform__BASE__PostTask(
+  context: *mut std::ffi::c_void,
+  isolate: *mut std::ffi::c_void,
+) {
+  let imp = unsafe { &*(context as *const Box<dyn PlatformImpl>) };
+  imp.post_task(isolate);
+}
+
+#[unsafe(no_mangle)]
+unsafe extern "C" fn v8__Platform__CustomPlatform__BASE__PostNonNestableTask(
+  context: *mut std::ffi::c_void,
+  isolate: *mut std::ffi::c_void,
+) {
+  let imp = unsafe { &*(context as *const Box<dyn PlatformImpl>) };
+  imp.post_non_nestable_task(isolate);
+}
+
+#[unsafe(no_mangle)]
+unsafe extern "C" fn v8__Platform__CustomPlatform__BASE__PostDelayedTask(
+  context: *mut std::ffi::c_void,
+  isolate: *mut std::ffi::c_void,
+  delay_in_seconds: f64,
+) {
+  let imp = unsafe { &*(context as *const Box<dyn PlatformImpl>) };
+  imp.post_delayed_task(isolate, delay_in_seconds);
+}
+
+#[unsafe(no_mangle)]
+unsafe extern "C" fn v8__Platform__CustomPlatform__BASE__PostNonNestableDelayedTask(
+  context: *mut std::ffi::c_void,
+  isolate: *mut std::ffi::c_void,
+  delay_in_seconds: f64,
+) {
+  let imp = unsafe { &*(context as *const Box<dyn PlatformImpl>) };
+  imp.post_non_nestable_delayed_task(isolate, delay_in_seconds);
+}
+
+#[unsafe(no_mangle)]
+unsafe extern "C" fn v8__Platform__CustomPlatform__BASE__PostIdleTask(
+  context: *mut std::ffi::c_void,
+  isolate: *mut std::ffi::c_void,
+) {
+  let imp = unsafe { &*(context as *const Box<dyn PlatformImpl>) };
+  imp.post_idle_task(isolate);
+}
+
+#[unsafe(no_mangle)]
+unsafe extern "C" fn v8__Platform__CustomPlatform__BASE__DROP(
+  context: *mut std::ffi::c_void,
+) {
+  unsafe {
+    let _ = Box::from_raw(context as *mut Box<dyn PlatformImpl>);
+  }
+}
+
 /// Returns a new instance of the default v8::Platform implementation.
 ///
 /// |thread_pool_size| is the number of worker threads to allocate for
@@ -111,6 +240,31 @@ pub fn new_single_threaded_default_platform(
   Platform::new_single_threaded(idle_task_support)
 }
 
+/// Creates a custom platform backed by `DefaultPlatform` that delegates
+/// virtual method overrides to the provided [`PlatformImpl`] trait object.
+///
+/// This follows the same pattern as
+/// [`V8InspectorClient::new`](crate::inspector::V8InspectorClient::new).
+///
+/// When `unprotected` is true, thread-isolated allocations are disabled
+/// (same as `new_unprotected_default_platform`). This is required when
+/// isolates may be created on threads other than the one that called
+/// `V8::initialize`.
+#[inline(always)]
+pub fn new_custom_platform(
+  thread_pool_size: u32,
+  idle_task_support: bool,
+  unprotected: bool,
+  platform_impl: impl PlatformImpl + 'static,
+) -> UniqueRef<Platform> {
+  Platform::new_custom(
+    thread_pool_size,
+    idle_task_support,
+    unprotected,
+    platform_impl,
+  )
+}
+
 impl Platform {
   /// Returns a new instance of the default v8::Platform implementation.
   ///
@@ -175,6 +329,34 @@ impl Platform {
       ))
     }
   }
+
+  /// Creates a custom platform backed by `DefaultPlatform` that delegates
+  /// virtual method overrides to the provided [`PlatformImpl`] trait object.
+  ///
+  /// The trait object is owned by the platform and will be dropped when the
+  /// platform is destroyed.
+  #[inline(always)]
+  pub fn new_custom(
+    thread_pool_size: u32,
+    idle_task_support: bool,
+    unprotected: bool,
+    platform_impl: impl PlatformImpl + 'static,
+  ) -> UniqueRef<Self> {
+    // Double-box: inner Box<dyn> is a fat pointer, outer Box gives us a
+    // thin pointer we can pass through C++ void*.
+    let boxed: Box<dyn PlatformImpl> = Box::new(platform_impl);
+    let context = Box::into_raw(Box::new(boxed)) as *mut std::ffi::c_void;
+    // thread_pool_size clamping (0 → hardware_concurrency, max 16) is
+    // handled on the C++ side in v8__Platform__NewCustomPlatform.
+    unsafe {
+      UniqueRef::from_raw(v8__Platform__NewCustomPlatform(
+        thread_pool_size as i32,
+        idle_task_support,
+        unprotected,
+        context,
+      ))
+    }
+  }
 }
 
 impl Platform {
diff --git a/tests/test_custom_platform.rs b/tests/test_custom_platform.rs
