Skip to content

Require the isolate lock for jsg::Rc, jsg::Weak and jsg_cpp::Ref - #8319

Merged
nathanwhit merged 1 commit into
mainfrom
nathanwhit/isolate-lock-handles
Nov 11, 2026
Merged

nathanwhit merged 1 commit into
mainfrom
nathanwhit/isolate-lock-handles

Conversation

@nathanwhit

Copy link
Copy Markdown
Member

Only the isolate lock protects a resource's state: the reference counts of a jsg::Rc and its Wrappable, and the resource's Cells and RefCells. Today nothing enforces that. A jsg::Rc can be dereferenced and cloned without the lock, so a thread that holds one can read the resource or change its counts while another thread holds the lock. That's a data race, which is undefined behavior, and today safe code can cause it.

This PR makes the lock the only way to reach that state.

What changes

  • jsg::Rc loses Deref and Clone. Use get(lock), clone(lock) and downgrade(lock) instead. Weak::upgrade, Weak::clone, Weak::is_alive, to_js and attach_to_this take a Lock too.
  • jsg_cpp::Ref gets the same API, via a new jsg::LockGuarded. Its drop no longer relies on C++'s deferral. Today, two refs to an unwrapped object dropped on two threads race on its count.
  • v8::WrappableRc and the jsg_cpp bridge become private to jsg, since they change counts without the lock.
  • ~IsolateBase now calls the Rust dispose hook just before Dispose() as well as after. C++ objects held by resources are destroyed before Dispose(); a ref kept past teardown is dropped afterwards, which Unbind every Wrappable from its isolate at teardown #8315 makes safe.

