Skip to content

runtime: react to OS memory-pressure signals (opt-in) - #30403

Closed
ig-ant wants to merge 11 commits into
mainfrom
claude/memory-pressure-watcher
Closed

ig-ant wants to merge 11 commits into
mainfrom
claude/memory-pressure-watcher

Conversation

@ig-ant

@ig-ant ig-ant commented May 8, 2026

Copy link
Copy Markdown
Collaborator

What does this PR do?

Adds a Bun-native memory-pressure watcher that, when the OS signals low memory, runs a sync JSC GC, schedules shrinkFootprintWhenIdle() (drops JIT code at the next safe point), forces mi_collect(true) to hand mimalloc free segments back to the OS, and bumps analytics.Features.memory_pressure so any later crash report carries memory_pressure(N).

Off by default behind BUN_FEATURE_FLAG_EXPERIMENTAL_MEMORY_PRESSURE_HANDLER=1 so it can be A/B'd before becoming default-on. No JS-visible hook.

Detection

Platform Mechanism Cross-thread dispatch
Windows CreateMemoryResourceNotification(LowMemoryResourceNotification) + RegisterWaitForSingleObject (NT threadpool, WT_EXECUTEONLYONCE); 30 s uv_timer holdoff before re-arm since the handle is level-triggered. Same approach upstream WebKit recently took in MemoryPressureHandlerWin. uv_async_send
macOS dispatch_source_create(DISPATCH_SOURCE_TYPE_MEMORYPRESSURE, …, WARN | CRITICAL | PROC_LIMIT_*) on a global utility queue. Edge-triggered on transitions, no holdoff needed. enqueueTaskConcurrent
Linux PSI trigger on /proc/pressure/memory (some 150000 1000000), blocked on POLLPRI by a parked thread; 30 s holdoff between fires. Gracefully no-ops where the trigger write fails (no PSI / no CAP_SYS_RESOURCE). enqueueTaskConcurrent

All three converge on respond() running on the JS thread.

Why not WTF::MemoryPressureHandler?

In Bun's JSCOnly WebKit build (PlatformJSCOnly.cmake), install() is the empty Generic stub on Apple, sets a flag with no OS hook on Linux (it expects GTK/WPE's UIProcess to call triggerMemoryPressureEvent over IPC), and 60 s polling on Windows. And releaseMemory() is a no-op without setLowMemoryHandler, so we'd be supplying the same Bun-side cleanup either way.

How did you verify your code works?

  • bun run zig:check-all — 61/61 (all 16 OS/arch/profile combos)
  • bun bd test test/js/bun/util/memory-pressure.test.ts — 3 pass / 0 fail (Linux)
  • USE_SYSTEM_BUN=1 bun test … — 0 pass / 3 skip (no false positives)
  • Manually confirmed the Linux install path runs and gracefully degrades without CAP_SYS_RESOURCE (PSI write → EINVAL, watcher logs PSI unavailable and skips).

Tests use the debug-only Bun.unsafe.simulateMemoryPressure() seam and a WeakRef to deterministically assert the sync GC ran (heap-size deltas were too noisy — JSC retains block capacity post-collection). Manual end-to-end repro instructions for each platform are in the test file's header comment.

macOS and Windows backends are compile-tested locally; CI runners on those platforms will exercise the install-smoke test.

Adds a Bun-native memory-pressure watcher that, when the OS signals low
memory, runs a sync JSC GC, schedules shrinkFootprintWhenIdle (drops JIT
code at the next safe point), forces mi_collect(true) to return mimalloc
free segments to the OS, and bumps analytics.Features.memory_pressure so
later crash reports carry memory_pressure(N).

Off by default behind BUN_FEATURE_FLAG_EXPERIMENTAL_MEMORY_PRESSURE_HANDLER
so it can be A/B'd before becoming default-on.

Detection:
- Windows: CreateMemoryResourceNotification(LowMemoryResourceNotification)
  waited on via RegisterWaitForSingleObject (NT threadpool, ONLYONCE);
  uv_async_send to the JS thread, 30 s uv_timer holdoff before re-arm.
  Same mechanism upstream WebKit recently adopted for
  MemoryPressureHandlerWin.
- macOS: dispatch_source_create(DISPATCH_SOURCE_TYPE_MEMORYPRESSURE) on a
  global utility queue; handler enqueueTaskConcurrent's the JS thread.
