Add v8::Locker, v8::Unlocker, and UnenteredIsolate bindings

Add support for multi-threaded isolate pooling architectures:

- UnenteredIsolate: An isolate type that doesn't auto-enter, allowing
  flexible ownership and no LIFO drop constraint
- Locker: Acquires exclusive access to an isolate for the current thread
- Unlocker: Temporarily releases a lock within a Locker scope

Key implementation details:
- Use isolate.as_real_ptr() for correct pointer casting
- Implement Send for UnenteredIsolate (thread safety via Locker)
- Add NewHandleScope impl for UnenteredIsolate
- Each thread must call enter() before first use to set up V8's
  thread-local state (LocalHeap)

This enables architectures similar to Cloudflare Workers where isolates
can be pooled and shared across threads.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: max-lt

src/binding.cc

@@ -170,6 +170,23 @@ 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);
+}
+
+void v8__Unlocker__CONSTRUCT(uninit_t<v8::Unlocker>* buf,
+                             v8::Isolate* isolate) {
+  construct_in_place<v8::Unlocker>(buf, isolate);
+}
+
+void v8__Unlocker__DESTRUCT(v8::Unlocker* self) { self->~Unlocker(); }
+
 v8::Isolate* v8__Isolate__GetCurrent() { return v8::Isolate::GetCurrent(); }
 
 const v8::Data* v8__Isolate__GetCurrentHostDefinedOptions(

src/isolate.rs

@@ -914,6 +914,26 @@ impl Isolate {
     OwnedIsolate::new(Self::new_impl(params))
   }
 
+  /// Creates a new isolate that does not automatically enter/exit.
+  ///
+  /// This is designed for use with `v8::Locker` in multi-threaded scenarios.
+  /// Unlike `Isolate::new()` which returns an `OwnedIsolate` that automatically
+  /// enters on creation and exits on drop, this returns an `UnenteredIsolate`
+  /// that requires manual entry management via `v8::Locker`.
+  ///
+  /// # Example
+  /// ```ignore
+  /// let isolate = v8::Isolate::new_unentered(params);
+  /// let locker = v8::Locker::new(&*isolate);
+  /// // Use isolate...
+  /// ```
+  ///
+  /// V8::initialize() must have run prior to this.
+  #[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 +2138,83 @@ impl AsMut<Isolate> for Isolate {
   }
 }
 
+/// An isolate that does not automatically enter/exit, designed for use with v8::Locker.
+///
+/// Unlike `OwnedIsolate` which automatically calls `enter()` on creation and `exit()` on drop,
+/// `UnenteredIsolate` requires manual entry management via `v8::Locker`.
+///
+/// This is useful for multi-threaded scenarios where isolates are shared across threads
+/// using the Locker pattern, as automatic enter/exit conflicts with Locker semantics.
+///
+/// # Example
+/// ```ignore
+/// use v8::{Isolate, UnenteredIsolate, Locker};
+///
+/// // Create isolate without entering
+/// let isolate = Isolate::new_unentered(params);
+///
+/// // Lock and enter on current thread
+/// let locker = Locker::new(&*isolate);
+///
+/// // Use isolate...
+///
+/// // Locker drop unlocks, isolate drop disposes (no exit call)
+/// ```
+#[derive(Debug)]
+pub struct UnenteredIsolate {
+  cxx_isolate: NonNull<RealIsolate>,
+}
+
+impl UnenteredIsolate {
+  pub(crate) fn new(cxx_isolate: *mut RealIsolate) -> Self {
+    let cxx_isolate = NonNull::new(cxx_isolate).unwrap();
+    Self { cxx_isolate }
+  }
+}
+
+impl Drop for UnenteredIsolate {
+  fn drop(&mut self) {
+    unsafe {
+      let snapshot_creator = self.get_annex_mut().maybe_snapshot_creator.take();
+      assert!(
+        snapshot_creator.is_none(),
+        "If isolate was created using v8::Isolate::snapshot_creator, you should use v8::UnenteredIsolate::create_blob before dropping an isolate."
+      );
+
+      // Unlike OwnedIsolate, we don't call exit() here as the isolate
+      // was never entered (or was entered/exited via Locker).
+      // We also don't assert on GetCurrent() since Locker manages entry.
+
+      self.dispose_annex();
+      Platform::notify_isolate_shutdown(&get_current_platform(), self);
+      self.dispose();
+    }
+  }
+}
+
+impl Deref for UnenteredIsolate {
+  type Target = Isolate;
+  fn deref(&self) -> &Self::Target {
+    unsafe { Isolate::from_raw_ref(&self.cxx_isolate) }
+  }
+}
+
+impl DerefMut for UnenteredIsolate {
+  fn deref_mut(&mut self) -> &mut Self::Target {
+    unsafe { Isolate::from_raw_ref_mut(&mut self.cxx_isolate) }
+  }
+}
+
+impl AsMut<Isolate> for UnenteredIsolate {
+  fn as_mut(&mut self) -> &mut Isolate {
+    self
+  }
+}
+
+// SAFETY: UnenteredIsolate can be sent between threads.
+// Thread safety is ensured by using v8::Locker before accessing the isolate.
+unsafe impl Send for UnenteredIsolate {}
+
 /// Collection of V8 heap information.
 ///
 /// Instances of this class can be passed to v8::Isolate::GetHeapStatistics to
@@ -2417,3 +2514,69 @@ impl AsRef<Isolate> for Isolate {
     self
   }
 }
