rework scopes to make them stack allocated and remove runtime bookkeeping of scopes (#1830)

Before this change, `HandleScope`s (and other scope types) were stored in the heap and we did bookkeeping at runtime of the current stack of scopes. The reasons were primarily:
- raw handle scopes need to be pinned in memory once initialized
- we couldn't enforce at compile that a `Local` didn't outlive the scope it was created from
The latter lead us to need a workaround where scopes actually were not exited when they were dropped, rather they were exited the next time we activated another scope.

This change refactors the scope implementation to:
- make scopes stack allocated, to reduce overhead of using them
- remove the runtime bookkeeping
- use lifetimes to prevent scopes from being dropped, so we can remove the `zombie` scope workaround

The practical effect is that creating a handle scope changes from:

```rust
let mut scope = v8::HandleScope::new(&mut isolate);
let local = v8::Integer::new(&mut scope, 123);
```

to:

```rust
let scope = std::pin::pin!(v8::HandleScope::new(&mut isolate));
let scope = scope.init();
let local = v8::Integer::new(&scope, 123);

// or shorter
v8::scope!(let scope, &mut isolate);
let local = v8::Integer::new(scope, 123);
```

If you accept a `HandleScope` as a parameter in a function, you would change it from:

```rust
fn takes_scope(s: &mut v8::HandleScope) {}
```

to

```rust
fn takes_scope(s: &mut v8::PinScope) {}
```

(`v8::PinScope` is a type alias for a pinned handle scope).

Author: nathanwhit

Cargo.toml

@@ -101,11 +101,14 @@ opt-level = 1
 default = ["use_custom_libcxx"]
 use_custom_libcxx = []
 v8_enable_pointer_compression = []
+v8_enable_v8_checks = []
 
 [dependencies]
 bitflags = "2.5"
 paste = "1.0"
-temporal_capi = { package = "ry_temporal_capi", version = "=0.0.11-ry.1", features = [ "compiled_data" ] }
+temporal_capi = { package = "ry_temporal_capi", version = "=0.0.11-ry.1", features = [
+  "compiled_data",
+] }
 
 [build-dependencies]
 miniz_oxide = "0.8.8"

benches/function.rs

@@ -10,14 +10,14 @@ fn main() {
   v8::V8::initialize_platform(platform);
   v8::V8::initialize();
   let isolate = &mut v8::Isolate::new(v8::CreateParams::default());
-  let handle_scope = &mut v8::HandleScope::new(isolate);
+  v8::scope!(let handle_scope, isolate);
   let context = v8::Context::new(handle_scope, Default::default());
   let scope = &mut v8::ContextScope::new(handle_scope, context);
   let global = context.global(scope);
   {
     let func = v8::Function::new(
       scope,
-      |scope: &mut v8::HandleScope,
+      |scope: &mut v8::PinScope,
        _: v8::FunctionCallbackArguments,
        mut rv: v8::ReturnValue| {
         rv.set(v8::Integer::new(scope, 42).into());
@@ -30,7 +30,8 @@ fn main() {
   {
     extern "C" fn callback(info: *const v8::FunctionCallbackInfo) {
       let info = unsafe { &*info };
-      let scope = unsafe { &mut v8::CallbackScope::new(info) };
+      let scope = std::pin::pin!(unsafe { v8::CallbackScope::new(info) });
+      let scope = &scope.init();
       let mut rv = v8::ReturnValue::from_function_callback_info(info);
       rv.set(v8::Integer::new(scope, 42).into());
     }
@@ -51,7 +52,7 @@ fn main() {
   {
     let func = v8::Function::new(
       scope,
-      |_: &mut v8::HandleScope,
+      |_: &mut v8::PinScope,
        _: v8::FunctionCallbackArguments,
        mut rv: v8::ReturnValue| {
         rv.set_uint32(42);
@@ -74,7 +75,7 @@ fn main() {
       ),
     );
     let template = v8::FunctionTemplate::builder(
-      |scope: &mut v8::HandleScope,
+      |scope: &mut v8::PinScope,
        _: v8::FunctionCallbackArguments,
        mut rv: v8::ReturnValue| {
         rv.set(v8::Integer::new(scope, 42).into());
@@ -90,7 +91,8 @@ fn main() {
   {
     extern "C" fn callback(info: *const v8::FunctionCallbackInfo) {
       let info = unsafe { &*info };
-      let scope = unsafe { &mut v8::CallbackScope::new(info) };
+      let scope = std::pin::pin!(unsafe { v8::CallbackScope::new(info) });
+      let scope = &scope.init();
       let mut rv = v8::ReturnValue::from_function_callback_info(info);
       rv.set(v8::undefined(scope).into());
     }
@@ -156,10 +158,11 @@ fn main() {
 }
 
 fn eval<'s>(
-  scope: &mut v8::HandleScope<'s>,
+  scope: &mut v8::PinScope<'s, '_>,
   code: &str,
 ) -> Option<v8::Local<'s, v8::Value>> {
-  let scope = &mut v8::EscapableHandleScope::new(scope);
+  v8::escapable_handle_scope!(let scope, scope);
+
   let source = v8::String::new(scope, code).unwrap();
   let script = v8::Script::compile(scope, source, None).unwrap();
   let r = script.run(scope);

build.rs

@@ -213,6 +213,10 @@ fn build_v8(is_asan: bool) {
     "v8_enable_pointer_compression={}",
     env::var("CARGO_FEATURE_V8_ENABLE_POINTER_COMPRESSION").is_ok()
   ));
+  gn_args.push(format!(
+    "v8_enable_v8_checks={}",
+    env::var("CARGO_FEATURE_V8_ENABLE_V8_CHECKS").is_ok()
+  ));
   // Fix GN's host_cpu detection when using x86_64 bins on Apple Silicon
   if cfg!(target_os = "macos") && cfg!(target_arch = "aarch64") {
     gn_args.push("host_cpu=\"arm64\"".to_string());

examples/cppgc-object.rs

@@ -30,31 +30,31 @@ const TAG: u16 = 1;
 fn main() {
   let platform = v8::new_default_platform(0, false).make_shared();
   v8::V8::set_flags_from_string("--no_freeze_flags_after_init --expose-gc");
-  v8::V8::initialize_platform(platform.clone());
-  v8::V8::initialize();
 
+  v8::V8::initialize_platform(platform.clone());
   v8::cppgc::initialize_process(platform.clone());
+  v8::V8::initialize();
 
   {
     let heap =
       v8::cppgc::Heap::create(platform, v8::cppgc::HeapCreateParams::default());
     let isolate =
       &mut v8::Isolate::new(v8::CreateParams::default().cpp_heap(heap));
 
-    let handle_scope = &mut v8::HandleScope::new(isolate);
+    v8::scope!(handle_scope, isolate);
     let context = v8::Context::new(handle_scope, Default::default());
     let scope = &mut v8::ContextScope::new(handle_scope, context);
     let global = context.global(scope);
     {
       let func = v8::Function::new(
         scope,
-        |scope: &mut v8::HandleScope,
+        |scope: &mut v8::PinScope<'_, '_>,
          args: v8::FunctionCallbackArguments,
          mut rv: v8::ReturnValue| {
           let id = args.get(0).to_rust_string_lossy(scope);
 
           fn empty(
-            _scope: &mut v8::HandleScope,
+            _scope: &mut v8::PinScope<'_, '_>,
             _args: v8::FunctionCallbackArguments,
             _rv: v8::ReturnValue,
           ) {
@@ -113,8 +113,8 @@ fn execute_script(
   context_scope: &mut v8::ContextScope<v8::HandleScope>,
   script: v8::Local<v8::String>,
 ) {
-  let scope = &mut v8::HandleScope::new(context_scope);
-  let try_catch = &mut v8::TryCatch::new(scope);
+  v8::scope!(handle_scope, context_scope);
+  v8::tc_scope!(let try_catch, handle_scope);
 
   let script = v8::Script::compile(try_catch, script, None)
     .expect("failed to compile script");

examples/cppgc.rs

@@ -52,8 +52,8 @@ impl Drop for Rope {
 fn main() {
   let platform = v8::new_default_platform(0, false).make_shared();
   v8::V8::initialize_platform(platform.clone());
-  v8::V8::initialize();
   v8::cppgc::initialize_process(platform.clone());
+  v8::V8::initialize();
 
   {
     // Create a managed heap.

examples/hello_world.rs

@@ -9,14 +9,13 @@ fn main() {
     let isolate = &mut v8::Isolate::new(v8::CreateParams::default());
 
     // Create a stack-allocated handle scope.
-    let handle_scope = &mut v8::HandleScope::new(isolate);
+    v8::scope!(let handle_scope, isolate);
 
     // Create a new context.
     let context = v8::Context::new(handle_scope, Default::default());
 
     // Enter the context for compiling and running the hello world script.
-    let scope = &mut v8::ContextScope::new(handle_scope, context);
-
+    let scope = &v8::ContextScope::new(handle_scope, context);
     // Create a string containing the JavaScript source code.
     let code = v8::String::new(scope, "'Hello' + ' World!'").unwrap();
 

examples/process.rs

@@ -3,7 +3,7 @@ use std::convert::TryFrom;
 
 #[allow(clippy::needless_pass_by_value)] // this function should follow the callback type
 fn log_callback(
-  scope: &mut v8::HandleScope,
+  scope: &mut v8::PinScope,
   args: v8::FunctionCallbackArguments,
   mut _retval: v8::ReturnValue,
 ) {
@@ -29,13 +29,13 @@ fn main() {
   }
 
   let mut isolate = v8::Isolate::new(v8::CreateParams::default());
-  let mut scope = v8::HandleScope::new(&mut isolate);
+  v8::scope!(let scope, &mut isolate);
 
   let source = std::fs::read_to_string(&file)
     .unwrap_or_else(|err| panic!("failed to open {file}: {err}"));
-  let source = v8::String::new(&mut scope, &source).unwrap();
+  let source = v8::String::new(scope, &source).unwrap();
 
-  let mut processor = JsHttpRequestProcessor::new(&mut scope, source, options);
+  let mut processor = JsHttpRequestProcessor::new(scope, source, options);
 
   let requests = vec![
     StringHttpRequest::new("/process.cc", "localhost", "google.com", "firefox"),
@@ -124,22 +124,19 @@ impl HttpRequest for StringHttpRequest {
 }
 
 /// An http request processor that is scriptable using JavaScript.
-struct JsHttpRequestProcessor<'s, 'i> {
-  context: v8::Local<'s, v8::Context>,
-  context_scope: v8::ContextScope<'i, v8::HandleScope<'s>>,
-  process_fn: Option<v8::Local<'s, v8::Function>>,
+struct JsHttpRequestProcessor<'scope, 'obj, 'isolate> {
+  context: v8::Local<'obj, v8::Context>,
+  context_scope: v8::ContextScope<'scope, 'obj, v8::HandleScope<'isolate>>,
+  process_fn: Option<v8::Local<'obj, v8::Function>>,
   request_template: v8::Global<v8::ObjectTemplate>,
   _map_template: Option<v8::Global<v8::ObjectTemplate>>,
 }
 
-impl<'s, 'i> JsHttpRequestProcessor<'s, 'i>
-where
-  's: 'i,
-{
+impl<'scope, 'obj, 'isolate> JsHttpRequestProcessor<'scope, 'obj, 'isolate> {
   /// Creates a scriptable HTTP request processor.
   pub fn new(
-    isolate_scope: &'i mut v8::HandleScope<'s, ()>,
-    source: v8::Local<'s, v8::String>,
+    isolate_scope: &'scope mut v8::PinScope<'obj, 'isolate, ()>,
+    source: v8::Local<'obj, v8::String>,
     options: HashMap<String, String>,
   ) -> Self {
     let global = v8::ObjectTemplate::new(isolate_scope);
@@ -155,14 +152,13 @@ where
         ..Default::default()
       },
     );
-    let mut context_scope = v8::ContextScope::new(isolate_scope, context);
+    let context_scope = v8::ContextScope::new(isolate_scope, context);
 
-    let request_template = v8::ObjectTemplate::new(&mut context_scope);
+    let request_template = v8::ObjectTemplate::new(&context_scope);
     request_template.set_internal_field_count(1);
 
     // make it global
-    let request_template =
-      v8::Global::new(&mut context_scope, request_template);
+    let request_template = v8::Global::new(&context_scope, request_template);
 
     let mut self_ = JsHttpRequestProcessor {
       context,
@@ -174,32 +170,29 @@ where
 
     // loads options and output
     let options = self_.wrap_map(options);
-    let options_str =
-      v8::String::new(&mut self_.context_scope, "options").unwrap();
-    self_.context.global(&mut self_.context_scope).set(
-      &mut self_.context_scope,
+    let options_str = v8::String::new(&self_.context_scope, "options").unwrap();
+    self_.context.global(&self_.context_scope).set(
+      &self_.context_scope,
       options_str.into(),
       options.into(),
     );
 
-    let output = v8::Object::new(&mut self_.context_scope);
-    let output_str =
-      v8::String::new(&mut self_.context_scope, "output").unwrap();
-    self_.context.global(&mut self_.context_scope).set(
-      &mut self_.context_scope,
+    let output = v8::Object::new(&self_.context_scope);
+    let output_str = v8::String::new(&self_.context_scope, "output").unwrap();
+    self_.context.global(&self_.context_scope).set(
+      &self_.context_scope,
       output_str.into(),
       output.into(),
     );
 
     // execute script
     self_.execute_script(source);
 
-    let process_str =
-      v8::String::new(&mut self_.context_scope, "Process").unwrap();
+    let process_str = v8::String::new(&self_.context_scope, "Process").unwrap();
     let process_fn = self_
       .context
-      .global(&mut self_.context_scope)
-      .get(&mut self_.context_scope, process_str.into())
+      .global(&self_.context_scope)
+      .get(&self_.context_scope, process_str.into())
       .expect("missing function Process");
 
     let process_fn = v8::Local::<v8::Function>::try_from(process_fn)
@@ -209,9 +202,10 @@ where
     self_
   }
 
-  fn execute_script(&mut self, script: v8::Local<'s, v8::String>) {
-    let scope = &mut v8::HandleScope::new(&mut self.context_scope);
-    let try_catch = &mut v8::TryCatch::new(scope);
+  fn execute_script(&mut self, script: v8::Local<'scope, v8::String>) {
+    v8::scope!(let scope, &mut self.context_scope);
+
+    v8::tc_scope!(let try_catch, scope);
 
     let script = v8::Script::compile(try_catch, script, None)
       .expect("failed to compile script");
@@ -235,8 +229,9 @@ where
     let request: Box<dyn HttpRequest> = Box::new(request);
     let request = self.wrap_request(request);
 
-    let scope = &mut v8::HandleScope::new(&mut self.context_scope);
-    let try_catch = &mut v8::TryCatch::new(scope);
+    v8::scope!(let scope, &mut self.context_scope);
+
+    v8::tc_scope!(let try_catch, scope);
 
     let process_fn = self.process_fn.as_mut().unwrap();
     let global = self.context.global(try_catch).into();
@@ -259,7 +254,7 @@ where
   fn wrap_request(
     &mut self,
     request: Box<dyn HttpRequest>,
-  ) -> v8::Local<'s, v8::Object> {
+  ) -> v8::Local<'scope, v8::Object> {
     // TODO: fix memory leak
 
     use std::ffi::c_void;
@@ -295,7 +290,7 @@ where
   /// This handles the properties of `HttpRequest`
   #[allow(clippy::needless_pass_by_value)] // this function should follow the callback type
   fn request_prop_handler(
-    scope: &mut v8::HandleScope,
+    scope: &mut v8::PinScope,
     key: v8::Local<v8::Name>,
     args: v8::PropertyCallbackArguments,
     mut rv: v8::ReturnValue,
@@ -327,7 +322,7 @@ where
 
   /// Utility function that extracts the http request object from a wrapper object.
   fn unwrap_request(
-    scope: &mut v8::HandleScope,
+    scope: &v8::PinScope,
     request: v8::Local<v8::Object>,
   ) -> *mut Box<dyn HttpRequest> {
     let external = request
@@ -340,9 +335,9 @@ where
   fn wrap_map(
     &mut self,
     options: HashMap<String, String>,
-  ) -> v8::Local<'s, v8::Object> {
+  ) -> v8::Local<'scope, v8::Object> {
     // TODO: wrap map, not convert into Object
-    let scope = &mut self.context_scope;
+    let scope = &self.context_scope;
     let result = v8::Object::new(scope);
 
     for (key, value) in options {
@@ -356,7 +351,9 @@ where
 
   /// Prints the output.
   pub fn print_output(&mut self) {
-    let scope = &mut v8::HandleScope::new(&mut self.context_scope);
+    let scope: std::pin::Pin<&mut v8::ScopeStorage<v8::HandleScope<'_>>> =
+      std::pin::pin!(v8::HandleScope::new(&mut self.context_scope));
+    let scope = &scope.init();
     let key = v8::String::new(scope, "output").unwrap();
     let output = self
       .context