Add v8::Locker and v8::UnenteredIsolate

Author: max-lt

src/binding.cc

@@ -170,6 +170,16 @@ void v8__Isolate__Enter(v8::Isolate* isolate) { isolate->Enter(); }
 
 void v8__Isolate__Exit(v8::Isolate* isolate) { isolate->Exit(); }
 
+void v8__Locker__CONSTRUCT(uninit_t<v8::Locker>* buf, v8::Isolate* isolate) {
+  construct_in_place<v8::Locker>(buf, isolate);
+}
+
+void v8__Locker__DESTRUCT(v8::Locker* self) { self->~Locker(); }
+
+bool v8__Locker__IsLocked(v8::Isolate* isolate) {
+  return v8::Locker::IsLocked(isolate);
+}
+
 v8::Isolate* v8__Isolate__GetCurrent() { return v8::Isolate::GetCurrent(); }
 
 const v8::Data* v8__Isolate__GetCurrentHostDefinedOptions(

src/isolate.rs

@@ -914,6 +914,14 @@ impl Isolate {
     OwnedIsolate::new(Self::new_impl(params))
   }
 
+  /// Creates an isolate for use with `v8::Locker` in multi-threaded scenarios.
+  ///
+  /// Unlike `Isolate::new()`, this does not automatically enter the isolate.
+  #[allow(clippy::new_ret_no_self)]
+  pub fn new_unentered(params: CreateParams) -> UnenteredIsolate {
+    UnenteredIsolate::new(Self::new_impl(params))
+  }
+
   #[allow(clippy::new_ret_no_self)]
   pub fn snapshot_creator(
     external_references: Option<Cow<'static, [ExternalReference]>>,
@@ -2118,6 +2126,40 @@ impl AsMut<Isolate> for Isolate {
   }
 }
 
+/// An isolate that must be accessed via `Locker`. Does not auto-enter.
+#[derive(Debug)]
+pub struct UnenteredIsolate {
+  cxx_isolate: NonNull<RealIsolate>,
+}
+
+impl UnenteredIsolate {
+  pub(crate) fn new(cxx_isolate: *mut RealIsolate) -> Self {
+    Self {
+      cxx_isolate: NonNull::new(cxx_isolate).unwrap(),
+    }
+  }
+}
+
+impl Drop for UnenteredIsolate {
+  fn drop(&mut self) {
+    unsafe {
+      let isolate = Isolate::from_raw_ref_mut(&mut self.cxx_isolate);
+      let snapshot_creator =
+        isolate.get_annex_mut().maybe_snapshot_creator.take();
+      assert!(
+        snapshot_creator.is_none(),
+        "v8::UnenteredIsolate::create_blob must be called before dropping"
+      );
+      isolate.dispose_annex();
+      Platform::notify_isolate_shutdown(&get_current_platform(), isolate);
+      isolate.dispose();
+    }
+  }
+}
+
+// Thread safety ensured by Locker.
+unsafe impl Send for UnenteredIsolate {}
+
 /// Collection of V8 heap information.
 ///
 /// Instances of this class can be passed to v8::Isolate::GetHeapStatistics to
@@ -2417,3 +2459,50 @@ impl AsRef<Isolate> for Isolate {
     self
   }
 }
+
+/// Locks an isolate and enters it for the current thread.
+pub struct Locker<'a> {
+  raw: std::mem::ManuallyDrop<crate::scope::raw::Locker>,
+  isolate: &'a mut UnenteredIsolate,
+}
+
+impl<'a> Locker<'a> {
+  pub fn new(isolate: &'a mut UnenteredIsolate) -> Self {
+    let isolate_ptr = isolate.cxx_isolate;
+    unsafe {
+      v8__Isolate__Enter(isolate_ptr.as_ptr());
+    }
+    let mut raw = unsafe { crate::scope::raw::Locker::uninit() };
+    unsafe { raw.init(isolate_ptr) };
+    Self {
+      raw: std::mem::ManuallyDrop::new(raw),
+      isolate,
+    }
+  }
+
+  pub fn is_locked(isolate: &UnenteredIsolate) -> bool {
+    crate::scope::raw::Locker::is_locked(isolate.cxx_isolate)
+  }
+}
+
+impl Drop for Locker<'_> {
+  fn drop(&mut self) {
+    unsafe {
+      std::mem::ManuallyDrop::drop(&mut self.raw);
+      v8__Isolate__Exit(self.isolate.cxx_isolate.as_ptr());
+    }
+  }
+}
+
+impl Deref for Locker<'_> {
+  type Target = Isolate;
+  fn deref(&self) -> &Self::Target {
+    unsafe { Isolate::from_raw_ref(&self.isolate.cxx_isolate) }
+  }
+}
+
+impl DerefMut for Locker<'_> {
+  fn deref_mut(&mut self) -> &mut Self::Target {
+    unsafe { Isolate::from_raw_ref_mut(&mut self.isolate.cxx_isolate) }
+  }
+}