+
+/// A stack-allocated class that governs exclusive access to an isolate.
+///
+/// Locks V8 in a given thread. All threads writing to a single isolate must
+/// use a `Locker` to ensure thread-safe access.
+///
+/// The isolate is automatically unlocked when the `Locker` goes out of scope.
+pub struct Locker {
+  _raw: crate::scope::raw::Locker,
+  _no_send: std::marker::PhantomData<*mut ()>,
+}
+
+impl Locker {
+  /// Initialize Locker for a given Isolate.
+  pub fn new(isolate: &Isolate) -> Self {
+    let mut raw = unsafe { crate::scope::raw::Locker::uninit() };
+    let isolate_ptr = NonNull::new(isolate.as_real_ptr()).unwrap();
+
+    unsafe {
+      raw.init(isolate_ptr);
+    }
+
+    Self {
+      _raw: raw,
+      _no_send: std::marker::PhantomData,
+    }
+  }
+
+  /// Returns whether or not the locker for a given isolate is locked by the
+  /// current thread.
+  pub fn is_locked(isolate: &Isolate) -> bool {
+    let isolate_ptr = NonNull::new(isolate.as_real_ptr()).unwrap();
+
+    crate::scope::raw::Locker::is_locked(isolate_ptr)
+  }
+}
+
+/// A stack-allocated class that temporarily unlocks an isolate.
+///
+/// An Unlocker may be used to temporarily release the lock on an isolate,
+/// allowing other threads to access it. This is useful for long-running
+/// operations where you want to yield control to other threads.
+///
+/// An Unlocker can only be used within the scope of a `Locker` and will
+/// restore the lock when it goes out of scope.
+pub struct Unlocker {
+  _raw: crate::scope::raw::Unlocker,
+  _no_send: std::marker::PhantomData<*mut ()>,
+}
+
+impl Unlocker {
+  /// Initialize Unlocker for a given Isolate.
+  pub fn new(isolate: &Isolate) -> Self {
+    let mut raw = unsafe { crate::scope::raw::Unlocker::uninit() };
+    let isolate_ptr = NonNull::new(isolate.as_real_ptr()).unwrap();
+
+    unsafe {
+      raw.init(isolate_ptr);
+    }
+
+    Self {
+      _raw: raw,
+      _no_send: std::marker::PhantomData,
+    }
+  }
+}

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,8 @@ pub use isolate::PromiseHookType;
 pub use isolate::PromiseRejectCallback;
 pub use isolate::RealIsolate;
 pub use isolate::TimeZoneDetection;
+pub use isolate::UnenteredIsolate;
+pub use isolate::Unlocker;
 pub use isolate::UseCounterCallback;
 pub use isolate::UseCounterFeature;
 pub use isolate::WasmAsyncSuccess;

src/scope.rs

@@ -128,8 +128,8 @@
 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,
+  SealedLocal, UnenteredIsolate, Value, fast_api::FastApiCallbackOptions,
+  isolate::RealIsolate, support::assert_layout_subset,
 };
 use std::{
   any::type_name,
@@ -442,6 +442,20 @@ impl<'s> NewHandleScope<'s> for OwnedIsolate {
   }
 }
 
+impl<'s> NewHandleScope<'s> for UnenteredIsolate {
+  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,77 @@ impl Drop for AllowJavascriptExecutionScope {
   }
 }
 
+#[repr(C)]
+#[derive(Debug)]
+pub(crate) struct Locker([MaybeUninit<usize>; 2]);
+
+impl Locker {
+  /// Creates an uninitialized `Locker`.
+  ///
+  /// This function is marked unsafe because the caller must ensure that the
+  /// returned value isn't dropped before `init()` has been called.
+  #[inline]
+  pub unsafe fn uninit() -> Self {
+    Self(unsafe { MaybeUninit::uninit().assume_init() })
+  }
+
+  /// This function is marked unsafe because `init()` must be called exactly
+  /// once, no more and no less, after creating a `Locker` value with
+  /// `Locker::uninit()`.
+  #[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());
+    }
+  }
+
+  /// Check if the isolate is locked by any thread.
+  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) };
+  }
+}
+
+#[repr(C)]
+#[derive(Debug)]
+pub(crate) struct Unlocker([MaybeUninit<usize>; 2]);
+
+impl Unlocker {
+  /// Creates an uninitialized `Unlocker`.
+  ///
+  /// This function is marked unsafe because the caller must ensure that the
+  /// returned value isn't dropped before `init()` has been called.
+  #[inline]
+  pub unsafe fn uninit() -> Self {
+    Self(unsafe { MaybeUninit::uninit().assume_init() })
+  }
+
+  /// This function is marked unsafe because `init()` must be called exactly
+  /// once, no more and no less, after creating an `Unlocker` value with
+  /// `Unlocker::uninit()`.
+  #[inline]
+  pub unsafe fn init(&mut self, isolate: NonNull<RealIsolate>) {
+    let buf = NonNull::from(self).cast();
+    unsafe {
+      v8__Unlocker__CONSTRUCT(buf.as_ptr(), isolate.as_ptr());
+    }
+  }
+}
+
+impl Drop for Unlocker {
+  #[inline(always)]
+  fn drop(&mut self) {
+    unsafe { v8__Unlocker__DESTRUCT(self) };
+  }
+}
+
 unsafe extern "C" {
   pub(super) fn v8__Isolate__GetCurrent() -> *mut RealIsolate;
   pub(super) fn v8__Isolate__GetCurrentContext(
@@ -311,4 +382,17 @@ 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;
+
+  pub(super) fn v8__Unlocker__CONSTRUCT(
+    buf: *mut MaybeUninit<Unlocker>,
+    isolate: *mut RealIsolate,
+  );
+  pub(super) fn v8__Unlocker__DESTRUCT(this: *mut Unlocker);
 }