feat(napi): meter page-backed V8 buffers per application

Author: theduke

src/budget.rs

@@ -155,6 +155,12 @@ pub enum Pool {
     /// slots, finalizer records, deferreds, scope frames, callback
     /// registrations), granted in chunks by [`napi_host_bookkeeping_charge`].
     HostBookkeeping,
+    /// Committed pages of buffers V8 reserves through its page allocator
+    /// rather than the `ArrayBuffer::Allocator`: resizable `ArrayBuffer`s and
+    /// growable `SharedArrayBuffer`s. Charged softly (see
+    /// [`ResourceBudget::try_charge_soft`]): a refused commit surfaces in JS as
+    /// a `RangeError` and does not stop the context.
+    V8BackingPages,
 }
 
 /// Embedder-owned aggregate accounting for byte reservations made by N-API.
@@ -165,6 +171,14 @@ pub trait NapiMemoryAccountant: Send + Sync {
     fn memory_limit(&self) -> u64;
     fn memory_charged(&self) -> u64;
     fn try_charge(&self, bytes: u64) -> bool;
+    /// Charge bytes whose refusal the provider handles gracefully (V8 turns
+    /// it into a JS `RangeError`). Must deny without side effects such as
+    /// stopping the application; it may be called from V8 background
+    /// threads and must not call back into V8. Embedders whose
+    /// [`try_charge`](Self::try_charge) is terminal should override it.
+    fn try_charge_soft(&self, bytes: u64) -> bool {
+        self.try_charge(bytes)
+    }
     fn uncharge(&self, bytes: u64);
 }
 
@@ -219,6 +233,8 @@ pub struct ResourceUsage {
     /// [`DEFAULT_HEAP_EMERGENCY_HEADROOM`]). Non-zero means at least one
     /// isolate of this budget is stopping after exhausting its heap.
     pub v8_heap_emergency: u64,
+    /// Committed bytes of page-allocated V8 buffers (resizable buffers).
+    pub v8_backing_pages: u64,
     /// Number of live V8 isolates (envs) counted against `max_envs`.
     pub live_isolates: usize,
 }
@@ -281,6 +297,7 @@ pub struct ResourceBudget {
     /// Emergency headroom currently exposed, summed over stopping isolates.
     /// Not part of `mem_charged`: it is by definition over the budget.
     v8_heap_emergency: AtomicU64,
+    v8_backing_pages: AtomicU64,
     /// Live V8 isolates (envs), counted against `max_envs`.
     live_isolates: AtomicUsize,
 }
@@ -316,6 +333,10 @@ impl std::fmt::Debug for ResourceBudget {
                 "v8_heap_emergency",
                 &self.v8_heap_emergency.load(Ordering::Acquire),
             )
+            .field(
+                "v8_backing_pages",
+                &self.v8_backing_pages.load(Ordering::Acquire),
+            )
             .field("live_isolates", &self.live_isolates.load(Ordering::Acquire))
             .finish()
     }
@@ -358,6 +379,7 @@ impl ResourceBudget {
             host_bookkeeping: AtomicU64::new(0),
             heap_emergency_headroom: AtomicU64::new(DEFAULT_HEAP_EMERGENCY_HEADROOM),
             v8_heap_emergency: AtomicU64::new(0),
+            v8_backing_pages: AtomicU64::new(0),
             live_isolates: AtomicUsize::new(0),
         })
     }
@@ -376,6 +398,7 @@ impl ResourceBudget {
             host_bookkeeping: AtomicU64::new(0),
             heap_emergency_headroom: AtomicU64::new(DEFAULT_HEAP_EMERGENCY_HEADROOM),
             v8_heap_emergency: AtomicU64::new(0),
+            v8_backing_pages: AtomicU64::new(0),
             live_isolates: AtomicUsize::new(0),
         }
     }
