PlatformImpl

Author: fraidev

src/binding.cc

@@ -3012,20 +3012,21 @@ v8::StartupData v8__SnapshotCreator__CreateBlob(
   return self->CreateBlob(function_code_handling);
 }
 
-// Rust-side callbacks for the trait-based NotifyingPlatform.
-// `context` is a pointer to a Rust Box<dyn ForegroundTaskCallback>.
-extern "C" {
-void v8__Platform__NotifyingPlatform__onForegroundTaskPosted(
-    void* context, void* isolate, double delay_in_seconds);
-void v8__Platform__NotifyingPlatform__dropContext(void* context);
-}
-
-// TaskRunner wrapper that intercepts all PostTask* calls and notifies
-// the embedder (via a Rust trait) before delegating to the real runner.
-class NotifyingTaskRunner final : public v8::TaskRunner {
+// Rust-side callbacks for trait-based CustomPlatform (PlatformImpl trait).
+// `this` is a pointer to the CustomPlatform instance, used by Rust to
+// recover the Box<dyn PlatformImpl> stored at the same offset.
+void v8__Platform__CustomPlatform__BASE__onForegroundTaskPosted(
+    void* this_, void* isolate, double delay_in_seconds);
+void v8__Platform__CustomPlatform__BASE__onIsolateShutdown(void* this_,
+                                                           void* isolate);
+void v8__Platform__CustomPlatform__BASE__DROP(void* this_);
+
+// TaskRunner wrapper that intercepts all PostTask* calls and dispatches
+// to the Rust PlatformImpl trait via the CustomPlatform context.
+class CustomTaskRunner final : public v8::TaskRunner {
  public:
-  NotifyingTaskRunner(std::shared_ptr<v8::TaskRunner> wrapped, void* context,
-                      v8::Isolate* isolate)
+  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(); }
@@ -3040,20 +3041,20 @@ class NotifyingTaskRunner final : public v8::TaskRunner {
   void PostTaskImpl(std::unique_ptr<v8::Task> task,
                     const v8::SourceLocation& location) override {
     wrapped_->PostTask(std::move(task), location);
-    v8__Platform__NotifyingPlatform__onForegroundTaskPosted(
+    v8__Platform__CustomPlatform__BASE__onForegroundTaskPosted(
         context_, static_cast<void*>(isolate_), 0.0);
   }
   void PostNonNestableTaskImpl(std::unique_ptr<v8::Task> task,
                                const v8::SourceLocation& location) override {
     wrapped_->PostNonNestableTask(std::move(task), location);
-    v8__Platform__NotifyingPlatform__onForegroundTaskPosted(
+    v8__Platform__CustomPlatform__BASE__onForegroundTaskPosted(
         context_, static_cast<void*>(isolate_), 0.0);
   }
   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__NotifyingPlatform__onForegroundTaskPosted(
+    v8__Platform__CustomPlatform__BASE__onForegroundTaskPosted(
         context_, static_cast<void*>(isolate_),
         delay_in_seconds > 0 ? delay_in_seconds : 0.0);
   }
@@ -3062,14 +3063,14 @@ class NotifyingTaskRunner final : public v8::TaskRunner {
       const v8::SourceLocation& location) override {
     wrapped_->PostNonNestableDelayedTask(std::move(task), delay_in_seconds,
                                          location);
-    v8__Platform__NotifyingPlatform__onForegroundTaskPosted(
+    v8__Platform__CustomPlatform__BASE__onForegroundTaskPosted(
         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__NotifyingPlatform__onForegroundTaskPosted(
+    v8__Platform__CustomPlatform__BASE__onForegroundTaskPosted(
         context_, static_cast<void*>(isolate_), 0.0);
   }
 
@@ -3079,19 +3080,19 @@ class NotifyingTaskRunner final : public v8::TaskRunner {
   v8::Isolate* isolate_;
 };
 
-// Platform wrapper that intercepts GetForegroundTaskRunner to return
-// NotifyingTaskRunner instances, dispatching to a Rust trait object.
-class NotifyingPlatform : public v8::platform::DefaultPlatform {
+// Generic Platform subclass that delegates virtual method overrides to a
+// Rust PlatformImpl trait object, following the inspector API pattern.
+class CustomPlatform : public v8::platform::DefaultPlatform {
   using IdleTaskSupport = v8::platform::IdleTaskSupport;
 
  public:
-  NotifyingPlatform(int thread_pool_size, IdleTaskSupport idle_task_support,
-                    void* context)
+  CustomPlatform(int thread_pool_size, IdleTaskSupport idle_task_support,
+                 void* context)
       : DefaultPlatform(thread_pool_size, idle_task_support),
         context_(context) {}
 
-  ~NotifyingPlatform() override {
-    v8__Platform__NotifyingPlatform__dropContext(context_);
+  ~CustomPlatform() override {
+    v8__Platform__CustomPlatform__BASE__DROP(context_);
   }
 
   std::shared_ptr<v8::TaskRunner> GetForegroundTaskRunner(
@@ -3104,10 +3105,10 @@ class NotifyingPlatform : public v8::platform::DefaultPlatform {
       auto runner = it->second.lock();
       if (runner) return runner;
     }
-    auto notifying =
-        std::make_shared<NotifyingTaskRunner>(original, context_, isolate);
-    runners_[key] = notifying;
-    return notifying;
+    auto custom =
+        std::make_shared<CustomTaskRunner>(original, context_, isolate);
+    runners_[key] = custom;
+    return custom;
   }
 
   void NotifyIsolateShutdown(v8::Isolate* isolate) {
@@ -3121,6 +3122,8 @@ class NotifyingPlatform : public v8::platform::DefaultPlatform {
         }
       }
     }
+    v8__Platform__CustomPlatform__BASE__onIsolateShutdown(
+        context_, static_cast<void*>(isolate));
     DefaultPlatform::NotifyIsolateShutdown(isolate);
   }
 
@@ -3132,7 +3135,7 @@ class NotifyingPlatform : public v8::platform::DefaultPlatform {
   void* context_;
   std::mutex mutex_;
   std::map<std::pair<v8::Isolate*, v8::TaskPriority>,
-           std::weak_ptr<NotifyingTaskRunner>>
+           std::weak_ptr<CustomTaskRunner>>
       runners_;
 };
 
@@ -3189,14 +3192,14 @@ v8::Platform* v8__Platform__NewSingleThreadedDefaultPlatform(
       .release();
 }
 
-v8::Platform* v8__Platform__NewNotifyingPlatform(int thread_pool_size,
-                                                 bool idle_task_support,
-                                                 void* context) {
+v8::Platform* v8__Platform__NewCustomPlatform(int thread_pool_size,
+                                              bool idle_task_support,
+                                              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<NotifyingPlatform>(
+  return std::make_unique<CustomPlatform>(
              thread_pool_size,
              idle_task_support ? v8::platform::IdleTaskSupport::kEnabled
                                : v8::platform::IdleTaskSupport::kDisabled,

src/lib.rs

@@ -136,10 +136,10 @@ pub use isolate_create_params::CreateParams;
 pub use microtask::MicrotaskQueue;
 pub use module::*;
 pub use object::*;
-pub use platform::ForegroundTaskCallback;
 pub use platform::Platform;
+pub use platform::PlatformImpl;
+pub use platform::new_custom_platform;
 pub use platform::new_default_platform;
-pub use platform::new_notifying_platform;
 pub use platform::new_single_threaded_default_platform;
 pub use platform::new_unprotected_default_platform;
 pub use primitives::*;

src/platform.rs

@@ -22,7 +22,7 @@ unsafe extern "C" {
   fn v8__Platform__NewSingleThreadedDefaultPlatform(
     idle_task_support: bool,
   ) -> *mut Platform;
-  fn v8__Platform__NewNotifyingPlatform(
+  fn v8__Platform__NewCustomPlatform(
     thread_pool_size: int,
     idle_task_support: bool,
     context: *mut std::ffi::c_void,
@@ -65,15 +65,21 @@ unsafe extern "C" {
 #[derive(Debug)]
 pub struct Platform(Opaque);
 
-/// Trait for receiving notifications when foreground tasks are posted to an
-/// isolate's task runner. Implementations must be thread-safe as callbacks
-/// can fire from any V8 background thread.
+/// Trait for customizing platform behavior, following the same pattern as
+/// [`V8InspectorClientImpl`](crate::inspector::V8InspectorClientImpl).
 ///
-/// This follows the trait-based pattern used by the inspector API
-/// (`V8InspectorClientImpl`, `ChannelImpl`).
-pub trait ForegroundTaskCallback: Send + Sync {
+/// Implement this trait to receive callbacks for platform virtual method
+/// overrides. The C++ `CustomPlatform` base class delegates to these methods.
+/// 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 {
   /// Called when a foreground task has been posted for the given isolate.
   ///
+  /// This corresponds to intercepted calls on the isolate's `TaskRunner`
+  /// (`PostTask`, `PostDelayedTask`, `PostIdleTask`, etc.).
+  ///
   /// `isolate_ptr` is the raw `v8::Isolate*` pointer of the target isolate.
   /// `delay_in_seconds` is 0.0 for immediate tasks, or the delay before the
   /// task should be executed. For delayed tasks, the embedder should schedule
@@ -84,29 +90,44 @@ pub trait ForegroundTaskCallback: Send + Sync {
     &self,
     isolate_ptr: *mut std::ffi::c_void,
     delay_in_seconds: f64,
-  );
+  ) {
+  }
+
+  /// Called when an isolate is about to be shut down.
+  ///
+  /// This corresponds to the `NotifyIsolateShutdown` virtual method.
+  /// The default `DefaultPlatform` cleanup runs after this callback returns.
+  fn on_isolate_shutdown(&self, isolate_ptr: *mut std::ffi::c_void) {}
 }
 
-// FFI callbacks called from C++ NotifyingPlatform/NotifyingTaskRunner.
-// `context` is a raw pointer to a `Box<dyn ForegroundTaskCallback>`.
+// 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__NotifyingPlatform__onForegroundTaskPosted(
+unsafe extern "C" fn v8__Platform__CustomPlatform__BASE__onForegroundTaskPosted(
   context: *mut std::ffi::c_void,
   isolate: *mut std::ffi::c_void,
   delay_in_seconds: f64,
 ) {
-  let callback =
-    unsafe { &*(context as *const Box<dyn ForegroundTaskCallback>) };
-  callback.on_foreground_task_posted(isolate, delay_in_seconds);
+  let imp = unsafe { &*(context as *const Box<dyn PlatformImpl>) };
+  imp.on_foreground_task_posted(isolate, delay_in_seconds);
 }
 
 #[unsafe(no_mangle)]
-unsafe extern "C" fn v8__Platform__NotifyingPlatform__dropContext(
+unsafe extern "C" fn v8__Platform__CustomPlatform__BASE__onIsolateShutdown(
+  context: *mut std::ffi::c_void,
+  isolate: *mut std::ffi::c_void,
+) {
+  let imp = unsafe { &*(context as *const Box<dyn PlatformImpl>) };
+  imp.on_isolate_shutdown(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 ForegroundTaskCallback>);
+    let _ = Box::from_raw(context as *mut Box<dyn PlatformImpl>);
   }
 }
 
@@ -161,26 +182,21 @@ pub fn new_single_threaded_default_platform(
   Platform::new_single_threaded(idle_task_support)
 }
 
-/// Creates a NotifyingPlatform that wraps DefaultPlatform and calls the
-/// provided [`ForegroundTaskCallback`] whenever a foreground task is posted
-/// for any isolate.
-///
-/// This allows embedders to wake their event loop when V8 background threads
-/// complete work and post foreground continuations (e.g. background compilation
-/// finishing, Atomics.waitAsync resolving). For delayed tasks, the embedder
-/// should schedule a wake-up after `delay_in_seconds` (e.g. via a timer).
+/// Creates a custom platform backed by `DefaultPlatform` that delegates
+/// virtual method overrides to the provided [`PlatformImpl`] trait object.
 ///
-/// The callback may be invoked from ANY thread (V8 background threads, etc.)
-/// and must be safe to call concurrently.
+/// This follows the same pattern as
+/// [`V8InspectorClient::new`](crate::inspector::V8InspectorClient::new).
 ///
-/// Thread-isolated allocations are disabled (same as `new_unprotected_default_platform`).
+/// Thread-isolated allocations are disabled (same as
+/// `new_unprotected_default_platform`).
 #[inline(always)]
-pub fn new_notifying_platform(
+pub fn new_custom_platform(
   thread_pool_size: u32,
   idle_task_support: bool,
-  callback: impl ForegroundTaskCallback + 'static,
+  platform_impl: impl PlatformImpl + 'static,
 ) -> UniqueRef<Platform> {
-  Platform::new_notifying(thread_pool_size, idle_task_support, callback)
+  Platform::new_custom(thread_pool_size, idle_task_support, platform_impl)
 }
 
 impl Platform {
@@ -248,24 +264,23 @@ impl Platform {
     }
   }
 
-  /// Creates a NotifyingPlatform (subclass of DefaultPlatform) that dispatches
-  /// to the provided [`ForegroundTaskCallback`] whenever a foreground task is
-  /// posted for an isolate.
+  /// Creates a custom platform backed by `DefaultPlatform` that delegates
+  /// virtual method overrides to the provided [`PlatformImpl`] trait object.
   ///
-  /// The callback trait object is owned by the platform and will be dropped
-  /// when the platform is destroyed.
+  /// The trait object is owned by the platform and will be dropped when the
+  /// platform is destroyed.
   #[inline(always)]
-  pub fn new_notifying(
+  pub fn new_custom(
     thread_pool_size: u32,
     idle_task_support: bool,
-    callback: impl ForegroundTaskCallback + 'static,
+    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 ForegroundTaskCallback> = Box::new(callback);
+    let boxed: Box<dyn PlatformImpl> = Box::new(platform_impl);
     let context = Box::into_raw(Box::new(boxed)) as *mut std::ffi::c_void;
     unsafe {
-      UniqueRef::from_raw(v8__Platform__NewNotifyingPlatform(
+      UniqueRef::from_raw(v8__Platform__NewCustomPlatform(
         thread_pool_size.min(16) as i32,
         idle_task_support,
         context,