Skip to main content

redjs/
web.rs

1//! Native web-scheduling core: `performance.now()`, requestAnimationFrame and
2//! setTimeout/setInterval implemented INSIDE redjs, pumped by the host once
3//! per frame with a single FFI call.
4//!
5//! Why native: these are the hottest engine globals (`performance.now()` is
6//! called constantly by app/profiling code, rAF once per frame per system).
7//! As `extern "sysv64"` Rust host functions they cost ~2 ns from JS — no
8//! trampoline slot, no reverse-P/Invoke. And everything shares ONE monotonic
9//! clock: rAF timestamps, timer deadlines, `performance.now()` and the value
10//! the host reads via `redjs_now` are the same time base.
11//!
12//! Semantics mirror the browser where it matters:
13//! - a pump snapshots due timers first; callbacks registered during the drain
14//!   fire on the NEXT pump (no same-tick reschedule loops);
15//! - intervals reschedule from `now + interval` (min 1 ms), one-shots die;
16//! - a timer cleared mid-drain by an earlier callback does not fire;
17//! - rAF callbacks are moved out before invoking; re-registration lands in
18//!   the next frame's batch; each gets the pump's `now` as DOMHighResTimeStamp;
19//! - callback exceptions go to the error funnel (`errors::report`, kind
20//!   `PumpCallback`) and never abort the pump.
21//!
22//! Threading: schedule/cancel host fns run on the JS thread (inside the VM);
23//! `redjs_pump` must be called from that same thread. The registry mutex is
24//! never held across a JS callback.
25
26use core::ffi::c_void;
27use std::cell::RefCell;
28use std::collections::HashMap;
29use std::sync::atomic::{AtomicBool, Ordering};
30use std::sync::{Mutex, OnceLock, RwLock};
31use std::time::Instant;
32
33use crate::capi;
34use crate::glue;
35
36// ---------------------------------------------------------------------------
37// Clock
38// ---------------------------------------------------------------------------
39
40struct Clock {
41    origin: Instant,
42    /// Unix epoch ms at origin (performance.timeOrigin).
43    epoch_origin_ms: f64,
44}
45
46fn clock() -> &'static Clock {
47    static CLOCK: OnceLock<Clock> = OnceLock::new();
48    CLOCK.get_or_init(|| Clock {
49        origin: Instant::now(),
50        epoch_origin_ms: std::time::SystemTime::now()
51            .duration_since(std::time::UNIX_EPOCH)
52            .map(|d| d.as_secs_f64() * 1000.0)
53            .unwrap_or(0.0),
54    })
55}
56
57pub fn now_ms() -> f64 {
58    clock().origin.elapsed().as_secs_f64() * 1000.0
59}
60
61// ---------------------------------------------------------------------------
62// Per-context scheduler state
63// ---------------------------------------------------------------------------
64
65struct Timer {
66    cb: u64,
67    /// Extra `setTimeout(cb, ms, ...args)` arguments (each protected).
68    args: Vec<u64>,
69    next_fire: f64,
70    interval: f64,
71    repeating: bool,
72}
73
74type NativeTask = Box<dyn FnOnce(*mut c_void) + Send>;
75
76#[derive(Default)]
77struct Scheduler {
78    raf: Vec<(u32, u64)>, // (id, protected callback) in registration order
79    raf_next_id: u32,
80    timers: HashMap<u32, Timer>,
81    timer_next_id: u32,
82    /// requestIdleCallback queue (fired after the rAF batch each pump).
83    idle: Vec<(u32, u64)>,
84    idle_next_id: u32,
85    /// Native one-shot tasks (async semantics for native APIs: image loads…).
86    native: Vec<(f64, NativeTask)>,
87}
88
89/// Schedules a native task on this context's pump (spec-async operations of
90/// the native web API: Image.src loading etc). Runs on the pump thread.
91pub(crate) fn schedule_native(g: *mut c_void, delay_ms: f64, task: NativeTask) {
92    let deadline = now_ms() + delay_ms.max(0.0);
93    let mut reg = registry().lock().unwrap();
94    reg.entry(g as usize).or_default().native.push((deadline, task));
95}
96
97/// [`schedule_native`] from ANOTHER thread, for the context `id` that asked.
98/// The task is dropped unrun when the context at `g` is no longer `id`: torn
99/// down (its scheduler entry is gone and must not be re-created, or the task
100/// and whatever it owns would be parked there for good) or replaced by a
101/// newer one at the same address (whose heap the task's values are not in).
102/// The check runs under the registry lock, so a teardown cannot slip between
103/// it and the push. `id: None` (a context nobody registered) behaves like
104/// [`schedule_native`].
105pub(crate) fn schedule_native_from(g: *mut c_void, id: Option<crate::context::ContextId>, delay_ms: f64, task: NativeTask) {
106    let deadline = now_ms() + delay_ms.max(0.0);
107    let mut reg = registry().lock().unwrap();
108    if id.is_some() && crate::context::id_of(g) != id {
109        drop(reg);
110        drop(task);
111        return;
112    }
113    reg.entry(g as usize).or_default().native.push((deadline, task));
114    drop(reg);
115    notify_embedder();
116}
117
118static WAKE_HOOK: OnceLock<fn()> = OnceLock::new();
119
120/// Called, from any thread, whenever work for a context is queued from outside its pump, so an
121/// embedder that stops pumping while idle knows to pump again. Set once.
122pub fn set_wake_hook(hook: fn()) {
123    let _ = WAKE_HOOK.set(hook);
124}
125
126pub(crate) fn notify_embedder() {
127    if let Some(hook) = WAKE_HOOK.get() {
128        hook();
129    }
130}
131
132/// When context `g` next has work for its pump, in [`now_ms`] time: its earliest timer or native
133/// task, now for a pending idle callback, JSC's GC and sweeper timers, or what a polling module
134/// needs. `None` when nothing is scheduled: work arriving from other threads then calls the
135/// [wake hook](set_wake_hook).
136pub fn next_work_ms(g: *mut c_void) -> Option<f64> {
137    let gc = unsafe { glue::rjs_gc_timers_due_s(g) };
138    let gc = (gc >= 0.0).then(|| now_ms() + gc * 1000.0);
139    #[cfg(feature = "audio")]
140    let polled = crate::webapi::mediadevices::next_poll_ms(g);
141    #[cfg(not(feature = "audio"))]
142    let polled = None;
143    next_scheduled_ms(g).into_iter().chain(gc).chain(polled).reduce(f64::min)
144}
145
146fn next_scheduled_ms(g: *mut c_void) -> Option<f64> {
147    let reg = registry().lock().unwrap();
148    let s = reg.get(&(g as usize))?;
149    let timers = s.timers.values().map(|t| t.next_fire);
150    let native = s.native.iter().map(|(at, _)| *at);
151    let idle = (!s.idle.is_empty()).then(now_ms);
152    timers.chain(native).chain(idle).reduce(f64::min)
153}
154
155fn registry() -> &'static Mutex<HashMap<usize, Scheduler>> {
156    static REG: OnceLock<Mutex<HashMap<usize, Scheduler>>> = OnceLock::new();
157    REG.get_or_init(|| Mutex::new(HashMap::new()))
158}
159
160/// `crate::context` fan-out. The timers, rAF/idle callbacks and native tasks
161/// of a context that is gone are DROPPED, never run: their callbacks are
162/// protected values in a heap that no longer exists.
163pub(crate) fn forget(gone: crate::context::Gone) {
164    let dropped = registry().lock().unwrap().remove(&gone.key);
165    drop(dropped); // outside the lock: native tasks may own Arcs with Drop impls
166    // Wakers are keyed by id, so a late `wake` for this id finds nothing.
167    let w = wakers().lock().unwrap().remove(&gone.id.0);
168    drop(w);
169}
170
171pub(crate) fn has_scheduler(g: *mut c_void) -> bool {
172    registry().lock().unwrap().contains_key(&(g as usize))
173}
174
175// ---------------------------------------------------------------------------
176// Host functions (SysV — direct JSC host calling convention)
177// ---------------------------------------------------------------------------
178
179#[inline]
180unsafe fn cf_argc(cf: *mut c_void) -> u32 {
181    (*((cf as usize + 32) as *const u32)).saturating_sub(1)
182}
183
184#[inline]
185unsafe fn cf_arg(cf: *mut c_void, i: u32) -> u64 {
186    if i < cf_argc(cf) {
187        *((cf as usize + 48 + (i as usize) * 8) as *const u64)
188    } else {
189        ENC_UNDEFINED
190    }
191}
192
193const ENC_UNDEFINED: u64 = 0xa;
194const TAG_NUMBER: u64 = 0xfffe_0000_0000_0000;
195
196#[inline]
197fn enc_int32(i: i32) -> u64 {
198    TAG_NUMBER | (i as u32 as u64)
199}
200
201#[inline]
202fn enc_double(d: f64) -> u64 {
203    let i = d as i32;
204    if i as f64 == d && !(i == 0 && d.is_sign_negative()) {
205        return enc_int32(i);
206    }
207    (d.to_bits() as i64).wrapping_add((1i64) << 49) as u64
208}
209
210#[inline]
211fn dec_number(v: u64) -> Option<f64> {
212    if (v & TAG_NUMBER) == TAG_NUMBER {
213        return Some(v as u32 as i32 as f64);
214    }
215    if (v & TAG_NUMBER) != 0 {
216        return Some(f64::from_bits((v as i64).wrapping_sub((1i64) << 49) as u64));
217    }
218    None
219}
220
221#[inline]
222fn is_cell(v: u64) -> bool {
223    v != 0 && (v & (TAG_NUMBER | 0x2)) == 0
224}
225
226#[crate::host_fn]
227unsafe fn perf_now(_g: *mut c_void, _cf: *mut c_void) -> u64 {
228    enc_double(now_ms())
229}
230
231#[crate::host_fn]
232unsafe fn raf_request(g: *mut c_void, cf: *mut c_void) -> u64 {
233    let cb = cf_arg(cf, 0);
234    if !is_cell(cb) {
235        return enc_int32(0);
236    }
237    capi::JSValueProtect(g, cb as usize as capi::JSValueRef);
238    let mut reg = registry().lock().unwrap();
239    let s = reg.entry(g as usize).or_default();
240    s.raf_next_id += 1;
241    let id = s.raf_next_id;
242    let first = s.raf.is_empty();
243    s.raf.push((id, cb));
244    drop(reg);
245    if first {
246        notify_embedder();
247    }
248    enc_int32(id as i32)
249}
250
251#[crate::host_fn]
252unsafe fn raf_cancel(g: *mut c_void, cf: *mut c_void) -> u64 {
253    if let Some(id) = dec_number(cf_arg(cf, 0)) {
254        let removed = {
255            let mut reg = registry().lock().unwrap();
256            let s = reg.entry(g as usize).or_default();
257            match s.raf.iter().position(|(i, _)| *i == id as u32) {
258                Some(pos) => Some(s.raf.remove(pos).1),
259                None => None,
260            }
261        };
262        if let Some(cb) = removed {
263            capi::JSValueUnprotect(g, cb as usize as capi::JSValueRef);
264        }
265    }
266    ENC_UNDEFINED
267}
268
269unsafe fn timer_set(g: *mut c_void, cf: *mut c_void, repeating: bool) -> u64 {
270    timer_set_inner(g, cf, repeating, None, 2)
271}
272
273/// `delay_override`: fixed delay ignoring arg 1 (setImmediate). `args_from`:
274/// first callback-argument index (2 for setTimeout, 1 for setImmediate).
275unsafe fn timer_set_inner(g: *mut c_void, cf: *mut c_void, repeating: bool, delay_override: Option<f64>, args_from: u32) -> u64 {
276    let cb = cf_arg(cf, 0);
277    if !is_cell(cb) {
278        return enc_int32(0);
279    }
280    let delay = delay_override.unwrap_or_else(|| dec_number(cf_arg(cf, 1)).unwrap_or(0.0).max(0.0));
281    let interval = if repeating { delay.max(1.0) } else { delay };
282    // Spec: trailing arguments are passed to the callback on every fire.
283    let args: Vec<u64> = (args_from..cf_argc(cf)).map(|i| cf_arg(cf, i)).collect();
284    capi::JSValueProtect(g, cb as usize as capi::JSValueRef);
285    for &a in &args {
286        if is_cell(a) {
287            capi::JSValueProtect(g, a as usize as capi::JSValueRef);
288        }
289    }
290    let now = now_ms();
291    let mut reg = registry().lock().unwrap();
292    let s = reg.entry(g as usize).or_default();
293    s.timer_next_id += 1;
294    let id = s.timer_next_id;
295    s.timers.insert(id, Timer { cb, args, next_fire: now + delay, interval, repeating });
296    enc_int32(id as i32)
297}
298
299#[crate::host_fn]
300unsafe fn timer_set_timeout(g: *mut c_void, cf: *mut c_void) -> u64 {
301    timer_set(g, cf, false)
302}
303
304#[crate::host_fn]
305unsafe fn timer_set_interval(g: *mut c_void, cf: *mut c_void) -> u64 {
306    timer_set(g, cf, true)
307}
308
309/// `setImmediate(cb, ...args)` — a 0-delay macrotask (fires on the next pump,
310/// before that pump's rAF batch). Shares the timer registry, so
311/// `clearImmediate` is just `clearTimeout`.
312#[crate::host_fn]
313unsafe fn immediate_set(g: *mut c_void, cf: *mut c_void) -> u64 {
314    timer_set_inner(g, cf, false, Some(0.0), 1)
315}
316
317/// `queueMicrotask(cb)` — the VM's real microtask queue.
318#[crate::host_fn]
319unsafe fn queue_microtask(g: *mut c_void, cf: *mut c_void) -> u64 {
320    let cb = cf_arg(cf, 0);
321    if glue::rjs_queue_microtask(g, cb) != 0 {
322        let m: Vec<u16> = "queueMicrotask: argument must be callable".encode_utf16().collect();
323        let mut err = ENC_UNDEFINED;
324        glue::rjs_error_create(g, 1, m.as_ptr(), m.len(), &mut err);
325        glue::rjs_throw(g, err);
326    }
327    ENC_UNDEFINED
328}
329
330#[crate::host_fn]
331unsafe fn idle_request(g: *mut c_void, cf: *mut c_void) -> u64 {
332    let cb = cf_arg(cf, 0);
333    if !is_cell(cb) {
334        return enc_int32(0);
335    }
336    capi::JSValueProtect(g, cb as usize as capi::JSValueRef);
337    let mut reg = registry().lock().unwrap();
338    let s = reg.entry(g as usize).or_default();
339    s.idle_next_id += 1;
340    let id = s.idle_next_id;
341    s.idle.push((id, cb));
342    enc_int32(id as i32)
343}
344
345#[crate::host_fn]
346unsafe fn idle_cancel(g: *mut c_void, cf: *mut c_void) -> u64 {
347    if let Some(id) = dec_number(cf_arg(cf, 0)) {
348        let removed = {
349            let mut reg = registry().lock().unwrap();
350            let s = reg.entry(g as usize).or_default();
351            match s.idle.iter().position(|(i, _)| *i == id as u32) {
352                Some(pos) => Some(s.idle.remove(pos).1),
353                None => None,
354            }
355        };
356        if let Some(cb) = removed {
357            capi::JSValueUnprotect(g, cb as usize as capi::JSValueRef);
358        }
359    }
360    ENC_UNDEFINED
361}
362
363/// IdleDeadline.timeRemaining(): a real decreasing budget so hydrate-style
364/// `while (deadline.timeRemaining() > 0)` loops make progress AND terminate.
365#[crate::host_fn]
366unsafe fn idle_time_remaining(g: *mut c_void, cf: *mut c_void) -> u64 {
367    let this = *((cf as usize + 40) as *const u64);
368    let a = glue::rjs_atom8(g, "__t0".as_ptr(), 4);
369    let mut t0 = ENC_UNDEFINED;
370    glue::rjs_get(g, this, a, &mut t0);
371    glue::rjs_atom_free(g, a);
372    let t0 = dec_number(t0).unwrap_or(0.0);
373    enc_double((4.0 - (now_ms() - t0)).max(0.0))
374}
375
376#[crate::host_fn]
377unsafe fn timer_clear(g: *mut c_void, cf: *mut c_void) -> u64 {
378    if let Some(id) = dec_number(cf_arg(cf, 0)) {
379        let removed = {
380            let mut reg = registry().lock().unwrap();
381            let s = reg.entry(g as usize).or_default();
382            s.timers.remove(&(id as u32))
383        };
384        if let Some(t) = removed {
385            unprotect_timer(g, &t);
386        }
387    }
388    ENC_UNDEFINED
389}
390
391unsafe fn unprotect_timer(g: *mut c_void, t: &Timer) {
392    capi::JSValueUnprotect(g, t.cb as usize as capi::JSValueRef);
393    for &a in &t.args {
394        if is_cell(a) {
395            capi::JSValueUnprotect(g, a as usize as capi::JSValueRef);
396        }
397    }
398}
399
400// ---------------------------------------------------------------------------
401// Install
402// ---------------------------------------------------------------------------
403
404unsafe fn define_native(g: *mut c_void, target: u64, name: &str, arity: u32, f: *const c_void) -> i32 {
405    let name16: Vec<u16> = name.encode_utf16().collect();
406    let mut func = 0u64;
407    let rc = glue::rjs_function_create(g, name16.as_ptr(), name16.len(), arity, f, &mut func);
408    if rc != 0 {
409        return rc;
410    }
411    let atom = glue::rjs_atom8(g, name.as_ptr(), name.len());
412    let rc = glue::rjs_define(g, target, atom, func, 0);
413    glue::rjs_atom_free(g, atom);
414    rc
415}
416
417/// Installs `performance` (now/timeOrigin), requestAnimationFrame /
418/// cancelAnimationFrame, setTimeout/clearTimeout/setInterval/clearInterval
419/// as NATIVE globals sharing one clock. Idempotent per context.
420pub unsafe fn install(g: *mut c_void) -> i32 {
421    // First: if this address last belonged to another context, its timers are
422    // purged here instead of being fired into this one (crate::context).
423    crate::context::ensure(g);
424    let _ = clock(); // pin the time origin before anything reads it
425    registry().lock().unwrap().entry(g as usize).or_default();
426
427    let global = glue::rjs_global(g);
428
429    // performance = { now(), timeOrigin }
430    let mut perf = 0u64;
431    let rc = glue::rjs_object_create(g, ENC_UNDEFINED, &mut perf);
432    if rc != 0 {
433        return rc;
434    }
435    let rc = define_native(g, perf, "now", 0, perf_now as *const c_void);
436    if rc != 0 {
437        return rc;
438    }
439    let atom = glue::rjs_atom8(g, "timeOrigin".as_ptr(), "timeOrigin".len());
440    glue::rjs_define(g, perf, atom, enc_double(clock().epoch_origin_ms), 0);
441    glue::rjs_atom_free(g, atom);
442    let atom = glue::rjs_atom8(g, "performance".as_ptr(), "performance".len());
443    let rc = glue::rjs_define(g, global, atom, perf, 0);
444    glue::rjs_atom_free(g, atom);
445    if rc != 0 {
446        return rc;
447    }
448
449    let fns: [(&str, u32, *const c_void); 11] = [
450        ("requestAnimationFrame", 1, raf_request as *const c_void),
451        ("cancelAnimationFrame", 1, raf_cancel as *const c_void),
452        ("setTimeout", 2, timer_set_timeout as *const c_void),
453        ("setInterval", 2, timer_set_interval as *const c_void),
454        ("clearTimeout", 1, timer_clear as *const c_void),
455        ("clearInterval", 1, timer_clear as *const c_void),
456        ("setImmediate", 1, immediate_set as *const c_void),
457        ("clearImmediate", 1, timer_clear as *const c_void),
458        ("queueMicrotask", 1, queue_microtask as *const c_void),
459        ("requestIdleCallback", 1, idle_request as *const c_void),
460        ("cancelIdleCallback", 1, idle_cancel as *const c_void),
461    ];
462    for (name, arity, f) in fns {
463        let rc = define_native(g, global, name, arity, f);
464        if rc != 0 {
465            return rc;
466        }
467    }
468    0
469}
470
471// ---------------------------------------------------------------------------
472// Pump
473// ---------------------------------------------------------------------------
474
475pub const PUMP_TIMERS: u32 = 1;
476pub const PUMP_RAF: u32 = 2;
477pub const PUMP_MICROTASKS: u32 = 4;
478/// A microtask checkpoint after EVERY task the pump runs (each timer, rAF and
479/// idle callback, each native task, each module pump's delivery batch), the
480/// way the HTML event loop does it — instead of one drain at the end of the
481/// pump. OFF for skathi's window today: turning it on there changes Vue's
482/// flush timing runtime-wide, which is its own decision (m25 indexeddb-design
483/// §4.1 IDB-D1, workers-design §3.2). A worker agent's loop always sets it.
484pub const PUMP_CHECKPOINT_PER_TASK: u32 = 8;
485
486pub use crate::ffi::RjsPumpStats;
487
488unsafe fn fire(g: *mut c_void, cb: u64, args: &[u64], flags: u32, label: &'static str) {
489    let mut out = 0u64;
490    let per_task = flags & PUMP_CHECKPOINT_PER_TASK != 0;
491    // Without a checkpoint per task, this callback's microtasks — and the
492    // "cleanup Indexed Database transactions" step — run at the end of the
493    // pump, not at the end of this callback. Modules that care (IndexedDB's
494    // IDB-D1 advisory) can ask.
495    let prev = COALESCED_CALLBACK.with(|c| c.replace(!per_task));
496    let rc = {
497        let _profile = crate::profiling::js_span(g, cb, label);
498        glue::rjs_call(g, cb, ENC_UNDEFINED, args.as_ptr(), args.len() as u32, &mut out)
499    };
500    COALESCED_CALLBACK.with(|c| c.set(prev));
501    if rc == 1 {
502        crate::errors::report(g, out, crate::errors::ErrKind::PumpCallback);
503    }
504    if per_task {
505        checkpoint(g);
506    }
507}
508
509thread_local! {
510    /// Set while a timer / rAF / idle callback runs in a pump that checkpoints
511    /// only once at its end (no `PUMP_CHECKPOINT_PER_TASK`).
512    static COALESCED_CALLBACK: core::cell::Cell<bool> = const { core::cell::Cell::new(false) };
513}
514
515/// Is a pumped timer, rAF or idle callback running right now whose microtask
516/// checkpoint is coalesced into the end of the pump (the window's shape, see
517/// [`PUMP_CHECKPOINT_PER_TASK`])? IndexedDB reads it to name its one timing
518/// divergence (IDB-D1) when a transaction is created there.
519pub fn in_coalesced_callback() -> bool {
520    COALESCED_CALLBACK.with(|c| c.get())
521}
522
523// ---------------------------------------------------------------------------
524// Waking a context, and the one bounded delivery wait per pump
525// ---------------------------------------------------------------------------
526//
527// Work produced on other threads (the IndexedDB server's results today, a
528// worker's messages next) lands in a per-context inbox and is delivered on the
529// context's own thread by a PUMP SOURCE. Two things are shared by every source,
530// on purpose (m25 workers-design §3.14.3):
531//
532// - ONE WAKER per context, keyed by `ContextId` (never by address): a producer
533//   pushes, then calls [`wake`]. A worker loop blocked in its wait, or a window
534//   pump inside its bounded wait, returns at once.
535// - ONE BUDGET per pump: while any source still has work in flight, the pump
536//   keeps delivering — and, when nothing is ready, waits on the waker — until
537//   the budget is spent. A browser runs tasks continuously between frames; a
538//   pump that only looked once per frame would cost an awaited IndexedDB
539//   request a whole frame per hop (`for … await store.get()` over 1000 ids:
540//   ~6 s at 165 Hz instead of ~0.1 s). The budget bounds what the frame pays.
541
542/// A context's waker. Waiting is done only by the context's own thread.
543pub struct Waker {
544    sys: wake_sys::Event,
545}
546
547impl Waker {
548    fn new() -> Waker {
549        Waker { sys: wake_sys::Event::new() }
550    }
551
552    /// Wakes the waiter (or the next wait, if nobody is waiting yet).
553    pub fn wake(&self) {
554        self.sys.set();
555    }
556
557    /// Waits until woken or until `timeout` elapses; `true` = woken. The
558    /// deadline is honoured to well under a millisecond on Windows (a
559    /// high-resolution waitable timer, not a condvar's 15.6 ms tick).
560    pub fn wait(&self, timeout: std::time::Duration) -> bool {
561        self.sys.wait(timeout)
562    }
563}
564
565fn wakers() -> &'static Mutex<HashMap<u64, std::sync::Arc<Waker>>> {
566    static W: OnceLock<Mutex<HashMap<u64, std::sync::Arc<Waker>>>> = OnceLock::new();
567    W.get_or_init(|| Mutex::new(HashMap::new()))
568}
569
570/// The waker of context `id`, created on first ask.
571pub fn waker(id: crate::context::ContextId) -> std::sync::Arc<Waker> {
572    wakers().lock().unwrap().entry(id.0).or_insert_with(|| std::sync::Arc::new(Waker::new())).clone()
573}
574
575/// Wakes context `id` from any thread. A no-op for an id that never asked
576/// for a waker (nobody can be waiting on it).
577pub fn wake(id: crate::context::ContextId) {
578    let w = wakers().lock().unwrap().get(&id.0).cloned();
579    if let Some(w) = w {
580        w.wake();
581    }
582    notify_embedder();
583}
584
585/// A producer of results for a context, delivered inside the pump's budget.
586#[derive(Clone, Copy)]
587pub struct PumpSource {
588    /// Can a result still arrive for `g` — is anything this source started
589    /// still outstanding? `false` lets the pump skip the wait altogether.
590    pub inflight: unsafe fn(*mut c_void) -> bool,
591    /// Is something already queued for `g` (cheap; polled while spinning)?
592    pub ready: unsafe fn(*mut c_void) -> bool,
593    /// Deliver what is queued for `g`, each item one task (it checkpoints
594    /// after each). Returns how many tasks ran.
595    pub drain: unsafe fn(*mut c_void) -> usize,
596}
597
598static ANY_SOURCE: AtomicBool = AtomicBool::new(false);
599
600fn sources() -> &'static RwLock<Vec<PumpSource>> {
601    static S: OnceLock<RwLock<Vec<PumpSource>>> = OnceLock::new();
602    S.get_or_init(|| RwLock::new(Vec::new()))
603}
604
605/// Registers a pump source, process-wide and for good (a module registers at
606/// install; the same `drain` twice is a no-op).
607pub fn register_pump_source(src: PumpSource) {
608    let mut s = sources().write().unwrap();
609    if !s.iter().any(|x| x.drain as usize == src.drain as usize) {
610        s.push(src);
611    }
612    ANY_SOURCE.store(true, Ordering::Release);
613}
614
615/// Default per-pump delivery budget: 4 ms (m25 indexeddb-design §3.3).
616///
617/// What the budget buys, measured on both backends (m25 P2,
618/// tests/idb_libs.rs with `REDJS_IDB_BUDGET_US`): for reads and relaxed
619/// commits the time spent inside pumps is the same at any budget (~23-30 ms
620/// per 1000 awaited gets) — the budget only decides how many frames that work
621/// is spread over (6 at 4 ms, 12 at 2 ms, 24 at 1 ms, 1000 at 0). For strict
622/// commits most of it is waiting on the fsync. An embedder that knows its
623/// display rate should scale the budget with the frame (skathi: a quarter
624/// of the refresh interval, capped here) — the wall-clock latency of a chain
625/// then stays the same at 60 and 144 Hz, and so does the frame's share.
626pub const DEFAULT_PUMP_BUDGET_US: u32 = 4000;
627static PUMP_BUDGET_US: std::sync::atomic::AtomicU32 = std::sync::atomic::AtomicU32::new(DEFAULT_PUMP_BUDGET_US);
628
629/// Sets the per-pump delivery budget, process-wide. 0 = deliver what is
630/// already queued and never wait (a worker loop's setting: its own wait on the
631/// same waker covers latency).
632pub fn set_pump_budget_us(us: u32) {
633    PUMP_BUDGET_US.store(us, Ordering::Relaxed);
634}
635
636pub fn pump_budget_us() -> u32 {
637    PUMP_BUDGET_US.load(Ordering::Relaxed)
638}
639
640/// How long the pump spins on `ready` before blocking on the waker: a thread
641/// hop through the OS costs ~10-50 µs, a result that is already on its way
642/// usually lands sooner.
643const SPIN: std::time::Duration = std::time::Duration::from_micros(20);
644
645/// Every source, within one budget. Cheap when nothing is in flight: one
646/// relaxed load per source.
647unsafe fn drain_sources(g: *mut c_void) {
648    if !ANY_SOURCE.load(Ordering::Acquire) {
649        return;
650    }
651    let srcs: Vec<PumpSource> = sources().read().unwrap().clone();
652    let busy = |srcs: &[PumpSource]| srcs.iter().any(|s| (s.inflight)(g) || (s.ready)(g));
653    if !busy(&srcs) {
654        return;
655    }
656    let start = Instant::now();
657    let deadline = start + std::time::Duration::from_micros(pump_budget_us() as u64);
658    let waker = crate::context::id_of(g).map(waker);
659    loop {
660        let mut ran = 0usize;
661        for s in &srcs {
662            ran += (s.drain)(g);
663        }
664        let now = Instant::now();
665        if now >= deadline || !srcs.iter().any(|s| (s.inflight)(g)) {
666            break;
667        }
668        if ran > 0 || srcs.iter().any(|s| (s.ready)(g)) {
669            continue;
670        }
671        // Nothing ready, something in flight: spin briefly, then sleep on the
672        // waker until it fires or the budget is spent.
673        let spin_until = (now + SPIN).min(deadline);
674        let mut got = false;
675        while Instant::now() < spin_until {
676            if srcs.iter().any(|s| (s.ready)(g)) {
677                got = true;
678                break;
679            }
680            core::hint::spin_loop();
681        }
682        if got {
683            continue;
684        }
685        let Some(w) = &waker else { break };
686        let now = Instant::now();
687        if now >= deadline {
688            break;
689        }
690        w.wait(deadline - now);
691    }
692}
693
694#[cfg(windows)]
695mod wake_sys {
696    //! An auto-reset event plus a high-resolution waitable timer: the wait
697    //! returns when the event is set or the timer fires, whichever is first.
698    //! Raw kernel32 declarations — no dependency.
699    use core::ffi::c_void;
700    use std::time::Duration;
701
702    type Handle = *mut c_void;
703    const CREATE_WAITABLE_TIMER_HIGH_RESOLUTION: u32 = 0x2;
704    const TIMER_ALL_ACCESS: u32 = 0x001F_0003;
705    const INFINITE: u32 = 0xFFFF_FFFF;
706    const WAIT_OBJECT_0: u32 = 0;
707
708    #[link(name = "kernel32")]
709    extern "system" {
710        fn CreateEventW(attrs: *mut c_void, manual_reset: i32, initial: i32, name: *const u16) -> Handle;
711        fn SetEvent(h: Handle) -> i32;
712        fn CreateWaitableTimerExW(attrs: *mut c_void, name: *const u16, flags: u32, access: u32) -> Handle;
713        fn SetWaitableTimer(h: Handle, due: *const i64, period: i32, cb: *mut c_void, arg: *mut c_void, resume: i32) -> i32;
714        fn CancelWaitableTimer(h: Handle) -> i32;
715        fn WaitForMultipleObjects(n: u32, handles: *const Handle, wait_all: i32, ms: u32) -> u32;
716        fn WaitForSingleObject(h: Handle, ms: u32) -> u32;
717        fn CloseHandle(h: Handle) -> i32;
718    }
719
720    pub struct Event {
721        ev: Handle,
722        timer: Handle,
723    }
724
725    // Handles are process-global kernel objects; SetEvent is thread-safe, and
726    // only the owning context's thread ever waits (so the timer is never armed
727    // from two threads).
728    unsafe impl Send for Event {}
729    unsafe impl Sync for Event {}
730
731    impl Event {
732        pub fn new() -> Event {
733            unsafe {
734                let ev = CreateEventW(core::ptr::null_mut(), 0, 0, core::ptr::null());
735                let mut timer = CreateWaitableTimerExW(
736                    core::ptr::null_mut(),
737                    core::ptr::null(),
738                    CREATE_WAITABLE_TIMER_HIGH_RESOLUTION,
739                    TIMER_ALL_ACCESS,
740                );
741                if timer.is_null() {
742                    // Before Windows 10 1803: a timer at the system tick.
743                    timer = CreateWaitableTimerExW(core::ptr::null_mut(), core::ptr::null(), 0, TIMER_ALL_ACCESS);
744                }
745                Event { ev, timer }
746            }
747        }
748
749        pub fn set(&self) {
750            unsafe {
751                SetEvent(self.ev);
752            }
753        }
754
755        pub fn wait(&self, timeout: Duration) -> bool {
756            unsafe {
757                if self.timer.is_null() {
758                    let ms = timeout.as_millis().clamp(1, (INFINITE - 1) as u128) as u32;
759                    return WaitForSingleObject(self.ev, ms) == WAIT_OBJECT_0;
760                }
761                // Relative due time, in 100 ns units, as a negative number.
762                let due: i64 = -((timeout.as_nanos() / 100).max(1) as i64);
763                SetWaitableTimer(self.timer, &due, 0, core::ptr::null_mut(), core::ptr::null_mut(), 0);
764                let hs = [self.ev, self.timer];
765                let r = WaitForMultipleObjects(2, hs.as_ptr(), 0, INFINITE);
766                CancelWaitableTimer(self.timer);
767                r == WAIT_OBJECT_0
768            }
769        }
770    }
771
772    impl Drop for Event {
773        fn drop(&mut self) {
774            unsafe {
775                if !self.ev.is_null() {
776                    CloseHandle(self.ev);
777                }
778                if !self.timer.is_null() {
779                    CloseHandle(self.timer);
780                }
781            }
782        }
783    }
784}
785
786#[cfg(not(windows))]
787mod wake_sys {
788    use std::sync::{Condvar, Mutex};
789    use std::time::Duration;
790
791    pub struct Event {
792        set: Mutex<bool>,
793        cv: Condvar,
794    }
795
796    impl Event {
797        pub fn new() -> Event {
798            Event { set: Mutex::new(false), cv: Condvar::new() }
799        }
800
801        pub fn set(&self) {
802            *self.set.lock().unwrap() = true;
803            self.cv.notify_one();
804        }
805
806        pub fn wait(&self, timeout: Duration) -> bool {
807            let g = self.set.lock().unwrap();
808            let (mut g, _) = self.cv.wait_timeout_while(g, timeout, |s| !*s).unwrap();
809            let woken = *g;
810            *g = false;
811            woken
812        }
813    }
814}
815
816// ---------------------------------------------------------------------------
817// The microtask checkpoint
818// ---------------------------------------------------------------------------
819
820/// Runs after every checkpoint that drained with no JS on the stack, with the
821/// context it ran for. The seam IndexedDB's "cleanup Indexed Database
822/// transactions" step hangs on (HTML §8.1.7.3 step 6). Must not run user JS:
823/// it runs at the END of a checkpoint, and a microtask it queued would wait
824/// for the next one.
825pub type CheckpointHook = unsafe fn(*mut c_void);
826
827static ANY_CHECKPOINT_HOOK: AtomicBool = AtomicBool::new(false);
828
829fn checkpoint_hooks() -> &'static RwLock<Vec<CheckpointHook>> {
830    static H: OnceLock<RwLock<Vec<CheckpointHook>>> = OnceLock::new();
831    H.get_or_init(|| RwLock::new(Vec::new()))
832}
833
834/// Registers a post-checkpoint hook, process-wide and for good (modules
835/// register at install; registering the same fn twice is a no-op).
836pub fn on_checkpoint(f: CheckpointHook) {
837    let mut hooks = checkpoint_hooks().write().unwrap();
838    if !hooks.iter().any(|h| *h as usize == f as usize) {
839        hooks.push(f);
840    }
841    ANY_CHECKPOINT_HOOK.store(true, Ordering::Release);
842}
843
844thread_local! {
845    /// HTML's per-event-loop "performing a microtask checkpoint" flag, kept per
846    /// context: the contexts this thread is checkpointing right now.
847    static CHECKPOINTING: RefCell<Vec<usize>> = const { RefCell::new(Vec::new()) };
848}
849
850/// What one [`checkpoint`] call did.
851#[derive(Debug, Clone, Copy, PartialEq, Eq)]
852pub enum Checkpoint {
853    /// Microtasks drained and the post-checkpoint hooks ran.
854    Full,
855    /// Microtasks drained, hooks NOT run: JavaScript is on the stack (a host
856    /// function asked for a drain mid-script). Running them there would, for
857    /// example, deactivate an IndexedDB transaction the calling script created a
858    /// moment ago — stricter than any browser.
859    DrainedInJs,
860    /// Nothing at all: this context is already performing a checkpoint further
861    /// up the stack (HTML: "if performing a microtask checkpoint is true,
862    /// return"). The outer drain runs whatever is still queued.
863    Nested,
864}
865
866/// THE microtask checkpoint — the single entry point every drain in redjs goes
867/// through: the end of [`pump`], [`crate::api::Context::drain_microtasks`], the
868/// `redjs_drain_microtasks` export (so skathi's own drains and a C# host's
869/// count), and an event dispatcher's between-listeners step. Nothing calls
870/// `rjs_drain_microtasks` directly any more.
871///
872/// = drain the VM's microtask queue (and JSC's deferred engine work), then the
873/// [`on_checkpoint`] hooks — the hooks only when no JS is on the stack.
874///
875/// One drain this function does not see: JSC drains by itself whenever the
876/// OUTERMOST API lock is released (`JSLock::willReleaseLock`), i.e. after any
877/// top-level call made without the lock held. Those drains run no hooks. An
878/// embedder that holds the lock across its frame — skathi's pump holds
879/// `redjs_lock`, a worker agent's loop will too — routes every drain here.
880///
881/// # Safety
882/// `g` must be a live context, on its VM thread.
883pub unsafe fn checkpoint(g: *mut c_void) -> Checkpoint {
884    let key = g as usize;
885    let nested = CHECKPOINTING.with(|c| {
886        let mut c = c.borrow_mut();
887        if c.contains(&key) {
888            true
889        } else {
890            c.push(key);
891            false
892        }
893    });
894    if nested {
895        return Checkpoint::Nested;
896    }
897    {
898        let _profile_context = crate::profiling::ContextScope::enter(g as usize);
899        let _profile = crate::profiling::span("microtask", "Promise / microtask checkpoint");
900        glue::rjs_drain_microtasks(g);
901    }
902    let full = glue::rjs_in_js(g) == 0;
903    if full && ANY_CHECKPOINT_HOOK.load(Ordering::Acquire) {
904        let hooks: Vec<CheckpointHook> = checkpoint_hooks().read().unwrap().clone();
905        for h in hooks {
906            h(g);
907        }
908    }
909    CHECKPOINTING.with(|c| c.borrow_mut().retain(|&k| k != key));
910    if full { Checkpoint::Full } else { Checkpoint::DrainedInJs }
911}
912
913extern "C" {
914    /// mimalloc (cpp/mimalloc, oven-sh's fork): see `idle_sweep`.
915    fn mi_on_thread_idle();
916}
917
918/// How often the JS thread's idle sweep runs, at most.
919const IDLE_SWEEP_MS: f64 = 250.0;
920
921thread_local! {
922    static LAST_IDLE_SWEEP: std::cell::Cell<f64> = const { std::cell::Cell::new(f64::NEG_INFINITY) };
923}
924static IDLE_SWEEPS: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
925static IDLE_SWEEP_US: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
926static IDLE_SWEEP_MAX_US: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
927static RUN_LOOP_US: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
928static RUN_LOOP_MAX_US: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
929
930/// `mi_on_thread_idle` on the thread that runs JS, at most every
931/// [`IDLE_SWEEP_MS`].
932///
933/// mimalloc gives pages back on allocator activity or when a thread says it
934/// is idle; JSC's helper threads say so when they park, but the JS thread is
935/// the embedder's and nothing said it there (README "Memory"). So a GC freed
936/// objects and the pages stayed resident: what the collection freed went back
937/// to the OS only if this thread happened to allocate again. The sweep
938/// collects the thread's pending frees, discards the free blocks inside its
939/// still-used pages and drains the arena purge queue.
940fn idle_sweep() {
941    let now = now_ms();
942    if LAST_IDLE_SWEEP.with(|l| now - l.get() < IDLE_SWEEP_MS) {
943        return;
944    }
945    let started = Instant::now();
946    unsafe { mi_on_thread_idle() };
947    // From when it RETURNED, as mimalloc's own interval counts.
948    LAST_IDLE_SWEEP.with(|l| l.set(now_ms()));
949    let us = started.elapsed().as_micros() as u64;
950    IDLE_SWEEPS.fetch_add(1, Ordering::Relaxed);
951    IDLE_SWEEP_US.fetch_add(us, Ordering::Relaxed);
952    IDLE_SWEEP_MAX_US.fetch_max(us, Ordering::Relaxed);
953}
954
955/// What the pump's between-wave memory work has cost since the process
956/// started: the JS thread's idle sweeps ([`idle_sweep`]) and the turns of the
957/// RunLoop that fire JSC's GC and sweeper timers (which include the GC work
958/// those timers do).
959#[derive(Clone, Copy, Debug, Default)]
960pub struct IdleWorkStats {
961    pub sweeps: u64,
962    pub sweep_us: u64,
963    pub sweep_max_us: u64,
964    pub run_loop_us: u64,
965    pub run_loop_max_us: u64,
966}
967
968pub fn idle_work_stats() -> IdleWorkStats {
969    IdleWorkStats {
970        sweeps: IDLE_SWEEPS.load(Ordering::Relaxed),
971        sweep_us: IDLE_SWEEP_US.load(Ordering::Relaxed),
972        sweep_max_us: IDLE_SWEEP_MAX_US.load(Ordering::Relaxed),
973        run_loop_us: RUN_LOOP_US.load(Ordering::Relaxed),
974        run_loop_max_us: RUN_LOOP_MAX_US.load(Ordering::Relaxed),
975    }
976}
977
978pub unsafe fn pump(g: *mut c_void, flags: u32, stats: *mut RjsPumpStats) {
979    let _profile_context = crate::profiling::ContextScope::enter(g as usize);
980    let _profile = crate::profiling::span("native", "JavaScript task pump");
981    let now = now_ms();
982    let key = g as usize;
983    let mut timers_fired = 0u32;
984    let mut raf_fired = 0u32;
985    let per_task = flags & PUMP_CHECKPOINT_PER_TASK != 0;
986
987    if flags & PUMP_TIMERS != 0 {
988        // Native one-shots first (image loads etc). Taken under the lock, run
989        // without it; tasks scheduled by tasks land on the next pump.
990        let due_native: Vec<NativeTask> = {
991            let mut reg = registry().lock().unwrap();
992            let s = reg.entry(key).or_default();
993            let mut due = Vec::new();
994            let mut i = 0;
995            while i < s.native.len() {
996                if now >= s.native[i].0 {
997                    due.push(s.native.swap_remove(i).1);
998                } else {
999                    i += 1;
1000                }
1001            }
1002            due
1003        };
1004        for task in due_native {
1005            { let _profile = crate::profiling::span("native", "Async native task"); task(g); }
1006            if per_task {
1007                checkpoint(g);
1008            }
1009        }
1010
1011        // Snapshot due timers (entries stay in the map so a mid-drain clear
1012        // by an earlier callback is honored), then fire without the lock.
1013        let due: Vec<(u32, u64, Vec<u64>, f64, bool, f64)> = {
1014            let mut reg = registry().lock().unwrap();
1015            let s = reg.entry(key).or_default();
1016            let mut due: Vec<_> = s
1017                .timers
1018                .iter()
1019                .filter(|(_, t)| now >= t.next_fire)
1020                .map(|(id, t)| (*id, t.cb, t.args.clone(), t.interval, t.repeating, t.next_fire))
1021                .collect();
1022            // Browser ordering: earliest deadline first, registration order ties.
1023            due.sort_by(|a, b| a.5.total_cmp(&b.5).then(a.0.cmp(&b.0)));
1024            due
1025        };
1026
1027        for (id, cb, args, interval, repeating, _deadline) in due {
1028            // Skip if a callback earlier in this drain cleared it.
1029            let still_there = registry().lock().unwrap().entry(key).or_default().timers.contains_key(&id);
1030            if !still_there {
1031                continue;
1032            }
1033            fire(g, cb, &args, flags, if repeating { "setInterval callback" } else { "setTimeout callback" });
1034            timers_fired += 1;
1035
1036            let removed = {
1037                let mut reg = registry().lock().unwrap();
1038                let s = reg.entry(key).or_default();
1039                if repeating {
1040                    // Don't resurrect an interval its own callback cleared.
1041                    if let Some(t) = s.timers.get_mut(&id) {
1042                        t.next_fire = now + interval;
1043                    }
1044                    None
1045                } else {
1046                    s.timers.remove(&id)
1047                }
1048            };
1049            if let Some(t) = removed {
1050                unprotect_timer(g, &t);
1051            }
1052        }
1053    }
1054
1055    if flags & PUMP_RAF != 0 {
1056        // Swap the batch out; re-registrations during callbacks land in the
1057        // fresh vec (next frame).
1058        let batch: Vec<(u32, u64)> = {
1059            let mut reg = registry().lock().unwrap();
1060            core::mem::take(&mut reg.entry(key).or_default().raf)
1061        };
1062        let ts = [enc_double(now)];
1063        for (_, cb) in &batch {
1064            fire(g, *cb, &ts, flags, "requestAnimationFrame callback");
1065            raf_fired += 1;
1066        }
1067        for (_, cb) in &batch {
1068            capi::JSValueUnprotect(g, *cb as usize as capi::JSValueRef);
1069        }
1070    }
1071
1072    if flags & PUMP_RAF != 0 {
1073        // Idle callbacks after the frame work (requestIdleCallback). Each gets
1074        // an IdleDeadline with a real decreasing ~4ms budget.
1075        let idle_batch: Vec<(u32, u64)> = {
1076            let mut reg = registry().lock().unwrap();
1077            core::mem::take(&mut reg.entry(key).or_default().idle)
1078        };
1079        if !idle_batch.is_empty() {
1080            let mut deadline = ENC_UNDEFINED;
1081            glue::rjs_object_create(g, ENC_UNDEFINED, &mut deadline);
1082            let a = glue::rjs_atom8(g, "didTimeout".as_ptr(), 10);
1083            glue::rjs_define(g, deadline, a, 0x6 /* false */, 0);
1084            glue::rjs_atom_free(g, a);
1085            let a = glue::rjs_atom8(g, "__t0".as_ptr(), 4);
1086            glue::rjs_define(g, deadline, a, enc_double(now_ms()), 2);
1087            glue::rjs_atom_free(g, a);
1088            let name: Vec<u16> = "timeRemaining".encode_utf16().collect();
1089            let mut trf = ENC_UNDEFINED;
1090            glue::rjs_function_create(g, name.as_ptr(), name.len(), 0, idle_time_remaining as *const c_void, &mut trf);
1091            let a = glue::rjs_atom8(g, "timeRemaining".as_ptr(), 13);
1092            glue::rjs_define(g, deadline, a, trf, 2);
1093            glue::rjs_atom_free(g, a);
1094            for (_, cb) in &idle_batch {
1095                fire(g, *cb, &[deadline], flags, "requestIdleCallback callback");
1096            }
1097            for (_, cb) in &idle_batch {
1098                capi::JSValueUnprotect(g, *cb as usize as capi::JSValueRef);
1099            }
1100        }
1101    }
1102
1103    if flags & PUMP_TIMERS != 0 {
1104        // Permission `change` delivery. One `drain_changes()` call, and nothing
1105        // at all unless a host is installed and reports a subscription.
1106        crate::webapi::permissions::pump(g);
1107        if per_task {
1108            checkpoint(g);
1109        }
1110        // WebSocket delivery: open/message/error/close events parsed off-thread
1111        // and dispatched here, on the thread that owns the VM. One relaxed
1112        // atomic read when no socket is connected.
1113        crate::webapi::websocket::pump(g);
1114        if per_task {
1115            checkpoint(g);
1116        }
1117        // Results produced on other threads (IndexedDB), delivered — and
1118        // waited for — within one bounded budget. One relaxed load when no
1119        // source is registered or nothing is in flight.
1120        drain_sources(g);
1121    }
1122
1123    #[cfg(feature = "audio")]
1124    if flags & PUMP_TIMERS != 0 {
1125        // Web Audio upkeep: firewheel graph update, AudioParam timelines,
1126        // scheduled starts/stops, `onended` dispatch.
1127        crate::webapi::audio::pump(g);
1128        // Device hot-plug polling. Costs two property reads unless something
1129        // is actually listening for `devicechange`.
1130        crate::webapi::mediadevices::pump(g);
1131        // Finished `getUserMedia` opens and devices lost under live tracks.
1132        // One relaxed load when there are none.
1133        crate::webapi::mediastream::pump(g);
1134        if per_task {
1135            checkpoint(g);
1136        }
1137    }
1138
1139    if flags & PUMP_MICROTASKS != 0 {
1140        checkpoint(g);
1141    }
1142
1143    if flags & (PUMP_TIMERS | PUMP_RAF) != 0 {
1144        if let Some(ext) = crate::webapi::gpu_ext::get() {
1145            ext.pump(g);
1146        }
1147    }
1148
1149    // Between waves, with no JS on the stack: JSC's own timers (the GC and the
1150    // sweeper that shrinks the heap — glue.cpp `rjs_run_loop_cycle`), then the
1151    // allocator's idle sweep of this thread's heaps.
1152    if glue::rjs_in_js(g) == 0 {
1153        let started = Instant::now();
1154        glue::rjs_run_loop_cycle();
1155        let us = started.elapsed().as_micros() as u64;
1156        RUN_LOOP_US.fetch_add(us, Ordering::Relaxed);
1157        RUN_LOOP_MAX_US.fetch_max(us, Ordering::Relaxed);
1158        idle_sweep();
1159    }
1160
1161    if !stats.is_null() {
1162        let (raf_pending, timers_active, next_deadline) = {
1163            let mut reg = registry().lock().unwrap();
1164            let s = reg.entry(key).or_default();
1165            let next = s
1166                .timers
1167                .values()
1168                .map(|t| t.next_fire)
1169                .fold(f64::INFINITY, f64::min);
1170            (s.raf.len() as u32, s.timers.len() as u32, if next.is_finite() { next } else { -1.0 })
1171        };
1172        *stats = RjsPumpStats {
1173            now,
1174            timers_fired,
1175            raf_fired,
1176            raf_pending,
1177            timers_active,
1178            next_timer_deadline: next_deadline,
1179        };
1180    }
1181}
1182
1183pub fn set_uncaught(handler: *const c_void) {
1184    crate::errors::set_handler(handler)
1185}
1186
1187#[cfg(test)]
1188mod checkpoint_tests {
1189    use super::*;
1190    use crate::api::Context;
1191    use crate::webapi::testing::{ok, s};
1192    use crate::webapi::util::{define, make_fn};
1193
1194    /// Hooks are process-wide and tests run in parallel, so every observation
1195    /// is filed under the context it was made for.
1196    fn hook_runs() -> &'static Mutex<HashMap<usize, u32>> {
1197        static R: OnceLock<Mutex<HashMap<usize, u32>>> = OnceLock::new();
1198        R.get_or_init(|| Mutex::new(HashMap::new()))
1199    }
1200    fn seen() -> &'static Mutex<HashMap<usize, Vec<Checkpoint>>> {
1201        static S: OnceLock<Mutex<HashMap<usize, Vec<Checkpoint>>>> = OnceLock::new();
1202        S.get_or_init(|| Mutex::new(HashMap::new()))
1203    }
1204    unsafe fn count_hook(g: *mut c_void) {
1205        *hook_runs().lock().unwrap().entry(g as usize).or_default() += 1;
1206    }
1207    fn runs(c: &Context) -> u32 {
1208        hook_runs().lock().unwrap().get(&(c.raw() as usize)).copied().unwrap_or(0)
1209    }
1210    fn outcomes(c: &Context) -> Vec<Checkpoint> {
1211        seen().lock().unwrap().get(&(c.raw() as usize)).cloned().unwrap_or_default()
1212    }
1213
1214    /// `__cp()` — a host function that asks for a checkpoint from inside JS.
1215    #[crate::host_fn]
1216    unsafe fn cp_from_js(g: *mut c_void, _cf: *mut c_void) -> u64 {
1217        let r = checkpoint(g);
1218        seen().lock().unwrap().entry(g as usize).or_default().push(r);
1219        ENC_UNDEFINED
1220    }
1221
1222    fn ctx() -> Context {
1223        on_checkpoint(count_hook);
1224        let c = crate::webapi::testing::ctx();
1225        unsafe {
1226            install(c.raw());
1227            let g = c.raw();
1228            define(g, glue::rjs_global(g), "__cp", make_fn(g, "__cp", 0, cp_from_js), 2);
1229        }
1230        c
1231    }
1232
1233    #[test]
1234    fn a_checkpoint_from_rust_drains_and_runs_the_hooks() {
1235        let c = ctx();
1236        s(&c, "globalThis.x = 0; Promise.resolve().then(() => { x = 1; }); 0");
1237        let before = runs(&c);
1238        assert_eq!(unsafe { checkpoint(c.raw()) }, Checkpoint::Full);
1239        ok(&c, "x === 1");
1240        assert_eq!(runs(&c), before + 1, "hooks run once per full checkpoint");
1241        // `Context::drain_microtasks` IS a checkpoint.
1242        c.drain_microtasks();
1243        assert_eq!(runs(&c), before + 2);
1244    }
1245
1246    #[test]
1247    fn a_checkpoint_asked_for_mid_script_drains_but_never_runs_the_hooks() {
1248        // HTML only cleans up (IDB transactions…) when the JS stack is empty: a
1249        // hook here would deactivate a transaction the calling script just made.
1250        let c = ctx();
1251        let before = runs(&c);
1252        ok(&c, "globalThis.y = 0; Promise.resolve().then(() => { y = 1; }); __cp(); y === 1");
1253        assert_eq!(outcomes(&c), vec![Checkpoint::DrainedInJs]);
1254        assert_eq!(runs(&c), before, "no hook while JS is on the stack");
1255    }
1256
1257    fn probes() -> &'static Mutex<Vec<usize>> {
1258        static P: Mutex<Vec<usize>> = Mutex::new(Vec::new());
1259        &P
1260    }
1261    /// A hook that asks for another checkpoint of the context it runs for —
1262    /// only for contexts that opted in, since hooks are process-wide.
1263    unsafe fn reentering_hook(g: *mut c_void) {
1264        if probes().lock().unwrap().contains(&(g as usize)) {
1265            let r = checkpoint(g);
1266            seen().lock().unwrap().entry(g as usize).or_default().push(r);
1267        }
1268    }
1269
1270    #[test]
1271    fn a_checkpoint_inside_a_checkpoint_is_a_no_op() {
1272        // "If the event loop's performing a microtask checkpoint is true, return."
1273        on_checkpoint(reentering_hook);
1274        let c = ctx();
1275        probes().lock().unwrap().push(c.raw() as usize);
1276        let before = runs(&c);
1277        assert_eq!(unsafe { checkpoint(c.raw()) }, Checkpoint::Full);
1278        probes().lock().unwrap().retain(|&k| k != c.raw() as usize);
1279        assert_eq!(outcomes(&c), vec![Checkpoint::Nested]);
1280        assert_eq!(runs(&c), before + 1, "the nested call ran no hooks of its own");
1281        // The flag is per context and cleared on the way out.
1282        assert_eq!(unsafe { checkpoint(c.raw()) }, Checkpoint::Full);
1283    }
1284
1285    #[test]
1286    fn per_task_checkpoints_run_microtasks_between_timers() {
1287        // HTML: the microtask a timer queues runs before the NEXT timer.
1288        // Without the flag the pump keeps its one-drain-at-the-end shape.
1289        for (flags, expect) in [
1290            (PUMP_TIMERS | PUMP_MICROTASKS | PUMP_CHECKPOINT_PER_TASK, "a,micro,b"),
1291            (PUMP_TIMERS | PUMP_MICROTASKS, "a,b,micro"),
1292        ] {
1293            let c = ctx();
1294            s(
1295                &c,
1296                "globalThis.log = [];
1297                 setTimeout(() => { log.push('a'); Promise.resolve().then(() => log.push('micro')); }, 0);
1298                 setTimeout(() => log.push('b'), 0); 0",
1299            );
1300            // Held across the pump, as an embedder's frame does (skathi's
1301            // pump holds `redjs_lock`): JSC drains microtasks by itself whenever
1302            // the OUTERMOST API lock is released, so an unlocked pump would get
1303            // a drain after every call regardless of the flag.
1304            unsafe {
1305                glue::rjs_lock(c.raw());
1306                pump(c.raw(), flags, core::ptr::null_mut());
1307                glue::rjs_unlock(c.raw());
1308            }
1309            assert_eq!(s(&c, "log.join()"), expect, "flags {flags}");
1310        }
1311    }
1312}
1313
1314#[cfg(test)]
1315mod native_from_tests {
1316    use super::*;
1317
1318    /// A result from another thread for a context that is gone is dropped,
1319    /// and the gone context's queue is not re-created (m25 review, finding 5;
1320    /// fetch's network delivery). For the live context it is queued as before.
1321    #[test]
1322    fn a_late_native_task_reaches_only_the_context_that_asked() {
1323        let c = crate::webapi::testing::ctx();
1324        let g = c.raw();
1325        unsafe { install(g) };
1326        let old = crate::context::id_of(g);
1327        assert!(old.is_some());
1328        schedule_native_from(g, old, 0.0, Box::new(|_| {}));
1329        assert!(has_scheduler(g), "the live context gets it");
1330        let new = unsafe { crate::context::register(g) };
1331        assert_ne!(Some(new), old);
1332        assert!(!has_scheduler(g));
1333        // Dropping the task is observable: it owns this, and lets go of it.
1334        let owned = std::sync::Arc::new(());
1335        let held = std::sync::Arc::clone(&owned);
1336        schedule_native_from(g, old, 0.0, Box::new(move |_| drop(held)));
1337        assert!(!has_scheduler(g), "nothing re-created for the old context");
1338        assert_eq!(std::sync::Arc::strong_count(&owned), 1, "the task was dropped, not parked");
1339    }
1340
1341    /// An embedder that stops pumping while idle is told when the next work is due, and woken for
1342    /// work queued from another thread.
1343    #[test]
1344    fn an_idle_embedder_learns_of_due_and_queued_work() {
1345        use std::sync::atomic::AtomicUsize;
1346        static WOKEN: AtomicUsize = AtomicUsize::new(0);
1347        set_wake_hook(|| {
1348            WOKEN.fetch_add(1, Ordering::SeqCst);
1349        });
1350        let c = crate::webapi::testing::ctx();
1351        let g = c.raw();
1352        unsafe { install(g) };
1353        assert_eq!(next_scheduled_ms(g), None);
1354        crate::webapi::testing::s(&c, "setTimeout(() => {}, 5000); 0");
1355        let due = next_scheduled_ms(g).expect("the timer");
1356        assert!(due > now_ms() + 4000.0 && due <= now_ms() + 5000.0, "{due}");
1357        assert!(next_work_ms(g).expect("the timer") <= due);
1358        crate::webapi::testing::s(&c, "globalThis.junk = []; for (let i = 0; i < 200000; i++) junk.push({ i }); junk = null; 0");
1359        let gc = unsafe { glue::rjs_gc_timers_due_s(g) };
1360        assert!(gc >= 0.0 && gc < 60.0, "a GC timer is armed after allocating: {gc}");
1361
1362        let before = WOKEN.load(Ordering::SeqCst);
1363        let id = crate::context::id_of(g);
1364        let addr = g as usize;
1365        std::thread::spawn(move || schedule_native_from(addr as *mut c_void, id, 0.0, Box::new(|_| {})))
1366            .join()
1367            .unwrap();
1368        assert!(WOKEN.load(Ordering::SeqCst) > before, "woken");
1369        assert!(next_work_ms(g).expect("the task") <= now_ms());
1370
1371        let before = WOKEN.load(Ordering::SeqCst);
1372        crate::webapi::testing::s(&c, "requestAnimationFrame(() => {}); 0");
1373        assert!(WOKEN.load(Ordering::SeqCst) > before, "a frame is wanted");
1374    }
1375}