@@ -411,12 +434,29 @@ impl ResourceBudget {
     ///
     /// [`uncharge`]: ResourceBudget::uncharge
     pub fn try_charge(&self, pool: Pool, bytes: u64) -> Result<(), OverBudget> {
+        self.charge(pool, bytes, false)
+    }
+
+    /// Like [`try_charge`](Self::try_charge), but a refusal is reported only
+    /// to the caller: an embedder accountant is asked through
+    /// [`NapiMemoryAccountant::try_charge_soft`], so the application is not
+    /// stopped. For allocations whose failure V8 handles gracefully.
+    pub fn try_charge_soft(&self, pool: Pool, bytes: u64) -> Result<(), OverBudget> {
+        self.charge(pool, bytes, true)
+    }
+
+    fn charge(&self, pool: Pool, bytes: u64, soft: bool) -> Result<(), OverBudget> {
         if bytes == 0 {
             return Ok(());
         }
 
         if let Some(accountant) = &self.accountant {
-            if !accountant.try_charge(bytes) {
+            let granted = if soft {
+                accountant.try_charge_soft(bytes)
+            } else {
+                accountant.try_charge(bytes)
+            };
+            if !granted {
                 return Err(OverBudget {
                     pool,
                     requested: bytes,
@@ -480,6 +520,7 @@ impl ResourceBudget {
             Pool::HostTransient => &self.host_transient,
             Pool::SerializedMessage => &self.serialized_message,
             Pool::HostBookkeeping => &self.host_bookkeeping,
+            Pool::V8BackingPages => &self.v8_backing_pages,
         }
     }
 
@@ -496,6 +537,7 @@ impl ResourceBudget {
             serialized_message: self.serialized_message.load(Ordering::Acquire),
             host_bookkeeping: self.host_bookkeeping.load(Ordering::Acquire),
             v8_heap_emergency: self.v8_heap_emergency.load(Ordering::Acquire),
+            v8_backing_pages: self.v8_backing_pages.load(Ordering::Acquire),
             live_isolates: self.live_isolates.load(Ordering::Acquire),
         }
     }
@@ -1968,6 +2010,54 @@ mod external_accountant_tests {
         assert_eq!(budget.snapshot().v8_heap_reserved, 0);
     }
 
+    /// Counts terminal charges; soft charges must never take that path.
+    struct SoftAccountant {
+        inner: Arc<TestAccountant>,
+        terminal_calls: AtomicU64,
+    }
+
+    impl NapiMemoryAccountant for SoftAccountant {
+        fn memory_limit(&self) -> u64 {
+            self.inner.memory_limit()
+        }
+
+        fn memory_charged(&self) -> u64 {
+            self.inner.memory_charged()
+        }
+
+        fn try_charge(&self, bytes: u64) -> bool {
+            self.terminal_calls.fetch_add(1, Ordering::AcqRel);
+            self.inner.try_charge(bytes)
+        }
+
+        fn try_charge_soft(&self, bytes: u64) -> bool {
+            self.inner.try_charge(bytes)
+        }
+
+        fn uncharge(&self, bytes: u64) {
+            self.inner.uncharge(bytes);
+        }
+    }
+
+    #[test]
+    fn soft_charges_use_the_accountants_soft_path() {
+        let accountant = Arc::new(SoftAccountant {
+            inner: TestAccountant::new(100),
+            terminal_calls: AtomicU64::new(0),
+        });
+        let budget = ResourceBudget::with_accountant(accountant.clone());
+        budget.try_charge_soft(Pool::V8BackingPages, 80).unwrap();
+        let refused = budget
+            .try_charge_soft(Pool::V8BackingPages, 40)
+            .unwrap_err();
+        assert_eq!(refused.pool, Pool::V8BackingPages);
+        assert_eq!(accountant.terminal_calls.load(Ordering::Acquire), 0);
+        assert_eq!(budget.snapshot().v8_backing_pages, 80);
+        budget.uncharge(Pool::V8BackingPages, 80);
+        assert_eq!(budget.snapshot().v8_backing_pages, 0);
+        assert_eq!(budget.memory_charged(), 0);
+    }
+
     #[cfg(all(napi_standalone_legacy_wait, not(target_arch = "wasm32")))]
     #[test]
     fn external_accountant_cannot_use_legacy_raw_detachment() {

src/env.rs

@@ -272,6 +272,7 @@ impl NapiEnv {
             if self.host_stopped.load(Ordering::Acquire) {
                 anyhow::bail!("N-API instance stopped during activation");
             }
+            lane.attach_page_accountant(&self.budget);
             self.managed_lane = Some(lane);
         }
         Ok(self.managed_lane.as_ref().map(ManagedV8Lane::enter))

src/lane.rs

@@ -4,6 +4,8 @@ use std::{cell::RefCell, ffi::c_void, ptr::NonNull, sync::Arc};
 
 use anyhow::{Result, bail};
 
+use crate::budget::{Pool, ResourceBudget};
+
 /// Called for each actual V8 background task. Dropping the returned guard
 /// ends that task's metered active interval.
 pub type BackgroundTaskScope = Arc<dyn Fn() -> Box<dyn Send> + Send + Sync>;
@@ -24,6 +26,13 @@ unsafe extern "C" {
     fn snapi_v8_lane_stop(handle: *mut c_void);
     fn snapi_v8_lane_delete(handle: *mut c_void);
     fn snapi_v8_lane_swap_current(handle: *mut c_void) -> *mut c_void;
+    fn snapi_v8_lane_set_page_accountant(
+        handle: *mut c_void,
+        context: *mut c_void,
+        charge: unsafe extern "C" fn(*mut c_void, u64) -> bool,
+        uncharge: unsafe extern "C" fn(*mut c_void, u64),
+        release: unsafe extern "C" fn(*mut c_void),
+    ) -> bool;
 }
 
 pub struct ManagedV8Lane {
@@ -88,6 +97,29 @@ impl ManagedV8Lane {
         unsafe { snapi_v8_lane_run(self.handle.as_ptr()) }
     }
 
+    /// Charge commits of page-backed V8 buffers (resizable `ArrayBuffer`s,
+    /// growable `SharedArrayBuffer`s) reserved while this lane is bound to
+    /// `budget`. The first budget attached to a lane is kept; every context
+    /// sharing a lane shares its application's budget.
+    pub(crate) fn attach_page_accountant(&self, budget: &Arc<ResourceBudget>) {
+        let context = Arc::into_raw(Arc::clone(budget))
+            .cast_mut()
+            .cast::<c_void>();
+        let attached = unsafe {
+            snapi_v8_lane_set_page_accountant(
+                self.handle.as_ptr(),
+                context,
+                charge_backing_pages,
+                uncharge_backing_pages,
+                release_page_accountant,
+            )
+        };
+        if !attached {
+            // SAFETY: the lane did not take ownership of the reference.
+            drop(unsafe { Arc::from_raw(context.cast::<ResourceBudget>()) });
+        }
+    }
+
     /// Bind this queue to the calling thread while V8 creates or enters an
     /// isolate. The guard restores the previous binding on drop.
     pub(crate) fn enter(self: &Arc<Self>) -> ManagedV8LaneScope {
@@ -122,6 +154,29 @@ impl Drop for ManagedV8Lane {
     }
 }
 
+// The page-accountant context is an `Arc<ResourceBudget>` reference owned by
+// the native lane and its tracked regions; see `attach_page_accountant`.
+unsafe extern "C" fn charge_backing_pages(context: *mut c_void, bytes: u64) -> bool {
+    let budget = unsafe { &*context.cast::<ResourceBudget>() };
+    std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+        budget.try_charge_soft(Pool::V8BackingPages, bytes).is_ok()
+    }))
+    .unwrap_or(false)
+}
+
+unsafe extern "C" fn uncharge_backing_pages(context: *mut c_void, bytes: u64) {
+    let budget = unsafe { &*context.cast::<ResourceBudget>() };
+    let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+        budget.uncharge(Pool::V8BackingPages, bytes);
+    }));
+}
+
+unsafe extern "C" fn release_page_accountant(context: *mut c_void) {
+    let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+        drop(unsafe { Arc::from_raw(context.cast::<ResourceBudget>()) });
+    }));
+}
+
 unsafe extern "C" fn enter_task_scope(context: *mut c_void) -> *mut c_void {
     if context.is_null() {
         return std::ptr::null_mut();
@@ -237,6 +292,24 @@ mod tests {
 
     unsafe extern "C" fn run_noop_task(_data: *mut c_void) {}
 
+    #[test]
+    fn page_accountant_charges_softly_and_releases_its_budget_reference() {
+        let budget = ResourceBudget::with_memory_limit(8 * 4096);
+        let lane = ManagedV8Lane::new(1, Arc::new(|| Box::new(())), Arc::new(|| {})).unwrap();
+        lane.attach_page_accountant(&budget);
+        // A second attach is refused and must not leak its reference.
+        lane.attach_page_accountant(&budget);
+        assert_eq!(Arc::strong_count(&budget), 2);
+        let context = Arc::as_ptr(&budget).cast_mut().cast();
+        assert!(unsafe { charge_backing_pages(context, 6 * 4096) });
+        assert!(!unsafe { charge_backing_pages(context, 4 * 4096) });
+        assert_eq!(budget.snapshot().v8_backing_pages, 6 * 4096);
+        unsafe { uncharge_backing_pages(context, 6 * 4096) };
+        assert_eq!(budget.snapshot().v8_backing_pages, 0);
+        drop(lane);
+        assert_eq!(Arc::strong_count(&budget), 1);
+    }
+
     #[test]
     fn zero_queue_capacity_is_rejected() {
         assert!(ManagedV8Lane::new(0, Arc::new(|| Box::new(())), Arc::new(|| {})).is_err());