Why this is safe

  • The compiler enforces that you hold a lock: Lock is neither Send nor Sync, and every operation except drop takes one.
  • A runtime check, in every build, enforces that it's the right lock. Each operation panics if the lock belongs to another isolate or the Realm is gone. Holding one isolate's lock doesn't exclude anyone from another's, so this check is part of the safety argument, not a debugging aid.
  • GC and detaching visits only change a reference under its own isolate's lock. A GC visit from another isolate leaves the reference alone: it leaks rather than racing.
  • Drops without the lock are queued without touching a count (Release Rust jsg::Rc and jsg::Weak under their isolate's lock #8111).
  • get() ties the &R to the lock's lifetime, so even a leaked Rc can't hand its resource to a 'static future.

As a result, jsg::Rc, jsg::Weak and jsg_cpp::Ref are Send for a Send resource: on a thread without the lock, all you can do with one is drop it. The argument is written up as safety rule 5 in src/rust/jsg/README.md.

Tests

  • Compile tests reject deref, clone, downgrade and upgrade without a lock, and a &R from get() captured in a 'static future. They also check that WrappableRc and the jsg_cpp bridge are private.
  • A compile test accepts a jsg::Rc / jsg::Weak dropped on another thread.
  • jsg-tests:
    • every lock-taking operation panics under another isolate's lock;
    • detaching a reference from another isolate panics, and another isolate's GC leaves it alone;
    • concurrent unlocked drops wait for the lock;
    • teardown destroys a held jsg_cpp::Ref's C++ object before Dispose(), and one kept past teardown can still be dropped.

@nathanwhit
nathanwhit added this pull request to stack #8320 November 9, 2026 22:44
@nathanwhit
nathanwhit requested review from a team as code owners November 9, 2026 22:44
@nathanwhit
nathanwhit requested review from jamesopstad and removed request for a team November 9, 2026 22:44

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Superseded by the review of 215a1af8.

This review, of 38366932

💬 Approved with comments — The lock-gated API, the cross-isolate runtime checks and the teardown ordering look sound and are well tested. The two WARNINGs are stale developer-documentation examples with no runtime impact.

Findings: 2 warnings

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.

🔧 Fix with your agent

Paste the following into your coding agent to investigate and fix these issues.

Fix the following code review issues found in pull request #8319.

Before making changes, review each issue and present a brief summary table:
- For each finding, state whether you agree, disagree, or need clarification
- If you disagree (e.g., the fix would require disproportionate changes
  for minimal ROI, or the finding is factually incorrect), explain why
- If you need to clarify something before deciding, ask those questions
- Then share your plan for which issues to tackle and in what order

## WARNING (2)

### [Documentation] The `watch` example dereferences a `jsg::Rc<Watcher>` (`watcher.targets`), which no longer compiles now that `Rc` has no `Deref`; use `watcher.get(lock).targets.borrow_mut(lock)`.
- **File:** src/rust/jsg-macros/README.md:136

### [Documentation] The review checklist recommends `this.downgrade()`, but `downgrade` now requires the isolate lock; write `this.downgrade(lock)`.
- **File:** docs/reference/rust-review-checklist.md:89

📝 Documentation: ⚠️ 2 warnings

Two documentation files not touched by this pull request still show the removed API

Recommendation: 📝 Minor Comments

  • [WARNING] The watch example dereferences a jsg::Rc<Watcher> (watcher.targets), which no longer compiles now that Rc has no Deref; use watcher.get(lock).targets.borrow_mut(lock). (src/rust/jsg-macros/README.md:136)
  • [WARNING] The review checklist recommends this.downgrade(), but downgrade now requires the isolate lock; write this.downgrade(lock). (docs/reference/rust-review-checklist.md:89)
View full review
  • src/rust/jsg-macros/README.md:136 uses watcher.targets, which relies on jsg::Rc dereferencing to its resource. That no longer compiles; use watcher.get(lock).targets.borrow_mut(lock).
  • docs/reference/rust-review-checklist.md:89 recommends this.downgrade(), but downgrade now takes the lock; write this.downgrade(lock).

✅ All other checks passed

🔒 Security: ✅ LGTM

No issues found:

  • Runtime checks. The cross-isolate check uses assert!, so it also runs in release builds. It rejects a closed state, so a new isolate that reuses the old address cannot pass.
  • Send. The Send impls rest on every operation except drop taking a Lock, which is neither Send nor Sync.
  • Dispose hook. release_while_alive checks the isolate's lock only under the drop-queue mutex and while disposing is false, and ~IsolateBase sets disposing under that same mutex before Dispose(). So V8 is never asked about an isolate that has been disposed.

📖 AGENTS.md: ✅ LGTM

The src/rust/AGENTS.md update matches the new lock-taking API.


📋 Code Quality: ✅ LGTM

No issues found:

  • Lock checks and signatures. The lock-taking signatures on Rc, Weak and jsg_cpp::Ref agree with every updated call site.
  • Privacy compile tests. The tests for WrappableRc and the jsg_cpp bridge match how those items are now declared.
  • Teardown. The dispose stages (DISPOSING before Dispose(), DISPOSED after) are handled exhaustively on both the C++ and the Rust side.
  • Drop paths. Unlocked drops release outside the queue mutex, so a destructor that drops another LockGuarded cannot deadlock.

⚡ Performance: ✅ LGTM

The cost added per access is small: an is_closed() check and a belongs_to comparison. The Arc<IsolateState> is cloned once, when the reference is created.


Reviewed commit: 38366932

@nathanwhit
nathanwhit force-pushed the nathanwhit/isolate-lock-handles branch from 3836693 to 215a1af Compare November 9, 2026 23:02

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Superseded by the review of 1ff42d87.

This review, of 215a1af8

💬 Approved with comments — No correctness, security or performance issues in the lock-gated handles, the cross-isolate checks or the teardown ordering. The two remaining WARNINGs are stale examples in developer documentation that no longer compile, with no runtime impact.

Findings: 2 warnings

Not opened by the correctness review: 1 changed file it was meant to read
  • src/rust/jsg-cpp/ffi.rs

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


📝 Documentation: ❌ Error

This review did not cover the documentation; two stale examples from the last review were re-checked by hand and are still present

Recommendation: ❌ Error

  • [WARNING] The watch example dereferences a jsg::Rc<Watcher> (watcher.targets.borrow_mut(lock)). That no longer compiles because Rc lost Deref; write watcher.get(lock).targets.borrow_mut(lock). (src/rust/jsg-macros/README.md:142)
  • [WARNING] The review checklist recommends this.downgrade(), but downgrade now requires the isolate lock; write this.downgrade(lock). (docs/reference/rust-review-checklist.md:89)
View full review

The documentation review did not complete for this commit, so it did not cover the documentation changes. Both stale examples flagged in the previous review were re-checked at this commit and are still present:

  • src/rust/jsg-macros/README.md:142: the watch example dereferences a jsg::Rc<Watcher> (watcher.targets). That no longer compiles now that Rc has no Deref.
  • docs/reference/rust-review-checklist.md:89 recommends this.downgrade(), but downgrade now takes the lock.

📖 AGENTS.md: ❌ Error

This review did not cover the AGENTS.md changes

Recommendation: ❌ Error

View full review

The AGENTS.md review did not complete for this commit, so this review did not cover the src/rust/AGENTS.md change.


✅ All other checks passed

🔒 Security: ✅ LGTM

  • Send. The Send impls on LockGuarded, Rc and Weak hold up: every operation except drop takes a Lock, which is neither Send nor Sync, and the isolate check uses assert!.
  • Unlocked drops. A drop without the lock queues the value without touching it.
  • Teardown. release_while_alive asks V8 about the isolate's lock only under the drop-queue mutex and while disposing is false. ~IsolateBase sets disposing under that mutex before Dispose(), so V8 is never asked about an isolate that has been disposed.

📋 Code Quality: ✅ LGTM

The changed code agrees with itself:

  • Lock-gated methods. Rc::get, clone, downgrade and attach_to_this, Weak::is_alive, upgrade and clone, and LockGuarded::get all assert the isolate and the closed state with assert!, so the check also runs in release builds.
  • Visits. may_change_in covers the detaching, visiting-isolate and no-isolate cases, and both visit_rc and LockGuarded::get_for_visit go through it.
  • Receiver resolution. resolve_receiver and resolve_method_receiver became free functions so that WrappableRc can be pub(crate). The macro call sites and the privacy compile tests (E0603 for WrappableRc, E0432 for the bridge) match.
  • Teardown. The DISPOSING and DISPOSED stages are handled on both the C++ and the Rust side.

⚡ Performance: ✅ LGTM

Each access adds only an is_closed() check and a belongs_to comparison. A reference clones the Arc<IsolateState> once, when it is created.


Reviewed commit: 215a1af8

@codecov-commenter

codecov-commenter commented Nov 9, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 30.65693% with 95 lines in your changes missing coverage. Please review.
✅ Project coverage is 65.61%. Comparing base (fb5cd9d) to head (5591c49).
⚠️ Report is 100 commits behind head on main.

Files with missing lines Patch % Lines
src/rust/jsg/resource.rs 16.27% 36 Missing ⚠️
src/rust/jsg/v8.rs 25.00% 27 Missing ⚠️
src/rust/jsg/lock_guarded.rs 0.00% 26 Missing ⚠️
src/rust/jsg/isolate_state.rs 54.54% 5 Missing ⚠️
src/rust/jsg/ffi.c++ 91.66% 0 Missing and 1 partial ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main    #8319      +/-   ##
==========================================
+ Coverage   65.47%   65.61%   +0.13%     
==========================================
  Files         759      772      +13     
  Lines      192479   196213    +3734     
  Branches    30355    30808     +453     
==========================================
+ Hits       126022   128737    +2715     
- Misses      48835    49619     +784     
- Partials    17622    17857     +235     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@nathanwhit
nathanwhit force-pushed the nathanwhit/isolate-lock-handles branch from 215a1af to 1ff42d8 Compare November 9, 2026 23:28

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Superseded by the review of 326313ff.

This review, of 1ff42d87

💬 Approved with comments — No correctness, security or performance issues in the lock-gated handles, the cross-isolate checks or the teardown ordering. The two WARNINGs are developer-doc examples that no longer compile, with no runtime impact; the remaining notes are wording.

Findings: 2 warnings · 2 info (2 are inline comments on the diff)

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.

🔧 Fix with your agent

Paste the following into your coding agent to investigate and fix these issues.

Fix the following code review issues found in pull request #8319.

Before making changes, review each issue and present a brief summary table:
- For each finding, state whether you agree, disagree, or need clarification
- If you disagree (e.g., the fix would require disproportionate changes
  for minimal ROI, or the finding is factually incorrect), explain why
- If you need to clarify something before deciding, ask those questions
- Then share your plan for which issues to tackle and in what order

## WARNING (2)

### [Documentation] The `watch` example dereferences a `jsg::Rc<Watcher>` (`watcher.targets.borrow_mut(lock)`). That no longer compiles because `Rc` lost `Deref`; write `watcher.get(lock).targets.borrow_mut(lock)`. (src/rust/jsg-macros/README.md:142)
- **File:** src/rust/jsg-macros/README.md:142

### [Documentation] The review checklist recommends `this.downgrade()`, but `downgrade` now requires the isolate lock; write `this.downgrade(lock)`. (docs/reference/rust-review-checklist.md:89)
- **File:** docs/reference/rust-review-checklist.md:89

## INFO (2)

### [AGENTS.md] "Every other operation but dropping takes a `&Lock`" overlooks the lock-free pointer comparisons, hashing and `Debug` on `Rc`.
- **File:** src/rust/AGENTS.md:44

### [Documentation] Garbled sentence: "such as `jsg_cpp::Ref` its C++ `jsg::Ref`".
- **File:** src/rust/jsg/README.md:360

📝 Documentation: ⚠️ 2 warnings · 1 info

Two developer-doc examples still use APIs that no longer compile, and one sentence in the jsg README is garbled.

Recommendation: 📝 Minor Comments

  • [WARNING] The watch example dereferences a jsg::Rc<Watcher> (watcher.targets.borrow_mut(lock)). That no longer compiles because Rc lost Deref; write watcher.get(lock).targets.borrow_mut(lock). (src/rust/jsg-macros/README.md:142) (src/rust/jsg-macros/README.md:142)
  • [WARNING] The review checklist recommends this.downgrade(), but downgrade now requires the isolate lock; write this.downgrade(lock). (docs/reference/rust-review-checklist.md:89) (docs/reference/rust-review-checklist.md:89)
  • [INFO] Garbled sentence: "such as jsg_cpp::Ref its C++ jsg::Ref". (src/rust/jsg/README.md:360)
View full review
  • src/rust/jsg-macros/README.md:142. The watch example still reads watcher.targets through Deref on jsg::Rc, which this pull request removed.
  • docs/reference/rust-review-checklist.md:89. It still recommends this.downgrade() without the lock.
  • src/rust/jsg/README.md:360-361. The sentence "such as jsg_cpp::Ref its C++ jsg::Ref" is garbled.

📖 AGENTS.md: 💬 1 info

The new lock guidance overstates which operations need the lock.

Recommendation: 💬 Optional Nits

  • [INFO] "Every other operation but dropping takes a &Lock" overlooks the lock-free pointer comparisons, hashing and Debug on Rc. (src/rust/AGENTS.md:44)
View full review

src/rust/AGENTS.md:44 says every operation except dropping takes a &Lock. Rc also has pointer-only PartialEq, Ord and Hash, and a Debug that prints only the type, and none of these need the lock (src/rust/jsg/resource.rs:365-402).


✅ All other checks passed

🔒 Security: ✅ LGTM

  • Bridge privacy. The jsg_cpp bridge is now private, so the cpp_ref_* shims, which change counts without the lock, can't be reached from outside the crate.
  • Owning isolate. from_cpp is always called with the lock in hand, so each new reference belongs to the right isolate.
  • Send. Ref gets Send from LockGuarded, whose Send argument holds: every operation except drop takes a Lock, and the isolate check uses assert!.

📋 Code Quality: ✅ LGTM

  • jsg_cpp::Ref. It wraps jsg::LockGuarded<KjOwn<CppRef>>. get, as_cpp, clone and to_js go through LockGuarded::get, which asserts the isolate in every build. trace uses get_for_visit and track_as_field uses get_for_memory_info.
  • from_cpp. Its callers (call_cpp_for_ref, FromJS::from_js, Ref::clone) each pass a lock of the isolate that owns the reference.
  • Tests. The gc.rs and pending_exception.rs changes are mechanical moves to get(lock), clone(lock) and downgrade(lock), and they keep their assertions.
  • Doc comment. The CppResource doc comment in src/rust/jsg-cpp/ffi.rs has stale wording; see the item.

⚡ Performance: ✅ LGTM

Each access adds only an is_closed() check and an isolate comparison.


Reviewed commit: 1ff42d87

Comment thread src/rust/AGENTS.md Resolved
Comment thread src/rust/jsg/README.md Resolved
@nathanwhit
nathanwhit force-pushed the nathanwhit/isolate-lock-handles branch from 1ff42d8 to 326313f Compare November 10, 2026 01:07

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Superseded by the review of a6e45f22.

This review, of 326313ff

💬 Approved with comments — No correctness, security or performance issues in the lock-gated handles, the cross-isolate checks or the teardown ordering. The two WARNINGs are developer-doc examples that no longer compile, with no runtime impact; the remaining notes are wording.

Findings: 2 warnings · 2 info

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.

🔧 Fix with your agent

Paste the following into your coding agent to investigate and fix these issues.

Fix the following code review issues found in pull request #8319.

Before making changes, review each issue and present a brief summary table:
- For each finding, state whether you agree, disagree, or need clarification
- If you disagree (e.g., the fix would require disproportionate changes
  for minimal ROI, or the finding is factually incorrect), explain why
- If you need to clarify something before deciding, ask those questions
- Then share your plan for which issues to tackle and in what order

## WARNING (2)

### [Documentation] The `watch` example dereferences a `jsg::Rc<Watcher>` (`watcher.targets.borrow_mut(lock)`). That no longer compiles because `Rc` lost `Deref`; write `watcher.get(lock).targets.borrow_mut(lock)`. (src/rust/jsg-macros/README.md:142)
- **File:** src/rust/jsg-macros/README.md:142

### [Documentation] The review checklist recommends `this.downgrade()`, but `downgrade` now requires the isolate lock; write `this.downgrade(lock)`. (docs/reference/rust-review-checklist.md:89)
- **File:** docs/reference/rust-review-checklist.md:89

## INFO (2)

### [AGENTS.md] "Every other operation but dropping takes a `&Lock`" overlooks the lock-free pointer comparisons, hashing and `Debug` on `Rc`.
- **File:** src/rust/AGENTS.md:44

### [Documentation] Garbled sentence: "such as `jsg_cpp::Ref` its C++ `jsg::Ref`".
- **File:** src/rust/jsg/README.md:360

📝 Documentation: ⚠️ 2 warnings · 1 info

Two developer-doc examples still use APIs that no longer compile, and one sentence in the jsg README is garbled.

Recommendation: 📝 Minor Comments

  • [WARNING] The watch example dereferences a jsg::Rc<Watcher> (watcher.targets.borrow_mut(lock)). That no longer compiles because Rc lost Deref; write watcher.get(lock).targets.borrow_mut(lock). (src/rust/jsg-macros/README.md:142) (src/rust/jsg-macros/README.md:142)
  • [WARNING] The review checklist recommends this.downgrade(), but downgrade now requires the isolate lock; write this.downgrade(lock). (docs/reference/rust-review-checklist.md:89) (docs/reference/rust-review-checklist.md:89)
  • [INFO] Garbled sentence: "such as jsg_cpp::Ref its C++ jsg::Ref". (src/rust/jsg/README.md:360)
View full review
  • src/rust/jsg-macros/README.md:142. The watch example still reads watcher.targets through Deref on jsg::Rc, which this pull request removed.
  • docs/reference/rust-review-checklist.md:89. It still recommends this.downgrade() without the lock.
  • src/rust/jsg/README.md:360-361. The sentence "such as jsg_cpp::Ref its C++ jsg::Ref" is garbled.

📖 AGENTS.md: 💬 1 info

The new lock guidance overstates which operations need the lock.

Recommendation: 💬 Optional Nits

  • [INFO] "Every other operation but dropping takes a &Lock" overlooks the lock-free pointer comparisons, hashing and Debug on Rc. (src/rust/AGENTS.md:44)
View full review

src/rust/AGENTS.md:44 says every operation except dropping takes a &Lock. Rc also has pointer-only PartialEq, Ord and Hash, and a Debug that prints only the type, and none of these need the lock (src/rust/jsg/resource.rs:365-402).


✅ All other checks passed

🔒 Security: ✅ LGTM

  • Bridge privacy. The jsg_cpp bridge is now private, so the cpp_ref_* shims, which change counts without the lock, can't be reached from outside the crate.
  • Owning isolate. from_cpp is always called with the lock in hand, so each new reference belongs to the right isolate.
  • Send. Ref gets Send from LockGuarded, whose Send argument holds: every operation except drop takes a Lock, and the isolate check uses assert!.

📋 Code Quality: ✅ LGTM

  • jsg_cpp::Ref. It wraps jsg::LockGuarded<KjOwn<CppRef>>. get, as_cpp, clone and to_js go through LockGuarded::get, which asserts the isolate in every build. trace uses get_for_visit and track_as_field uses get_for_memory_info.
  • from_cpp. Its callers (call_cpp_for_ref, FromJS::from_js, Ref::clone) each pass a lock of the isolate that owns the reference.
  • Tests. The gc.rs and pending_exception.rs changes are mechanical moves to get(lock), clone(lock) and downgrade(lock), and they keep their assertions.
  • Doc comment. The CppResource doc comment in src/rust/jsg-cpp/ffi.rs has stale wording; see the item.

⚡ Performance: ✅ LGTM

Each access adds only an is_closed() check and an isolate comparison.


Reviewed commit: 326313ff — same changes as 1ff42d87, so this is that commit's review (no new review was run; line numbers are as of 1ff42d87)

@nathanwhit
nathanwhit force-pushed the nathanwhit/isolate-lock-handles branch from 326313f to a6e45f2 Compare November 10, 2026 01:09

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Superseded by the review of 9e00aee2.

This review, of a6e45f22

💬 Approved with comments — No correctness, security or performance issues in the lock-gated handles, the cross-isolate checks or the teardown ordering. The two WARNINGs are developer-doc examples that no longer compile, with no runtime impact; the remaining notes are wording.

Findings: 2 warnings · 2 info

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.

🔧 Fix with your agent

Paste the following into your coding agent to investigate and fix these issues.

Fix the following code review issues found in pull request #8319.

Before making changes, review each issue and present a brief summary table:
- For each finding, state whether you agree, disagree, or need clarification
- If you disagree (e.g., the fix would require disproportionate changes
  for minimal ROI, or the finding is factually incorrect), explain why
- If you need to clarify something before deciding, ask those questions
- Then share your plan for which issues to tackle and in what order

## WARNING (2)

### [Documentation] The `watch` example dereferences a `jsg::Rc<Watcher>` (`watcher.targets.borrow_mut(lock)`). That no longer compiles because `Rc` lost `Deref`; write `watcher.get(lock).targets.borrow_mut(lock)`. (src/rust/jsg-macros/README.md:142)
- **File:** src/rust/jsg-macros/README.md:142

### [Documentation] The review checklist recommends `this.downgrade()`, but `downgrade` now requires the isolate lock; write `this.downgrade(lock)`. (docs/reference/rust-review-checklist.md:89)
- **File:** docs/reference/rust-review-checklist.md:89

## INFO (2)

### [AGENTS.md] "Every other operation but dropping takes a `&Lock`" overlooks the lock-free pointer comparisons, hashing and `Debug` on `Rc`.
- **File:** src/rust/AGENTS.md:44

### [Documentation] Garbled sentence: "such as `jsg_cpp::Ref` its C++ `jsg::Ref`".
- **File:** src/rust/jsg/README.md:360

📝 Documentation: ⚠️ 2 warnings · 1 info

Two developer-doc examples still use APIs that no longer compile, and one sentence in the jsg README is garbled.

Recommendation: 📝 Minor Comments

  • [WARNING] The watch example dereferences a jsg::Rc<Watcher> (watcher.targets.borrow_mut(lock)). That no longer compiles because Rc lost Deref; write watcher.get(lock).targets.borrow_mut(lock). (src/rust/jsg-macros/README.md:142) (src/rust/jsg-macros/README.md:142)
  • [WARNING] The review checklist recommends this.downgrade(), but downgrade now requires the isolate lock; write this.downgrade(lock). (docs/reference/rust-review-checklist.md:89) (docs/reference/rust-review-checklist.md:89)
  • [INFO] Garbled sentence: "such as jsg_cpp::Ref its C++ jsg::Ref". (src/rust/jsg/README.md:360)
View full review
  • src/rust/jsg-macros/README.md:142. The watch example still reads watcher.targets through Deref on jsg::Rc, which this pull request removed.
  • docs/reference/rust-review-checklist.md:89. It still recommends this.downgrade() without the lock.
  • src/rust/jsg/README.md:360-361. The sentence "such as jsg_cpp::Ref its C++ jsg::Ref" is garbled.

📖 AGENTS.md: 💬 1 info

The new lock guidance overstates which operations need the lock.

Recommendation: 💬 Optional Nits

  • [INFO] "Every other operation but dropping takes a &Lock" overlooks the lock-free pointer comparisons, hashing and Debug on Rc. (src/rust/AGENTS.md:44)
View full review

src/rust/AGENTS.md:44 says every operation except dropping takes a &Lock. Rc also has pointer-only PartialEq, Ord and Hash, and a Debug that prints only the type, and none of these need the lock (src/rust/jsg/resource.rs:365-402).


✅ All other checks passed

🔒 Security: ✅ LGTM

  • Bridge privacy. The jsg_cpp bridge is now private, so the cpp_ref_* shims, which change counts without the lock, can't be reached from outside the crate.
  • Owning isolate. from_cpp is always called with the lock in hand, so each new reference belongs to the right isolate.
  • Send. Ref gets Send from LockGuarded, whose Send argument holds: every operation except drop takes a Lock, and the isolate check uses assert!.

📋 Code Quality: ✅ LGTM

  • jsg_cpp::Ref. It wraps jsg::LockGuarded<KjOwn<CppRef>>. get, as_cpp, clone and to_js go through LockGuarded::get, which asserts the isolate in every build. trace uses get_for_visit and track_as_field uses get_for_memory_info.
  • from_cpp. Its callers (call_cpp_for_ref, FromJS::from_js, Ref::clone) each pass a lock of the isolate that owns the reference.
  • Tests. The gc.rs and pending_exception.rs changes are mechanical moves to get(lock), clone(lock) and downgrade(lock), and they keep their assertions.
  • Doc comment. The CppResource doc comment in src/rust/jsg-cpp/ffi.rs has stale wording; see the item.

⚡ Performance: ✅ LGTM

Each access adds only an is_closed() check and an isolate comparison.


Reviewed commit: a6e45f22 — same changes as 1ff42d87, so this is that commit's review (no new review was run; line numbers are as of 1ff42d87)

@nathanwhit
nathanwhit force-pushed the nathanwhit/isolate-lock-handles branch from a6e45f2 to 9e00aee Compare November 10, 2026 01:31

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Superseded by the review of 1a2b456d.

This review, of 9e00aee2

💬 Approved with comments — No correctness, security or performance issues in the lock-gated handles, the cross-isolate checks or the teardown ordering. The two WARNINGs are developer-doc examples that no longer compile, with no runtime impact; the remaining notes are wording.

Findings: 2 warnings · 2 info

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.

🔧 Fix with your agent

Paste the following into your coding agent to investigate and fix these issues.

Fix the following code review issues found in pull request #8319.

Before making changes, review each issue and present a brief summary table:
- For each finding, state whether you agree, disagree, or need clarification
- If you disagree (e.g., the fix would require disproportionate changes
  for minimal ROI, or the finding is factually incorrect), explain why
- If you need to clarify something before deciding, ask those questions
- Then share your plan for which issues to tackle and in what order

## WARNING (2)

### [Documentation] The `watch` example dereferences a `jsg::Rc<Watcher>` (`watcher.targets.borrow_mut(lock)`). That no longer compiles because `Rc` lost `Deref`; write `watcher.get(lock).targets.borrow_mut(lock)`. (src/rust/jsg-macros/README.md:142)
- **File:** src/rust/jsg-macros/README.md:142

### [Documentation] The review checklist recommends `this.downgrade()`, but `downgrade` now requires the isolate lock; write `this.downgrade(lock)`. (docs/reference/rust-review-checklist.md:89)
- **File:** docs/reference/rust-review-checklist.md:89

## INFO (2)

### [AGENTS.md] "Every other operation but dropping takes a `&Lock`" overlooks the lock-free pointer comparisons, hashing and `Debug` on `Rc`.
- **File:** src/rust/AGENTS.md:44

### [Documentation] Garbled sentence: "such as `jsg_cpp::Ref` its C++ `jsg::Ref`".
- **File:** src/rust/jsg/README.md:360

📝 Documentation: ⚠️ 2 warnings · 1 info

Two developer-doc examples still use APIs that no longer compile, and one sentence in the jsg README is garbled.

Recommendation: 📝 Minor Comments

  • [WARNING] The watch example dereferences a jsg::Rc<Watcher> (watcher.targets.borrow_mut(lock)). That no longer compiles because Rc lost Deref; write watcher.get(lock).targets.borrow_mut(lock). (src/rust/jsg-macros/README.md:142) (src/rust/jsg-macros/README.md:142)
  • [WARNING] The review checklist recommends this.downgrade(), but downgrade now requires the isolate lock; write this.downgrade(lock). (docs/reference/rust-review-checklist.md:89) (docs/reference/rust-review-checklist.md:89)
  • [INFO] Garbled sentence: "such as jsg_cpp::Ref its C++ jsg::Ref". (src/rust/jsg/README.md:360)
View full review
  • src/rust/jsg-macros/README.md:142. The watch example still reads watcher.targets through Deref on jsg::Rc, which this pull request removed.
  • docs/reference/rust-review-checklist.md:89. It still recommends this.downgrade() without the lock.
  • src/rust/jsg/README.md:360-361. The sentence "such as jsg_cpp::Ref its C++ jsg::Ref" is garbled.

📖 AGENTS.md: 💬 1 info

The new lock guidance overstates which operations need the lock.

Recommendation: 💬 Optional Nits

  • [INFO] "Every other operation but dropping takes a &Lock" overlooks the lock-free pointer comparisons, hashing and Debug on Rc. (src/rust/AGENTS.md:44)
View full review

src/rust/AGENTS.md:44 says every operation except dropping takes a &Lock. Rc also has pointer-only PartialEq, Ord and Hash, and a Debug that prints only the type, and none of these need the lock (src/rust/jsg/resource.rs:365-402).


✅ All other checks passed

🔒 Security: ✅ LGTM

  • Bridge privacy. The jsg_cpp bridge is now private, so the cpp_ref_* shims, which change counts without the lock, can't be reached from outside the crate.
  • Owning isolate. from_cpp is always called with the lock in hand, so each new reference belongs to the right isolate.
  • Send. Ref gets Send from LockGuarded, whose Send argument holds: every operation except drop takes a Lock, and the isolate check uses assert!.

📋 Code Quality: ✅ LGTM

  • jsg_cpp::Ref. It wraps jsg::LockGuarded<KjOwn<CppRef>>. get, as_cpp, clone and to_js go through LockGuarded::get, which asserts the isolate in every build. trace uses get_for_visit and track_as_field uses get_for_memory_info.
  • from_cpp. Its callers (call_cpp_for_ref, FromJS::from_js, Ref::clone) each pass a lock of the isolate that owns the reference.
  • Tests. The gc.rs and pending_exception.rs changes are mechanical moves to get(lock), clone(lock) and downgrade(lock), and they keep their assertions.
  • Doc comment. The CppResource doc comment in src/rust/jsg-cpp/ffi.rs has stale wording; see the item.

⚡ Performance: ✅ LGTM

Each access adds only an is_closed() check and an isolate comparison.


Reviewed commit: 9e00aee2 — same changes as 1ff42d87, so this is that commit's review (no new review was run; line numbers are as of 1ff42d87)

@guybedford guybedford left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

The lock-as-token design looks right to me. One teardown ordering issue below, where a jsg_cpp::Ref held through a nested jsg::Rc still has its C++ object destroyed after Dispose().

Comment thread src/rust/jsg/resource.rs Resolved
@nathanwhit
nathanwhit force-pushed the nathanwhit/isolate-lock-handles branch from 9e00aee to 1a2b456 Compare November 10, 2026 18:01

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Superseded by the review of f7a5ab07.

This review, of 1a2b456d

💬 Approved with comments — No correctness, security or performance issues in the lock-gated handles, the cross-isolate checks or the teardown ordering. The two WARNINGs are developer-doc examples that no longer compile, with no runtime impact; the remaining notes are wording.

Findings: 2 warnings · 2 info

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.

🔧 Fix with your agent

Paste the following into your coding agent to investigate and fix these issues.

Fix the following code review issues found in pull request #8319.

Before making changes, review each issue and present a brief summary table:
- For each finding, state whether you agree, disagree, or need clarification
- If you disagree (e.g., the fix would require disproportionate changes
  for minimal ROI, or the finding is factually incorrect), explain why
- If you need to clarify something before deciding, ask those questions
- Then share your plan for which issues to tackle and in what order

## WARNING (2)

### [Documentation] The `watch` example dereferences a `jsg::Rc<Watcher>` (`watcher.targets.borrow_mut(lock)`). That no longer compiles because `Rc` lost `Deref`; write `watcher.get(lock).targets.borrow_mut(lock)`. (src/rust/jsg-macros/README.md:142)
- **File:** src/rust/jsg-macros/README.md:142

### [Documentation] The review checklist recommends `this.downgrade()`, but `downgrade` now requires the isolate lock; write `this.downgrade(lock)`. (docs/reference/rust-review-checklist.md:89)
- **File:** docs/reference/rust-review-checklist.md:89

## INFO (2)

### [AGENTS.md] "Every other operation but dropping takes a `&Lock`" overlooks the lock-free pointer comparisons, hashing and `Debug` on `Rc`.
- **File:** src/rust/AGENTS.md:44

### [Documentation] Garbled sentence: "such as `jsg_cpp::Ref` its C++ `jsg::Ref`".
- **File:** src/rust/jsg/README.md:360

📝 Documentation: ⚠️ 2 warnings · 1 info

Two developer-doc examples still use APIs that no longer compile, and one sentence in the jsg README is garbled.

Recommendation: 📝 Minor Comments

  • [WARNING] The watch example dereferences a jsg::Rc<Watcher> (watcher.targets.borrow_mut(lock)). That no longer compiles because Rc lost Deref; write watcher.get(lock).targets.borrow_mut(lock). (src/rust/jsg-macros/README.md:142) (src/rust/jsg-macros/README.md:142)
  • [WARNING] The review checklist recommends this.downgrade(), but downgrade now requires the isolate lock; write this.downgrade(lock). (docs/reference/rust-review-checklist.md:89) (docs/reference/rust-review-checklist.md:89)
  • [INFO] Garbled sentence: "such as jsg_cpp::Ref its C++ jsg::Ref". (src/rust/jsg/README.md:360)
View full review
  • src/rust/jsg-macros/README.md:142. The watch example still reads watcher.targets through Deref on jsg::Rc, which this pull request removed.
  • docs/reference/rust-review-checklist.md:89. It still recommends this.downgrade() without the lock.
  • src/rust/jsg/README.md:360-361. The sentence "such as jsg_cpp::Ref its C++ jsg::Ref" is garbled.

📖 AGENTS.md: 💬 1 info

The new lock guidance overstates which operations need the lock.

Recommendation: 💬 Optional Nits

  • [INFO] "Every other operation but dropping takes a &Lock" overlooks the lock-free pointer comparisons, hashing and Debug on Rc. (src/rust/AGENTS.md:44)
View full review

src/rust/AGENTS.md:44 says every operation except dropping takes a &Lock. Rc also has pointer-only PartialEq, Ord and Hash, and a Debug that prints only the type, and none of these need the lock (src/rust/jsg/resource.rs:365-402).


✅ All other checks passed

🔒 Security: ✅ LGTM

  • Bridge privacy. The jsg_cpp bridge is now private, so the cpp_ref_* shims, which change counts without the lock, can't be reached from outside the crate.
  • Owning isolate. from_cpp is always called with the lock in hand, so each new reference belongs to the right isolate.
  • Send. Ref gets Send from LockGuarded, whose Send argument holds: every operation except drop takes a Lock, and the isolate check uses assert!.

📋 Code Quality: ✅ LGTM

  • jsg_cpp::Ref. It wraps jsg::LockGuarded<KjOwn<CppRef>>. get, as_cpp, clone and to_js go through LockGuarded::get, which asserts the isolate in every build. trace uses get_for_visit and track_as_field uses get_for_memory_info.
  • from_cpp. Its callers (call_cpp_for_ref, FromJS::from_js, Ref::clone) each pass a lock of the isolate that owns the reference.
  • Tests. The gc.rs and pending_exception.rs changes are mechanical moves to get(lock), clone(lock) and downgrade(lock), and they keep their assertions.
  • Doc comment. The CppResource doc comment in src/rust/jsg-cpp/ffi.rs has stale wording; see the item.

⚡ Performance: ✅ LGTM

Each access adds only an is_closed() check and an isolate comparison.


Reviewed commit: 1a2b456d — same changes as 1ff42d87, so this is that commit's review (no new review was run; line numbers are as of 1ff42d87)

@nathanwhit
nathanwhit force-pushed the nathanwhit/isolate-lock-handles branch from 1a2b456 to f7a5ab0 Compare November 10, 2026 22:04

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Superseded by the review of 593054aa.

This review, of f7a5ab07

💬 Approved with comments — No correctness, security or performance problems in the lock-gated handles, the isolate checks or the two-stage dispose hook. The earlier doc WARNINGs are fixed, and two INFO doc notes remain.

Findings: 2 info (2 are inline comments on the diff)

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


📋 Code Quality: 💬 1 info

No correctness problems. One doc-comment note in jsg-cpp/ffi.rs is still open.

Recommendation: 💬 Optional Nits

  • [INFO] CppResource doc comment has an over-long unwrapped line and still says Ref<Self> "dereferences" the object (ffi.rs:87, also lines 7 and 11). (src/rust/jsg-cpp/ffi.rs:70)
View full review

Checked, no problems found

  • jsg_cpp::Ref wraps LockGuarded<KjOwn<CppRef>>, so get, as_cpp, clone and to_js all assert the isolate.
  • trace and track_as_field use visit and memory-info accessors that skip a foreign isolate.
  • The bridge is private, and the compile tests check that.
  • The teardown path handles a Ref reached through a nested jsg::Rc correctly (see the summary above).
  • The test changes are mechanical and keep their assertions.

Open note

  • The CppResource doc comment in src/rust/jsg-cpp/ffi.rs has a line that wasn't re-wrapped.
  • It still says Ref<Self> "dereferences" the object (lines 7, 11 and 87), but Ref no longer implements Deref.

📝 Documentation: 💬 1 info

Earlier doc issues are fixed. One overstated claim about which operations need the lock remains.

Recommendation: 💬 Optional Nits

  • [INFO] "Every other operation but dropping takes a Lock" overlooks the lock-free equality, ordering, hashing and Debug on Rc. (src/rust/jsg/README.md:72)
View full review
  • The watch example, the checklist's downgrade(lock) and the garbled README sentence are all fixed.
  • src/rust/jsg/README.md:72 and the Rc doc in src/rust/jsg/resource.rs say dropping is the only operation that needs no lock. That conflicts with the README's own later statement that equality, ordering, hashing and Debug don't need the lock either.

✅ All other checks passed

🔒 Security: ✅ LGTM

  • Isolate check. Every lock-taking operation asserts, in every build, that the lock belongs to the handle's isolate and that the isolate's state isn't closed. The closed check stops a new isolate at a reused address from passing the comparison.
  • Visits. may_change_in leaves another isolate's handles alone during GC and panics on a foreign detach.
  • Send. The Send impls hold: every operation except drop needs a Lock, which is neither Send nor Sync.
  • Dispose hook. this_thread_holds_lock_until_disposing and isolate_disposing take the same mutex, so the isolate isn't used after Dispose() begins.

📖 AGENTS.md: ✅ LGTM

The src/rust/AGENTS.md wording about lock-free operations is now accurate.


⚡ Performance: ✅ LGTM

Each access adds only an is_closed() check and an isolate comparison.


Reviewed commit: f7a5ab07

Comment thread src/rust/jsg-cpp/ffi.rs Resolved
Comment thread src/rust/jsg/README.md Resolved
@nathanwhit
nathanwhit force-pushed the nathanwhit/isolate-lock-handles branch from f7a5ab0 to 593054a Compare November 10, 2026 22:26

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Superseded by the review of aba1fff6.

This review, of 593054aa

💬 Approved with comments — No correctness, security or performance problems in the lock-gated handles, the isolate checks or the dispose ordering. One INFO doc note remains on which Rc operations need no lock.

Findings: 1 info

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


📝 Documentation: 💬 1 info

The Rc docs say dropping is the only operation that needs no lock.

Recommendation: 💬 Optional Nits

  • [INFO] "Every other operation but dropping takes a Lock" leaves out equality, ordering, hashing and Debug on Rc, which need no lock. (src/rust/jsg/README.md:72)
View full review

src/rust/jsg/README.md:72 and the Rc doc comment in src/rust/jsg/resource.rs say every operation except dropping takes a Lock. Equality, ordering, hashing and Debug need no lock either, which the README and the Send safety comment both say later.


✅ All other checks passed

🔒 Security: ✅ LGTM

  • Isolate check: every lock-taking operation checks, in every build, that the lock belongs to the handle's isolate and that the state isn't closed.
  • Visits: a GC visit leaves another isolate's handles alone, and a foreign detach panics.
  • Send: the impls hold, because every operation except drop needs a Lock, which is neither Send nor Sync.
  • Bridge: making it private removes the way to change counts without the lock.

📖 AGENTS.md: ✅ LGTM

The src/rust/AGENTS.md wording about lock-free operations is accurate.


📋 Code Quality: ✅ LGTM

  • jsg_cpp::Ref: get, as_cpp, clone and to_js all go through the isolate-checked LockGuarded accessor. trace and track_as_field skip a foreign isolate.
  • Bridge and WrappableRc: both are private now, and the compile tests check that.
  • Macros: they use the new receiver functions and pass the lock to attach_to_this.
  • Teardown: a Ref reached through a nested jsg::Rc is destroyed before Dispose(), and a test covers that case.
  • Test updates: they are mechanical and keep their assertions.

⚡ Performance: ✅ LGTM

Each handle access adds only an is_closed() check and an isolate pointer comparison.


Reviewed commit: 593054aa

Base automatically changed from nathanwhit/unbind-wrappable-teardown to main November 10, 2026 22:57
@nathanwhit
nathanwhit force-pushed the nathanwhit/isolate-lock-handles branch from 593054a to aba1fff Compare November 10, 2026 22:57

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Superseded by the review of ae53465f.

This review, of aba1fff6

💬 Approved with comments — No correctness, security or performance problems in the lock-gated handles, the isolate checks or the dispose ordering. One INFO doc note remains on which Rc operations need no lock.

Findings: 1 info

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


📝 Documentation: 💬 1 info

The Rc docs say dropping is the only operation that needs no lock.

Recommendation: 💬 Optional Nits

  • [INFO] "Every other operation but dropping takes a Lock" leaves out equality, ordering, hashing and Debug on Rc, which need no lock. (src/rust/jsg/README.md:72)
View full review

src/rust/jsg/README.md:72 and the Rc doc comment in src/rust/jsg/resource.rs say every operation except dropping takes a Lock. Equality, ordering, hashing and Debug need no lock either, which the README and the Send safety comment both say later.


✅ All other checks passed

🔒 Security: ✅ LGTM

  • Isolate check: every lock-taking operation checks, in every build, that the lock belongs to the handle's isolate and that the state isn't closed.
  • Visits: a GC visit leaves another isolate's handles alone, and a foreign detach panics.
  • Send: the impls hold, because every operation except drop needs a Lock, which is neither Send nor Sync.
  • Bridge: making it private removes the way to change counts without the lock.

📖 AGENTS.md: ✅ LGTM

The src/rust/AGENTS.md wording about lock-free operations is accurate.


📋 Code Quality: ✅ LGTM

  • jsg_cpp::Ref: get, as_cpp, clone and to_js all go through the isolate-checked LockGuarded accessor. trace and track_as_field skip a foreign isolate.
  • Bridge and WrappableRc: both are private now, and the compile tests check that.
  • Macros: they use the new receiver functions and pass the lock to attach_to_this.
  • Teardown: a Ref reached through a nested jsg::Rc is destroyed before Dispose(), and a test covers that case.
  • Test updates: they are mechanical and keep their assertions.

⚡ Performance: ✅ LGTM

Each handle access adds only an is_closed() check and an isolate pointer comparison.


Reviewed commit: aba1fff6 — same changes as 593054aa, so this is that commit's review (no new review was run; line numbers are as of 593054aa)

@nathanwhit
nathanwhit force-pushed the nathanwhit/isolate-lock-handles branch from aba1fff to ae53465 Compare November 10, 2026 23:10

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Superseded by the review of 5591c492.

This review, of ae53465f

💬 Approved with comments — No correctness, security or performance problems in the lock-gated Rc/Weak/Ref API or the teardown change. The earlier doc note is fixed, and one optional INFO test cleanup remains.

Findings: 1 info (1 is an inline comment on the diff)

Not opened by the correctness review: 1 changed file it was meant to read
  • src/rust/jsg-cpp/ffi.rs

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


📋 Code Quality: 💬 1 info

The Ref API, the private bridge, the macros and the teardown follow-up are correct. One optional test cleanup.

Recommendation: 💬 Optional Nits

  • [INFO] ToAnotherThread in gc.rs is now a redundant unsafe impl Send wrapper, because jsg::Rc and jsg::Weak are Send for a Send resource. (src/rust/jsg-test/tests/gc.rs:1564)
View full review
  • jsg_cpp::Ref: get, as_cpp, clone and to_js all go through the isolate-checked LockGuarded::get. trace and track_as_field skip another isolate through get_for_visit and get_for_memory_info. from_cpp now takes the lock, and both of its callers pass it.
  • Bridge and WrappableRc: both are private, and the compile tests check that.
  • Teardown: Rc and Weak drops now use the lock-aware release() path, so a Ref held through a nested jsg::Rc is destroyed before Dispose(). The old deferral test was flipped to match.
  • Test updates: they are mechanical and keep their assertions.

One optional cleanup: the ToAnotherThread wrapper in gc.rs is now redundant (see inline).


✅ All other checks passed

🔒 Security: ✅ LGTM

  • Isolate checks: every lock-taking operation checks, in every build, that the lock belongs to the handle's isolate and that the state is not closed.
  • Dispose ordering: this_thread_holds_lock_until_disposing reads disposing while holding the queue mutex, so the isolate pointer is not used once Dispose() has started.
  • Send impls: they hold, because every operation except drop needs a Lock, which is neither Send nor Sync.
  • Bridge: making it private removes the way to change counts without the lock.

📖 AGENTS.md: ✅ LGTM

The src/rust/AGENTS.md updates match the new lock-taking API.


⚡ Performance: ✅ LGTM

Each handle access adds only an is_closed() check and an isolate pointer comparison. Drops without the lock are still queued without touching a count.


📝 Documentation: ✅ LGTM

The earlier note is fixed. The README Rc section and the Rc doc comment now say that dropping, equality, ordering, hashing and Debug need no lock.


Reviewed commit: ae53465f

Comment thread src/rust/jsg-test/tests/gc.rs Resolved
Rust JSG shares state with no synchronization of its own: the reference counts of a jsg::Rc and
its Wrappable, and the Cells and RefCells of resources. Only the isolate lock keeps two threads
from using that state at once, which would be a data race. Today a jsg::Rc can be dereferenced
and cloned without the lock, so a thread that holds one but not the lock can read the resource or
change its counts while the lock's holder does. This change makes every reference reach that
state only under its isolate's lock.

- jsg::Rc and jsg::Weak touch their counts and their resource only under the lock of the
  resource's isolate, which makes them Send, for R: Send:
  - Rc loses Deref and Clone for get(lock), clone(lock) and downgrade(lock), and Weak::upgrade,
    Weak::clone, Weak::is_alive and Rc::attach_to_this take a Lock too. Each asserts, in every
    build, that the lock is of the resource's isolate and that its Realm is alive: holding one
    isolate's lock excludes no thread from another's. Lock is neither Send nor Sync. get()
    bounds the &R by the lock's brand 's, so even a leaked Rc can't lend its resource to a
    'static future.
  - GC and detaching visits change a jsg::Rc only under its isolate's lock. A detaching visit
    (jsg::Cell::take, say) under another isolate's lock panics; a GC visit on behalf of another
    isolate leaves it as it is, so a reference that one isolate's resource holds to another's
    leaks rather than racing, as TracedGlobal's visit already does. Debug builds assert against
    such a visit.
  - A drop without the lock is queued without touching a count (#8111). A drop under the lock
    releases at once, now also while the isolate is torn down, until it is about to be
    disposed: a jsg::Rc that teardown dropped used to be kept until after Dispose, and with it
    any resource reachable only through it.
  - Weak loses its unused GarbageCollected impl, whose memory_name upgraded it without a lock.
- jsg_cpp::Ref gets the same treatment through a new jsg::LockGuarded<T>: a value that only its
  isolate's lock guards, which it lends only under that lock (get, and get_for_visit for GC and
  detaching visits, which follow jsg::Rc's rules) and drops as a jsg::Rc drops its parts. Its
  constructor is unsafe: the value must be bound to no thread but through the lock. Ref's Deref
  becomes get(lock) and its Clone clone(lock), and to_js and as_cpp check the lock too. A heap
  snapshot reports it through LockGuarded::get_for_memory_info, which, as for a jsg::Rc, lends
  the value only to a snapshot of its own isolate, which holds that isolate's lock. Its drop
  no longer relies on C++'s deferral, which destroys an object that has no wrapper at once, with
  or without the lock: two references to such an object, dropped on two threads, raced on its
  count. While the isolate is torn down, a drop under the lock still drops the value then, until
  the isolate is about to be disposed, so the C++ objects that the resources teardown drops hold
  are destroyed before Dispose, as before; after it, a destructor that resets a raw v8::Global
  would use the freed isolate. ~IsolateBase now also calls its dispose hook just before Dispose,
  after which Rust no longer asks V8 whether a thread holds the lock. A jsg_cpp::Ref kept past
  teardown is dropped after Dispose, which the parent commit ("Unbind every Wrappable from its
  isolate at teardown") makes safe.
- v8::WrappableRc becomes private to jsg, since its Clone and Drop change the Wrappable's count
  without the lock, and so does the jsg_cpp bridge, whose functions clone and detach a C++
  reference without one. The macros' receiver helpers move to jsg::v8::resolve_receiver and
  resolve_method_receiver.

The argument also rests on GC running on the thread that holds the lock (--single-threaded-gc),
and on nothing releasing the lock while a Lock exists (workerd has no v8::Unlocker).

await_io keeps its Send bounds. A future may now hold a jsg::Rc, but only to drop it.

Resource state itself can still be anything, std::rc::Rc included; the next commit requires it
to be Send.

Tests: compile tests that reject deref, clone, downgrade and upgrade without a lock, and a &R
from get() captured in a 'static future, and one that accepts a resource with a
jsg::RefCell<Vec<jsg::Rc<_>>> field whose jsg::Rc and jsg::Weak are dropped on another thread.
jsg-tests check that each lock-taking operation, jsg_cpp::Ref's included, panics under another
isolate's lock, that detaching a jsg::Rc or jsg_cpp::Ref of another isolate panics, that another
isolate's GC leaves a jsg::Rc alone (in release builds), and that references to an object with
no wrapper, dropped on two threads without the lock, wait for it. They also check that teardown
destroys the C++ object of a jsg_cpp::Ref that a resource holds before the isolate is disposed,
including one reached through a jsg::Rc, that a jsg::Rc dropped under the lock during teardown
is released at once, and that a jsg_cpp::Ref kept past teardown can still be dropped. Compile tests check that WrappableRc and
the jsg_cpp bridge are private. Tests that used a resource after leaving its lock scope now read
it inside one.

src/rust/jsg/README.md gains safety rule 5, which states the argument, and src/rust/AGENTS.md
describes the new API.
@nathanwhit
nathanwhit force-pushed the nathanwhit/isolate-lock-handles branch from ae53465 to 5591c49 Compare November 11, 2026 19:29

@clanky-the-clanker clanky-the-clanker Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

✅ Approved — No issues remain. The redundant test wrapper is gone, and jsg-cpp/ffi.rs sends every operation on a Ref through the isolate-checked lock guard.

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


✅ All checks passed

🔒 Security: ✅ LGTM

  • Isolate checks: every operation that takes a lock checks, in every build, that the lock belongs to the handle's isolate and that the state is not closed.
  • Teardown: disposing is read and written under the queue mutex, so the isolate pointer is not used once Dispose() has started.
  • Bridge: the jsg_cpp bridge and WrappableRc are private, which removes the ways to change a count without the lock.
  • Send impls: they hold, because every operation except drop needs a Lock, which is neither Send nor Sync.

📖 AGENTS.md: ✅ LGTM

The src/rust/AGENTS.md updates match the new lock-taking API.


📋 Code Quality: ✅ LGTM

The ToAnotherThread wrapper is gone. The tests in gc.rs that move values to another thread now do it directly.

src/rust/jsg-cpp/ffi.rs:

  • Every operation on Ref goes through LockGuarded.
  • PhantomData<fn() -> T> means Send comes only from LockGuarded.
  • Every caller of from_cpp passes the lock.

⚡ Performance: ✅ LGTM

Each access to a handle adds only a closed-state check and an isolate pointer comparison. Drops without the lock are still queued without touching a count.


📝 Documentation: ✅ LGTM

No documentation issues.


Reviewed commit: 5591c492

@nathanwhit
nathanwhit merged commit b59577a into main Nov 11, 2026
35 of 42 checks passed
@nathanwhit
nathanwhit deleted the nathanwhit/isolate-lock-handles branch November 11, 2026 22:08
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.

4 participants