Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 91 additions & 1 deletion src/budget.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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);
}

Expand Down Expand Up @@ -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,
}
Expand Down Expand Up @@ -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,
}
Expand Down Expand Up @@ -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()
}
Expand Down Expand Up @@ -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),
})
}
Expand All @@ -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),
}
}
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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,
}
}

Expand All @@ -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),
}
}
Expand Down Expand Up @@ -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() {
Expand Down
1 change: 1 addition & 0 deletions src/env.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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))
Expand Down
73 changes: 73 additions & 0 deletions src/lane.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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>;
Expand All @@ -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 {
Expand Down Expand Up @@ -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 {
Expand Down Expand Up @@ -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();
Expand Down Expand Up @@ -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());
Expand Down
Loading
Loading