- Linux: PSI trigger on /proc/pressure/memory, blocked on POLLPRI by a
  parked thread that enqueueTaskConcurrent's the JS thread. Gracefully
  no-ops where PSI triggers need CAP_SYS_RESOURCE.

WTF::MemoryPressureHandler was considered but in the JSCOnly build it is
the empty Generic stub on Apple, has no OS hook on Linux, polls every 60 s
on Windows, and releaseMemory() is a no-op without a Bun-supplied
lowMemoryHandler anyway.

Debug-only Bun.unsafe.simulateMemoryPressure() test seam exercises the
JS-thread response path; tests use a WeakRef to assert the sync GC ran.
@robobun

robobun commented May 8, 2026 •

Copy link
Copy Markdown
Collaborator
Updated 10:10 AM PT - May 13th, 2026

❌ @ig-ant, your commit 89a337e has 3 failures in Build #54045 (All Failures):


🧪   To try this PR locally:

bunx bun-pr 30403

That installs a local version of the PR into your bun-30403 executable, so you can run:

bun-30403 --bun

@ig-ant
ig-ant marked this pull request as ready for review May 8, 2026 15:36
@coderabbitai

coderabbitai Bot commented May 8, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review

Walkthrough

Adds an opt-in, process-wide MemoryPressureWatcher that converts OS low-memory signals (Windows/macOS/Linux) into a JS-thread response performing full GC, shrinkFootprint, mimalloc cleanup, and analytics counting; installs on main-thread VMs when enabled by BUN_FEATURE_FLAG_EXPERIMENTAL_MEMORY_PRESSURE_HANDLER.

Changes

Memory Pressure Watcher Implementation