src/lib.rs

@@ -114,6 +114,7 @@ pub use isolate::HostImportModuleWithPhaseDynamicallyCallback;
 pub use isolate::HostInitializeImportMetaObjectCallback;
 pub use isolate::Isolate;
 pub use isolate::IsolateHandle;
+pub use isolate::Locker;
 pub use isolate::MemoryPressureLevel;
 pub use isolate::MessageCallback;
 pub use isolate::MessageErrorLevel;
@@ -128,6 +129,7 @@ pub use isolate::PromiseHookType;
 pub use isolate::PromiseRejectCallback;
 pub use isolate::RealIsolate;
 pub use isolate::TimeZoneDetection;
+pub use isolate::UnenteredIsolate;
 pub use isolate::UseCounterCallback;
 pub use isolate::UseCounterFeature;
 pub use isolate::WasmAsyncSuccess;

src/scope.rs

@@ -127,9 +127,9 @@
 //! So in `ContextScope<'b, 's>`, `'b` is the lifetime of the borrow of the inner scope, and `'s` is the lifetime of the inner scope (and therefore the handles).
 use crate::{
   Context, Data, DataError, Function, FunctionCallbackInfo, Isolate, Local,
-  Message, Object, OwnedIsolate, PromiseRejectMessage, PropertyCallbackInfo,
-  SealedLocal, Value, fast_api::FastApiCallbackOptions, isolate::RealIsolate,
-  support::assert_layout_subset,
+  Locker, Message, Object, OwnedIsolate, PromiseRejectMessage,
+  PropertyCallbackInfo, SealedLocal, Value, fast_api::FastApiCallbackOptions,
+  isolate::RealIsolate, support::assert_layout_subset,
 };
 use std::{
   any::type_name,
@@ -279,7 +279,7 @@ mod get_isolate {
 pub(crate) use get_isolate::GetIsolate;
 
 mod get_isolate_impls {
-  use crate::{Promise, PromiseRejectMessage};
+  use crate::{Locker, Promise, PromiseRejectMessage};
 
   use super::*;
   impl GetIsolate for Isolate {
@@ -294,6 +294,14 @@ mod get_isolate_impls {
     }
   }
 
+  impl GetIsolate for Locker<'_> {
+    fn get_isolate_ptr(&self) -> *mut RealIsolate {
+      // Locker derefs to Isolate, which has as_real_ptr()
+      use std::ops::Deref;
+      self.deref().as_real_ptr()
+    }
+  }
+
   impl GetIsolate for FunctionCallbackInfo {
     fn get_isolate_ptr(&self) -> *mut RealIsolate {
       self.get_isolate_ptr()
@@ -442,6 +450,20 @@ impl<'s> NewHandleScope<'s> for OwnedIsolate {
   }
 }
 
+impl<'s, 'a: 's> NewHandleScope<'s> for Locker<'a> {
+  type NewScope = HandleScope<'s, ()>;
+
+  fn make_new_scope(me: &'s mut Self) -> Self::NewScope {
+    HandleScope {
+      raw_handle_scope: unsafe { raw::HandleScope::uninit() },
+      isolate: unsafe { NonNull::new_unchecked(me.get_isolate_ptr()) },
+      context: Cell::new(None),
+      _phantom: PhantomData,
+      _pinned: PhantomPinned,
+    }
+  }
+}
+
 impl<'s, 'p: 's, 'i, C> NewHandleScope<'s>
   for PinnedRef<'p, CallbackScope<'i, C>>
 {

src/scope/raw.rs

@@ -219,6 +219,34 @@ impl Drop for AllowJavascriptExecutionScope {
   }
 }
 
+#[repr(C)]
+#[derive(Debug)]
+pub(crate) struct Locker([MaybeUninit<usize>; 3]);
+
+impl Locker {
+  #[inline]
+  pub unsafe fn uninit() -> Self {
+    Self(unsafe { MaybeUninit::uninit().assume_init() })
+  }
+
+  #[inline]
+  pub unsafe fn init(&mut self, isolate: NonNull<RealIsolate>) {
+    let buf = NonNull::from(self).cast();
+    unsafe { v8__Locker__CONSTRUCT(buf.as_ptr(), isolate.as_ptr()) };
+  }
+
+  pub fn is_locked(isolate: NonNull<RealIsolate>) -> bool {
+    unsafe { v8__Locker__IsLocked(isolate.as_ptr()) }
+  }
+}
+
+impl Drop for Locker {
+  #[inline(always)]
+  fn drop(&mut self) {
+    unsafe { v8__Locker__DESTRUCT(self) };
+  }
+}
+
 unsafe extern "C" {
   pub(super) fn v8__Isolate__GetCurrent() -> *mut RealIsolate;
   pub(super) fn v8__Isolate__GetCurrentContext(
@@ -311,4 +339,11 @@ unsafe extern "C" {
   pub(super) fn v8__AllowJavascriptExecutionScope__DESTRUCT(
     this: *mut AllowJavascriptExecutionScope,
   );
+
+  pub(super) fn v8__Locker__CONSTRUCT(
+    buf: *mut MaybeUninit<Locker>,
+    isolate: *mut RealIsolate,
+  );
+  pub(super) fn v8__Locker__DESTRUCT(this: *mut Locker);
+  pub(super) fn v8__Locker__IsLocked(isolate: *mut RealIsolate) -> bool;
 }

tests/test_locker.rs

@@ -0,0 +1,101 @@
+use std::pin::pin;
+
+#[test]
+fn locker_basic() {
+  let _setup_guard = setup();
+  let mut isolate = v8::Isolate::new_unentered(Default::default());
+  {
+    let mut locker = v8::Locker::new(&mut isolate);
+    let scope = pin!(v8::HandleScope::new(&mut *locker));
+    let scope = &mut scope.init();
+    let _context = v8::Context::new(scope, Default::default());
+  }
+}
+
+#[test]
+fn locker_with_script() {
+  let _setup_guard = setup();
+  let mut isolate = v8::Isolate::new_unentered(Default::default());
+  {
+    let mut locker = v8::Locker::new(&mut isolate);
+    let scope = pin!(v8::HandleScope::new(&mut *locker));
+    let scope = &mut scope.init();
+    let context = v8::Context::new(scope, Default::default());
+    let scope = &mut v8::ContextScope::new(scope, context);
+
+    let code = v8::String::new(scope, "40 + 2").unwrap();
+    let script = v8::Script::compile(scope, code, None).unwrap();
+    let result = script.run(scope).unwrap();
+    assert_eq!(result.to_integer(scope).unwrap().value(), 42);
+  }
+}
+
+#[test]
+fn unentered_isolate_no_lifo_constraint() {
+  let _setup_guard = setup();
+  let isolate1 = v8::Isolate::new_unentered(Default::default());
+  let isolate2 = v8::Isolate::new_unentered(Default::default());
+  let isolate3 = v8::Isolate::new_unentered(Default::default());
+  drop(isolate2);
+  drop(isolate1);
+  drop(isolate3);
+}
+
+#[test]
+fn locker_multiple_lock_unlock() {
+  let _setup_guard = setup();
+  let mut isolate = v8::Isolate::new_unentered(Default::default());
+
+  {
+    let mut locker = v8::Locker::new(&mut isolate);
+    let scope = pin!(v8::HandleScope::new(&mut *locker));
+    let scope = &mut scope.init();
+    let context = v8::Context::new(scope, Default::default());
+    let scope = &mut v8::ContextScope::new(scope, context);
+
+    let code = v8::String::new(scope, "1 + 1").unwrap();
+    let script = v8::Script::compile(scope, code, None).unwrap();
+    let result = script.run(scope).unwrap();
+    assert_eq!(result.to_integer(scope).unwrap().value(), 2);
+  }
+
+  {
+    let mut locker = v8::Locker::new(&mut isolate);
+    let scope = pin!(v8::HandleScope::new(&mut *locker));
+    let scope = &mut scope.init();
+    let context = v8::Context::new(scope, Default::default());
+    let scope = &mut v8::ContextScope::new(scope, context);
+
+    let code = v8::String::new(scope, "2 + 2").unwrap();
+    let script = v8::Script::compile(scope, code, None).unwrap();
+    let result = script.run(scope).unwrap();
+    assert_eq!(result.to_integer(scope).unwrap().value(), 4);
+  }
+}
+
+#[test]
+fn locker_is_locked() {
+  let _setup_guard = setup();
+  let mut isolate = v8::Isolate::new_unentered(Default::default());
+
+  assert!(!v8::Locker::is_locked(&isolate));
+  {
+    let _locker = v8::Locker::new(&mut isolate);
+  }
+  assert!(!v8::Locker::is_locked(&isolate));
+}
+
+fn setup() -> impl Drop {
+  use std::sync::Once;
+  static INIT: Once = Once::new();
+  INIT.call_once(|| {
+    let platform = v8::new_default_platform(0, false).make_shared();
+    v8::V8::initialize_platform(platform);
+    v8::V8::initialize();
+  });
+  struct Guard;
+  impl Drop for Guard {
+    fn drop(&mut self) {}
+  }
+  Guard
+}