Layer / File(s) Summary
Feature Flag and Data Contracts
src/bun_core/env_var.zig, src/analytics/analytics.zig, src/windows_sys/externs.zig
Adds BUN_FEATURE_FLAG_EXPERIMENTAL_MEMORY_PRESSURE_HANDLER, a memory_pressure analytics counter, and Windows kernel32 externs/types for memory-resource notifications and wait callbacks.
Core Watcher and Platform Backends
src/aio/MemoryPressureWatcher.zig
Implements shared respond() logic (analytics increment, synchronous full GC, shrinkFootprint(), mimalloc cleanup), exported installOnEventLoop()/uninstall()/debug simulate(), a Noop stub, and platform-specific backends: Windows NT threadpool + libuv signaling, macOS dispatch memorypressure source, and Linux PSI /proc/pressure/memory poll thread. All backends enforce a 30s holdoff and include best-effort uninstall cleanup.
VM Lifecycle and Module Export
src/bun.zig, src/jsc/VirtualMachine.zig
Re-exports MemoryPressureWatcher from root module; conditionally installs the watcher on main-thread VirtualMachine init paths and uninstalls it during deinit.
Debug Test Seams
src/runtime/api/UnsafeObject.zig
Registers debug-only Bun.unsafe.simulateMemoryPressure() that invokes the watcher's simulate path and returns the post-simulation analytics counter for deterministic testing; increases object slot capacity for the registration.
Feature Tests and Assertions
test/js/bun/util/memory-pressure.test.ts
Adds debug-only child-process tests using the simulate seam and scoped log assertions to validate GC side-effects, watcher install/uninstall log variants across feature-flag states, and exit-code behavior.
🚥 Pre-merge checks | ✅ 4
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly and concisely summarizes the main change: adding OS memory-pressure signal handling as an opt-in feature.
Description check ✅ Passed The PR description fully addresses both template sections with detailed explanations of functionality, platform-specific implementation, verification steps, and testing approach.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.


Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/aio/MemoryPressureWatcher.zig`:
- Around line 181-197: uninstall() currently schedules async closes for embedded
libuv handles wake and rearm but only wake uses onClosed(), which calls
bun.destroy(s) and can free State while rearm is still pending; change
uninstall() to call libuv.uv_close for both wake and rearm with a close callback
(e.g., onClosed), add an atomic counter or refcount field on State (incremented
before scheduling closes) and decrement it in the close callback, and only call
bun.destroy(s) when the counter reaches zero so State remains valid until both
wake and rearm have finished closing; update onClosed(), uninstall(), State, and
any call sites referencing bun.destroy to use this refcount logic.

In `@src/jsc/VirtualMachine.zig`:
- Line 1317: The MemoryPressureWatcher is only installed in init() but
initWithModuleGraph() can also create a main-thread VM, so add the same
installation call used in init() to initWithModuleGraph(): when you set
vm.is_main_thread = true (or immediately after VM construction there), call
bun.MemoryPressureWatcher.installOnEventLoop(vm) guarded by opts.is_main_thread;
this ensures VMs created by initWithModuleGraph() register the watcher and later
deinit()/uninstall() will properly see it.

In `@test/js/bun/util/memory-pressure.test.ts`:
- Around line 56-60: The WeakRef check is invalid because ref.deref() adds the
target to the kept-objects list for the remainder of the current job; replace
the synchronous post-pressure assertion with an assertion executed in a new task
(e.g., via setTimeout or MessageChannel) so the GC can run outside the current
job. Concretely, keep makeRef() and Bun.unsafe.simulateMemoryPressure(), but
move the aliveAfter check into a macrotask callback (after
simulateMemoryPressure()) and assert ref.deref() === undefined there; reference
symbols: makeRef, ref.deref, and Bun.unsafe.simulateMemoryPressure.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 22ac56b7-eb7f-4b90-9de6-5b0334b0046d

📥 Commits

Reviewing files that changed from the base of the PR and between d5945cf and 0c03cd1.

📒 Files selected for processing (8)
  • src/aio/MemoryPressureWatcher.zig
  • src/analytics/analytics.zig
  • src/bun.zig
  • src/bun_core/env_var.zig
  • src/jsc/VirtualMachine.zig
  • src/runtime/api/UnsafeObject.zig
  • src/windows_sys/externs.zig
  • test/js/bun/util/memory-pressure.test.ts

Comment thread src/aio/MemoryPressureWatcher.zig Resolved
Comment thread src/jsc/VirtualMachine.zig Resolved
Comment thread src/aio/MemoryPressureWatcher.zig Resolved
Comment thread src/aio/MemoryPressureWatcher.zig Resolved
Comment thread src/aio/MemoryPressureWatcher.zig Resolved
Comment thread src/aio/MemoryPressureWatcher.zig Resolved
ig-ant added 2 commits May 8, 2026 15:59
…-GC deref

- Windows.uninstall(): uv_close callbacks fire LIFO within a loop tick, so
  destroying State from wake's close cb while rearm's is still pending was a
  UAF. Count both closes down to zero before bun.destroy.
- initWithModuleGraph (standalone-executable VM init) now installs the
  watcher too, matching the ParentDeathWatchdog hook there.
- WeakRef test: per spec deref() pins the target until end of the current
  synchronous job, so don't deref before the GC — only after.
- Darwin.uninstall(): dispatch_source_cancel() is async and doesn't
  interrupt an in-flight event handler; freeing State right after raced
  with onPressureDispatch on a worker thread. Register a cancel handler
  and release+destroy there — libdispatch guarantees it runs only after
  the last event handler has returned.
- Windows.onWake(): per MSDN even WT_EXECUTEONLYONCE waits must be
  UnregisterWaitEx'd to free the threadpool wait object; nulling s.wait
  and re-arming leaked one registration per 30 s cycle under sustained
  pressure. Unregister (non-blocking) before nulling.
- Windows.onLowMemoryThreadpool(): drop the QueryMemoryResourceNotification
  TOCTOU re-check. If pressure cleared between signal and callback the
  early return permanently disarmed the watcher (only re-arm path is via
  onWake). A false-positive respond() once per 30 s holdoff is harmless.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/aio/MemoryPressureWatcher.zig`:
- Around line 157-163: The onLowMemoryThreadpool callback currently returns
early on spurious wake (when win_externs.QueryMemoryResourceNotification reports
is_low == 0), which consumes the WT_EXECUTEONLYONCE registration and prevents
re-arming; modify onLowMemoryThreadpool so it never returns before routing
through s.wake.send() — i.e., always call s.wake.send() (or re-register the
wait) even when is_low == 0 so the onWake()/onRearm()/arm() re-arm flow still
runs; locate the logic in onLowMemoryThreadpool and ensure the path that handles
is_low == 0 funnels to s.wake.send() rather than an early return.
- Around line 250-255: The uninstall() function currently cancels and
immediately destroys the Darwin state (state/bun.destroy) which races with
in-flight libdispatch handlers like onPressureDispatch(); instead register a
cancellation handler with dispatch_source_set_cancel_handler_f() and move
bun.destroy(s) into that cancel handler so destruction happens only after
libdispatch guarantees no further handlers will run; update uninstall() to set
the cancel handler (capturing s), call dispatch_source_cancel(s.source) and
dispatch_release(s.source) as before but remove the immediate bun.destroy(s) and
state = null until the cancel handler runs, and ensure onPressureDispatch() and
onJSThread() still check state appropriately.

In `@test/js/bun/util/memory-pressure.test.ts`:
- Around line 83-90: The test incorrectly requires "installed" on all non-Linux
platforms; change the assertion to only require "installed" when the runtime
platform actually has a MemoryPressureWatcher.Backend (e.g., isWindows ||
isMacOS || isLinux). Update the else branch that currently checks
expect(debug).toContain("installed") to instead assert that either the backend
is present and "installed" is contained, or for other platforms (FreeBSD/Noop)
assert that the install log is absent (e.g.,
expect(debug).not.toContain("installed")). Refer to the existing platform guards
(isLinux, add isWindows/isMacOS or a combined hasBackend flag) and the
MemoryPressureWatcher.Backend behavior to implement the conditional expectation.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 1959c9be-a193-4d48-a814-6a49ea9728de

📥 Commits

Reviewing files that changed from the base of the PR and between 0c03cd1 and 6003070.

📒 Files selected for processing (3)
  • src/aio/MemoryPressureWatcher.zig
  • src/jsc/VirtualMachine.zig
  • test/js/bun/util/memory-pressure.test.ts

Comment thread src/aio/MemoryPressureWatcher.zig Resolved
Comment thread src/aio/MemoryPressureWatcher.zig Resolved
…ckend

FreeBSD etc. use the Noop backend so there's no install log; the previous
else branch would fail there.
Comment thread src/aio/MemoryPressureWatcher.zig Resolved

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/aio/MemoryPressureWatcher.zig`:
- Around line 352-356: The poll loop contains a dead branch:
std.posix.poll(&fds, -1) with infinite timeout never returns 0, so remove the
unreachable "if (n == 0) continue;" check in the while loop that reads
s.shutdown and calls std.posix.poll; keep the existing EINTR-safe poll usage and
the subsequent checks (s.shutdown.load, n value handling, and fds[0].revents
mask) intact, and run tests to ensure behavior is unchanged.
- Around line 361-367: The current holdoff loop in MemoryPressureWatcher.zig
(using slept += 200 and std.Thread.sleep(200 ms)) can undercount if sleep
returns early; replace the accumulator approach with a deadline-based wait:
compute a deadline using the current monotonic time plus holdoff_ms, then loop
until the deadline is reached or s.shutdown.load(.monotonic) becomes true,
calling std.Thread.sleep for short slices but recomputing the remaining time
from the deadline each iteration so early wakeups don't shorten the effective
holdoff; update references to slept/holdoff_ms and the shutdown check
accordingly in the same block.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: ee8a0e48-d3df-4695-96de-227c73504b01

📥 Commits

Reviewing files that changed from the base of the PR and between 6003070 and 6a83525.

📒 Files selected for processing (1)
  • src/aio/MemoryPressureWatcher.zig

Comment thread src/aio/MemoryPressureWatcher.zig Resolved
Comment thread src/aio/MemoryPressureWatcher.zig Resolved
On Linux, closing an fd from one thread does not wake a poll() already
blocked on it in another — poll holds its own struct file reference via
fdget(), so close() just decrements f_count without reaching release()
or delivering POLLNVAL to the in-flight call. With an infinite timeout
the watcher thread would never observe shutdown, and thread.join() in
uninstall() would hang VM teardown.

Use a 200 ms poll timeout (matches the holdoff sleep slices) so the
shutdown flag is checked periodically, and close the fd after join()
rather than before to avoid an fd-reuse race.
Comment thread src/windows_sys/externs.zig Resolved
Its only call site (the spurious-wake re-check in
Windows.onLowMemoryThreadpool) was removed in 6a83525 when we
switched to always wake.send(). Zig lazy-compiles unreferenced externs
so this was harmless, but it was added for code that's now gone.
…pawns

Per test/CLAUDE.md ("Prefer concurrent tests over sequential tests…").
All three tests spawn isolated bun -e subprocesses with no shared
state, ports, or ordering dependency, so the spawns can overlap.
Comment thread src/aio/MemoryPressureWatcher.zig Resolved
dispatch_source_cancel() is async, so Darwin.uninstall() returns to
VirtualMachine.deinit() while an in-flight onPressureDispatch may still
be running on a libdispatch worker. By the time that handler reaches
s.vm.enqueueTaskConcurrent(), deinit() can have set has_terminated=true,
which is a debug-build panic in EventLoop.enqueueTaskConcurrent.

The cancel-handler fix in 6a83525 protects State's lifetime; this
protects the enqueue. Linux (thread.join) and Windows
(UnregisterWaitEx(.., INVALID_HANDLE_VALUE)) already block until the
off-thread callback drains, so this brings Darwin in line.
@ig-ant
ig-ant force-pushed the claude/memory-pressure-watcher branch from aebead6 to afd33f5 Compare May 13, 2026 04:47

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Additional findings (outside current diff — PR may have been updated during review):

  • 🟡 .claude/worktrees/agent-a9093ef2c1ca7e2ec:1 — This is a stray gitlink (mode 160000 "Subproject commit …") from a local Claude Code worktree that was accidentally staged — it's unrelated to the memory-pressure feature and should be dropped from the PR. Anyone checking out this branch will see git report it as a modified/uninitialized submodule (there's no corresponding .gitmodules entry). git rm --cached .claude/worktrees/agent-a9093ef2c1ca7e2ec and commit; you may also want to add .claude/worktrees/ to .gitignore.

    Extended reasoning...

    What this is

    The PR adds .claude/worktrees/agent-a9093ef2c1ca7e2ec whose entire content is the line Subproject commit 6ca54b3a3070678cd16ff86b6557474fc964df8d. git ls-files -s confirms it is tracked at mode 160000 — i.e., a gitlink (the index entry type git uses for submodules / nested repos), not a regular file. The repo has no .gitmodules, so this is not a declared submodule; it's a dangling pointer to a commit in some other repository.

    The path itself gives away the origin: .claude/worktrees/agent-<hex> is the per-agent worktree scaffolding that Claude Code creates locally. The repo's .gitignore only excludes .claude/settings.local.json and .claude/scheduled_tasks.lock — not .claude/worktrees/ — so a git add . (or git add .claude) during the PR's iteration picked it up. Every other tracked entry under .claude/ is intentional shared content (commands/, hooks/, skills/, settings.json); this is the lone outlier.

    Why it's unrelated to the PR

    The PR is about an OS memory-pressure watcher: all eight other changed files (MemoryPressureWatcher.zig, VirtualMachine.zig, UnsafeObject.zig, env_var.zig, analytics.zig, bun.zig, externs.zig, and the test) are on-topic. A gitlink under .claude/worktrees/ named after an auto-generated agent ID has no connection to any of that — it's developer-environment scaffolding, not source.

    Step-by-step proof

    1. git ls-files -s .claude/worktrees/ → 160000 6ca54b3a… 0 .claude/worktrees/agent-a9093ef2c1ca7e2ec. Mode 160000 = gitlink.
    2. test -f .gitmodules → no .gitmodules exists, so this gitlink has no submodule definition (no URL, no path mapping).
    3. .gitignore greps for .claude → only settings.local.json and scheduled_tasks.lock are ignored; .claude/worktrees/ is not, which is how it slipped into the index.
    4. The referenced commit 6ca54b3a… does not appear anywhere in this PR's history — it points into the agent's local worktree repo, which other contributors cannot fetch.

    Impact

    No runtime/build impact — Zig, the bundler, and the test suite never read this path. The harm is repo hygiene: anyone who checks out this branch will have git status report the path as a modified submodule (since there's no nested .git to satisfy the gitlink), and git submodule status / git clone --recurse-submodules will complain about a gitlink with no .gitmodules entry. It also permanently records an agent-local commit hash in the project history if merged.

    Fix

    git rm --cached .claude/worktrees/agent-a9093ef2c1ca7e2ec
    git commit -m 'remove stray .claude/worktrees gitlink'

    Optionally add .claude/worktrees/ to .gitignore so this can't recur.

Comment thread src/runtime/api/UnsafeObject.zig Resolved
ig-ant added 2 commits May 13, 2026 16:28
…light handler

shutting_down (102ec3b) narrows the teardown race but doesn't close
it: onPressureDispatch can pass shutting_down.load() (false), THEN
uninstall() runs (sets the flag, dispatch_source_cancel(), returns),
THEN VirtualMachine.deinit() reaches has_terminated=true, THEN the
worker reaches enqueueTaskConcurrent — which panics under allow_assert.
dispatch_source_cancel() is async and does not wait for an in-flight
handler.

This commit adds the deterministic test for that property
(Darwin.testUninstallBarrier, exposed as
Bun.unsafe.testMemoryPressureUninstallBarrier, macOS+debug only). It
installs a DISPATCH_SOURCE_TYPE_DATA_ADD source through the SAME
installSource/onPressureDispatch/onCancelled/uninstall path the real
MEMORYPRESSURE source uses, fires it via dispatch_source_merge_data,
parks the libdispatch worker between shutting_down.load() and the
enqueue, runs uninstall(), and snapshots whether the worker had
completed before uninstall() returned. A helper thread releases the
worker only once uninstall() is past dispatch_source_cancel() (via the
after_cancel hook).

On this commit the test FAILS on macOS with {blocked: false} —
uninstall() falls through right after after_cancel.set() while the
worker is still parked. The seam waits on handler_done after capturing
the verdict so its stack-allocated hooks outlive the worker even when
uninstall() didn't block; State cleanup remains in onCancelled. No
timing assertions.

Also: Bun.unsafe createEmptyObject capacity hint → if(isDebug) 5 else 3
now that there are two debug-only properties.

Fix follows in the next commit.
…r drains

Fixes the race demonstrated by testUninstallBarrier() in 3387b58:
add a dispatch_semaphore_t (`drained`) created in installSource(),
signalled by onCancelled() — which libdispatch guarantees runs only
after the last event handler returns — and waited on in uninstall()
right after dispatch_source_cancel(). This gives Darwin the same "no
off-thread enqueue after uninstall() returns" property as Linux's
thread.join() and Windows's UnregisterWaitEx(..., INVALID_HANDLE_VALUE).

release+destroy move from onCancelled() to uninstall() after the wait;
onCancelled() now only signals (and must not touch `s` afterwards —
uninstall() may free it the moment the wait unblocks). shutting_down
remains as a fast-path bail to skip an unnecessary enqueue when the
handler hasn't started yet, but is no longer load-bearing for safety.

testUninstallBarrier() now returns {blocked: true} on macOS.
@ig-ant
ig-ant force-pushed the claude/memory-pressure-watcher branch from afd33f5 to 89a337e Compare May 13, 2026 16:32
Comment on lines +414 to +415
// Drain so `hooks` outlives the worker even when uninstall() didn't
// block (RED). onCancelled then frees `s` once the worker returns.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Nit: the second sentence here ("onCancelled then frees s once the worker returns") is stale after 89a337e — onCancelled (lines 354–357) now only does dispatch_semaphore_signal(s.drained); dispatch_release and bun.destroy(s) were moved into uninstall() itself (lines 346–348) after the semaphore wait. The first sentence is still accurate; just drop or rephrase the second.

Extended reasoning...

What the issue is

The inline comment at lines 414–415 of Darwin.testUninstallBarrier reads:

// Drain so `hooks` outlives the worker even when uninstall() didn't
// block (RED). onCancelled then frees `s` once the worker returns.
hooks.handler_done.wait();

The second sentence describes the previous implementation. In the current code, onCancelled (lines 354–357) is:

fn onCancelled(ctx: ?*anyopaque) callconv(.c) void {
    const s: *State = @ptrCast(@alignCast(ctx.?));
    _ = dispatch_semaphore_signal(s.drained);
}

It does not free s. The dispatch_release(s.drained), dispatch_release(s.source), and bun.destroy(s) calls all live in uninstall() itself (lines 345–348), executed on the JS thread after dispatch_semaphore_wait(s.drained, DISPATCH_TIME_FOREVER) unblocks.

How it became stale

This comment was written for the commit-6a83525 implementation, where onCancelled did:

dispatch_release(s.source);
bun.destroy(s);

and uninstall() returned immediately after dispatch_source_cancel(). Commit 89a337e (the GREEN commit that added the drained semaphore barrier) moved teardown ownership: onCancelled now only signals, and uninstall() blocks on that signal before it releases/destroys. The inline comment in the test seam wasn't updated to match.

Step-by-step proof

  1. testUninstallBarrier calls Darwin.uninstall() at line 412.
  2. uninstall() sets shutting_down, calls dispatch_source_cancel(s.source), sets hooks.after_cancel, then blocks on dispatch_semaphore_wait(s.drained, DISPATCH_TIME_FOREVER) (line 345).
  3. The helper thread observes after_cancel, sets proceed; the parked worker resumes, completes the enqueue, sets handler_done, and returns.
  4. libdispatch runs onCancelled, which only does dispatch_semaphore_signal(s.drained).
  5. uninstall() unblocks and itself executes dispatch_release(s.drained), dispatch_release(s.source), bun.destroy(s) (lines 346–348), then returns to line 412.
  6. By the time control reaches line 416 (hooks.handler_done.wait()), s has already been freed — by uninstall(), not by onCancelled.

So the comment's claim that "onCancelled then frees s" is factually wrong in the current code.

Why it matters (a little)

This is debug-only test instrumentation with zero functional impact, hence a nit. But the comment misrepresents the lifetime ownership of State — exactly the property this whole test seam exists to verify — so a future reader trying to understand the teardown sequence would be misled. The first sentence (about hooks outliving the worker in the RED case) remains correct and is the load-bearing part of the comment.

Fix

Drop or rephrase the second sentence, e.g.:

// Drain so `hooks` outlives the worker even when uninstall() didn't
// block (RED). In GREEN, uninstall() has already destroyed `s` by now.

or simply delete the second sentence — the function-level doc comment (lines 374–388) already covers the lifetime story correctly.

robobun added a commit that referenced this pull request May 19, 2026
Rust port of #30403. Adds a native memory-pressure watcher that, when
the OS signals low memory, runs a sync JSC GC, schedules
shrinkFootprintWhenIdle() (drops JIT code at the next safe point),
forces mi_collect(true) to hand mimalloc free segments back to the OS,
and bumps analytics::features::memory_pressure so any later crash
report carries memory_pressure(N).

Off by default behind BUN_FEATURE_FLAG_EXPERIMENTAL_MEMORY_PRESSURE_HANDLER=1.

Detection:
- Windows: CreateMemoryResourceNotification + RegisterWaitForSingleObject
  (NT threadpool, WT_EXECUTEONLYONCE); uv_async_send to JS thread; 30s
  uv_timer holdoff before re-arm (level-triggered).
- macOS: dispatch_source_create(DISPATCH_SOURCE_TYPE_MEMORYPRESSURE) on a
  global utility queue; enqueue_task_concurrent to JS thread. Cancel
  handler + semaphore barrier so uninstall() blocks until in-flight
  event handlers drain.
- Linux: PSI trigger on /proc/pressure/memory (some 150000 1000000),
  blocked on POLLPRI by a dedicated thread; 30s holdoff. Gracefully
  no-ops where the trigger write fails (no PSI / no CAP_SYS_RESOURCE).

All three converge on respond() running on the JS thread.

Also: add missing <cassert> to wtf-bindings.cpp (unified-build ordering
left assert() undeclared).
robobun added a commit that referenced this pull request May 22, 2026
Rust port of #30403. Adds a native memory-pressure watcher that, when
the OS signals low memory, runs a sync JSC GC, schedules
shrinkFootprintWhenIdle() (drops JIT code at the next safe point),
forces mi_collect(true) to hand mimalloc free segments back to the OS,
and bumps analytics::features::memory_pressure so any later crash
report carries memory_pressure(N).

Off by default behind BUN_FEATURE_FLAG_EXPERIMENTAL_MEMORY_PRESSURE_HANDLER=1.

Detection:
- Windows: CreateMemoryResourceNotification + RegisterWaitForSingleObject
  (NT threadpool, WT_EXECUTEONLYONCE); uv_async_send to JS thread; 30s
  uv_timer holdoff before re-arm (level-triggered).
- macOS: dispatch_source_create(DISPATCH_SOURCE_TYPE_MEMORYPRESSURE) on a
  global utility queue; enqueue_task_concurrent to JS thread. Cancel
  handler + semaphore barrier so uninstall() blocks until in-flight
  event handlers drain.
- Linux: PSI trigger on /proc/pressure/memory (some 150000 1000000),
  blocked on POLLPRI by a dedicated thread; 30s holdoff. Gracefully
  no-ops where the trigger write fails (no PSI / no CAP_SYS_RESOURCE).

All three converge on respond() running on the JS thread.

Also: add missing <cassert> to wtf-bindings.cpp (unified-build ordering
left assert() undeclared).
@ig-ant

ig-ant commented Jun 24, 2026

Copy link
Copy Markdown
Collaborator Author

#32594 covers this

@ig-ant ig-ant closed this Jun 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants