Skip to content

Require Traced trait implementors to be Send - #8355

Merged
nathanwhit merged 1 commit into
mainfrom
nathanwhit/rust-traced-send
Nov 12, 2026
Merged

nathanwhit merged 1 commit into
mainfrom
nathanwhit/rust-traced-send

Conversation

@nathanwhit

Copy link
Copy Markdown
Member

Why

State behind the isolate lock (resources, function data, promise values) is shared by every IoContext on the isolate, and those run on different threads. The lock ensures one thread uses it at a time, so it must be Send, but needn't be Sync, just as Mutex needs only T: Send.

Nothing enforces this today. A resource can hold an std::rc::Rc. One thread can stash a clone outside the lock, and then two threads update its non-atomic count at once. That's a data race from safe code.

With #8319, which gates reference handles on the lock, this makes data races on lock-guarded state a compile error. It also keeps non-Send values confined to a single IoContext.

What changes

  • Traced now requires Send. The compiler rejects std::rc::Rc, Arc<RefCell<_>> and thread-bound KJ objects in resource state, function data and promise values.
    • std::rc::Rc loses its Traced and MemoryInfo impls.
    • jsg_traced! only implements Traced for a generic type when it's Send.
    • Hand-written Traced impls stay safe: getting one wrong leaks, panics or aborts, but can't cause undefined behavior.
  • Arc and Mutex are now Traced for data that holds no GC references, so a resource can share plain data with a future (for example Arc<Mutex<_>>). Heap snapshots report a Mutex's contents through try_lock, so a snapshot never blocks on a thread holding it.
  • ffi::InspectorSession and IoOwnedObject are declared Send, each with its justification:
    • every InspectorSession call, including its destructor, requires the lock;
    • an IoOwn dropped off its thread queues the deletion to its IoContext.
  • SpanBuilder and TraceContext lose Traced. No resource holds them, and they are bound to their thread.
  • Safety rule 5 in src/rust/jsg/README.md becomes "State guarded by the isolate lock is Send". src/rust/AGENTS.md and the jsg-macros README describe the new bounds.

@nathanwhit
nathanwhit added this pull request to stack #8320 November 11, 2026 02:54
@nathanwhit
nathanwhit requested review from a team as code owners November 11, 2026 02:54
@nathanwhit nathanwhit changed the title Require Send for Traced Require Traced trait implementors to be Send Nov 11, 2026

@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 4b165fe2.

This review, of 802e9d33

💬 Approved with comments — The change is sound. The only notes are a stale mention of Rc in src/rust/AGENTS.md, a missing test for the Mutex snapshot path that skips a locked mutex, and a doc line break.

Findings: 1 info · 2 suggestions (3 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: 💬 2 suggestions

The change is consistent. One note on test coverage and one doc nit.

Recommendation: 💬 Optional Nits

  • [SUGGESTION] The path where the Mutex snapshot skips a held or poisoned mutex has no test (src/rust/jsg/memory.rs:573)
  • [SUGGESTION] Stray line break in the jsg::Cell doc comment (src/rust/jsg/cell.rs:51)
View full review
  • The new MemoryInfo for std::sync::Mutex<T> reports nothing when the mutex is held or poisoned, and no test covers that path. The tests only use unlocked mutexes.
  • jsg::Cell's doc comment has /// which on a line by itself.

📖 AGENTS.md: 💬 1 info

One stale mention of Rc in the memory-reporting guidance

Recommendation: 💬 Optional Nits

  • [INFO] AGENTS.md still lists Rc among the pointers that report their contents, but std::rc::Rc no longer implements MemoryInfo (src/rust/AGENTS.md:54)
View full review

src/rust/AGENTS.md:54 still says Box, Rc and Arc report what they hold the same way, but this pull request removes MemoryInfo for std::rc::Rc.


✅ All other checks passed

🔒 Security: ✅ LGTM

The new Send bound and the unsafe impl Send declarations for ffi::InspectorSession and IoOwnedObject each come with a justification. I found no security issues.


⚡ Performance: ✅ LGTM

jsg::Cell::trace now sets and restores one thread-local flag per visit, which costs a few instructions. The Mutex snapshot impl uses try_lock and never blocks. Everything else changes only trait bounds, tests and docs.


📝 Documentation: ✅ LGTM

The new safety rule 5 in src/rust/jsg/README.md and the updated jsg-macros README match the code.


Reviewed commit: 802e9d33

Comment thread src/rust/AGENTS.md Resolved
Comment thread src/rust/jsg/cell.rs Resolved
Comment thread src/rust/jsg/memory.rs Resolved

@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.

LGTM, one suggestion inline.

Comment thread src/rust/api/inspector.rs Resolved
@nathanwhit
nathanwhit force-pushed the nathanwhit/rust-traced-send branch from 802e9d3 to 4b165fe 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.

Superseded by the review of 93975365.

This review, of 4b165fe2

💬 Approved with comments — The change is sound. The only notes are a stale mention of Rc in src/rust/AGENTS.md, a missing test for the Mutex snapshot path that skips a locked mutex, and a doc line break.

Findings: 1 info · 2 suggestions

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


📋 Code Quality: 💬 2 suggestions

The change is consistent. One note on test coverage and one doc nit.

Recommendation: 💬 Optional Nits

  • [SUGGESTION] The path where the Mutex snapshot skips a held or poisoned mutex has no test (src/rust/jsg/memory.rs:573)
  • [SUGGESTION] Stray line break in the jsg::Cell doc comment (src/rust/jsg/cell.rs:51)
View full review
  • The new MemoryInfo for std::sync::Mutex<T> reports nothing when the mutex is held or poisoned, and no test covers that path. The tests only use unlocked mutexes.
  • jsg::Cell's doc comment has /// which on a line by itself.

📖 AGENTS.md: 💬 1 info

One stale mention of Rc in the memory-reporting guidance

Recommendation: 💬 Optional Nits

  • [INFO] AGENTS.md still lists Rc among the pointers that report their contents, but std::rc::Rc no longer implements MemoryInfo (src/rust/AGENTS.md:54)
View full review

src/rust/AGENTS.md:54 still says Box, Rc and Arc report what they hold the same way, but this pull request removes MemoryInfo for std::rc::Rc.


✅ All other checks passed

🔒 Security: ✅ LGTM

The new Send bound and the unsafe impl Send declarations for ffi::InspectorSession and IoOwnedObject each come with a justification. I found no security issues.


⚡ Performance: ✅ LGTM

jsg::Cell::trace now sets and restores one thread-local flag per visit, which costs a few instructions. The Mutex snapshot impl uses try_lock and never blocks. Everything else changes only trait bounds, tests and docs.


📝 Documentation: ✅ LGTM

The new safety rule 5 in src/rust/jsg/README.md and the updated jsg-macros README match the code.


Reviewed commit: 4b165fe2 — same changes as 802e9d33, so this is that commit's review (no new review was run; line numbers are as of 802e9d33)

Base automatically changed from nathanwhit/isolate-lock-handles to main November 11, 2026 22:08
@nathanwhit
nathanwhit force-pushed the nathanwhit/rust-traced-send branch from 4b165fe to 9397536 Compare November 11, 2026 22:08

@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 5933a1dc.

This review, of 93975365

💬 Approved with comments — The change is sound and tightens thread safety. Only minor notes remain: a stale doc mention of Rc, a missing test for the Mutex snapshot skip path, and a doc-comment line break.

Findings: 1 info · 2 suggestions

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


📋 Code Quality: 💬 2 suggestions

Two minor notes from the earlier review remain open: no test for the Mutex snapshot skip path, and a stray doc-comment line break.

Recommendation: 💬 Optional Nits

  • [SUGGESTION] No test covers the path where the Mutex snapshot skips a held or poisoned mutex (src/rust/jsg/memory.rs:573)
  • [SUGGESTION] Stray line break in the jsg::Cell doc comment (src/rust/jsg/cell.rs:51)
View full review
  • src/rust/jsg/memory.rs:573: when the mutex is held or poisoned, MemoryInfo for std::sync::Mutex<T> reports nothing, and no test covers that path. The existing tests only use unlocked mutexes.
  • src/rust/jsg/cell.rs:51: /// which sits alone on a line in the jsg::Cell doc comment.

📖 AGENTS.md: 💬 1 info

AGENTS.md still says Rc reports its contents in heap snapshots.

Recommendation: 💬 Optional Nits

  • [INFO] AGENTS.md still lists Rc among the pointers that report their contents, but std::rc::Rc no longer implements MemoryInfo (src/rust/AGENTS.md:54)
View full review

src/rust/AGENTS.md:54 says Box, Rc and Arc report what they hold the same way, but this pull request removes MemoryInfo for std::rc::Rc.


✅ All other checks passed

🔒 Security: ✅ LGTM

The new Send bound narrows what lock-guarded state can hold. The unsafe impl Send declarations for ffi::InspectorSession and IoOwnedObject each give a specific justification. The Arc and Mutex Traced impls require HoldsNoGcReferences, and Arc also requires Sync. The read-in-place guard in jsg::Cell restores its thread-local flag on panic.


⚡ Performance: ✅ LGTM

jsg::Cell::trace now sets and restores one thread-local flag per visit, which costs a few instructions. The Mutex snapshot impl uses try_lock and never blocks. The std RefCell Traced impl is now a no-op. Everything else changes only trait bounds, tests and docs.


📝 Documentation: ✅ LGTM

The new safety rule 5 in src/rust/jsg/README.md and the updated jsg-macros README match the code.


Reviewed commit: 93975365

@nathanwhit
nathanwhit force-pushed the nathanwhit/rust-traced-send branch from 9397536 to 5933a1d Compare November 12, 2026 03:05

@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 1effdc15.

This review, of 5933a1dc

💬 Approved with comments — The change is sound and tightens thread safety. Only two INFO notes remain, both about developer docs (jsg-macros/README.md and src/rust/AGENTS.md) that no longer match the trait bounds.

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.


📖 AGENTS.md: 💬 1 info

AGENTS.md still says the std Cell's Traced impl reads its value in place.

Recommendation: 💬 Optional Nits

  • [INFO] Only jsg::Cell reads its value in place now; the std Cell's Traced impl is a no-op (src/rust/AGENTS.md:46)
View full review

src/rust/AGENTS.md:46 ends with "Traced for Cell<T> (std and jsg::) reads the T in place through Cell::as_ptr()". At this commit, Traced for std::cell::Cell<T> is a no-op for T: HoldsNoGcReferences (src/rust/jsg/wrappable.rs:341-343). Only jsg::Cell reads its value in place.


📝 Documentation: 💬 1 info

The jsg-macros README leaves out the Sync bound that Arc needs.

Recommendation: 💬 Optional Nits

  • [INFO] README omits the Sync bound that Arc<T> needs to be Traced (src/rust/jsg-macros/README.md:49)
View full review

src/rust/jsg-macros/README.md:49 says the HoldsNoGcReferences marker lets a struct into std::sync::Arc. But Traced and HoldsNoGcReferences for Arc<T> both require T: HoldsNoGcReferences + Sync (src/rust/jsg/wrappable.rs:359,363).


✅ All other checks passed

🔒 Security: ✅ LGTM

The Send bound narrows what lock-guarded state can hold. The unsafe impl Send for ffi::InspectorSession and for IoOwnedObject each state a specific invariant. Holding the inspector session in a LockGuarded instead, as suggested in the discussion, would be further hardening; it is not a defect. Map keys must now be HoldsNoGcReferences, since they are not visited.


📋 Code Quality: ✅ LGTM

Both earlier notes are fixed. memory_info.rs now covers the try_lock skip path for a locked Mutex, and the jsg::Cell doc comment reads as one paragraph. In jsg::Cell, a Drop guard restores the read-in-place flag, so it is also restored on panic, and replace moves the value out before any visit runs.


⚡ Performance: ✅ LGTM

The new Traced impls for std cells, Arc and Mutex do nothing. jsg::Cell::trace sets and restores one thread-local flag per visit. The Mutex snapshot uses try_lock, so it never blocks.


Reviewed commit: 5933a1dc

Comment thread src/rust/AGENTS.md Resolved
Comment thread src/rust/jsg-macros/README.md Resolved
The isolate lock is a mutex over what the isolate's references reach: resources, function data
and reaction data, including the values of typed promises. One thread uses that state at a time,
but the lock passes between threads, so state one thread creates, another uses or drops, and a
thread that holds the lock can move a value out and keep it after releasing the lock. That is
Rust's Send: as Mutex<T> is Sync only for T: Send, the state is sound when everything in it is
Send. It need not be Sync, since no two threads hold references to it at once.

Nothing checks this today. A resource can hold an std::rc::Rc; a thread that holds the lock can
keep a clone of it where the lock doesn't guard it (a thread_local!, a task on its event loop)
and use it while the next thread to take the lock uses the original. A KJ object held in a
resource, bound to its IoContext's thread, can likewise be dropped by another thread holding the
lock.

- Traced, which everything in that state implements, now requires Send, so the compiler rejects
  std::rc::Rc, Arc<RefCell<_>> and thread-bound KJ objects there. std::rc::Rc loses its Traced
  impl, and jsg_traced! implements Traced for a generic type only where it is Send.
- Hand-written impls stay safe: their other duties (visit every GC reference, keep traced state
  with one GC owner, hold no Global, change nothing but through the visitor) leak, panic or
  abort when broken, but can't cause undefined behaviour. For the last, std::cell::Cell and
  RefCell, which hold no GC references, now trace nothing; Cell's trace read its value in place,
  so a trace that wrote into the same Cell could drop the value under the read. jsg::Cell, which
  must visit its value, refuses writes into any jsg::Cell on the thread while a visit reads one
  in place, as it already did while a heap snapshot reported one.
- Map keys, which aren't visited, must be HoldsNoGcReferences, which the docs already asked: a
  jsg::Rc key stayed strong and leaked any cycle through it. Hashers must be Send.
- std::sync::Arc<T> (T: Sync) and Mutex<T> are Traced for T: HoldsNoGcReferences, so a resource
  can share plain data with a future, and so are the atomics. A heap snapshot reports a Mutex's
  contents, through try_lock, so as not to wait for a thread that holds it. std::rc::Rc loses
  its MemoryInfo impl, which nothing could reach any more.
- ffi::InspectorSession is declared Send: every call to it, its destructor included, requires the
  isolate lock. (A jsg::Rc<InspectorConnection> kept past teardown would destroy it after the
  isolate, Send or not; nothing keeps one, and the comment says so.) io-context's IoOwnedObject is declared Send: IoOwn's destructor, run off its
  IoContext's thread, queues the deletion to that IoContext through a mutex. SpanBuilder and
  TraceContext, which hold KJ objects bound to their thread and which no resource holds, lose
  their Traced impls, so a resource or function data holding one no longer compiles.

Tests: compile tests that reject Traced for std::rc::Rc, Arc<RefCell<_>>, non-Send function
data, a hand-written impl for a non-Send type, a resource holding a SpanBuilder and a map keyed
by jsg::Rc, and one that accepts a resource with Arc<Mutex<_>> and Arc<AtomicU32> fields. A
jsg-test checks that writing into a jsg::Cell from a trace panics. Tests that stored an std::rc::Rc in a resource
now use an Arc newtype or read through the resource; the heap snapshot tests share allocations,
and build cycles, through Arc and Mutex instead.

Safety rule 5 in src/rust/jsg/README.md becomes "State guarded by the isolate lock is Send", and
src/rust/AGENTS.md and the jsg-macros README describe the new bounds.
@nathanwhit
nathanwhit force-pushed the nathanwhit/rust-traced-send branch from 5933a1d to 1effdc1 Compare November 12, 2026 03:12

@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 — Both earlier documentation notes are fixed, and I found no new problems. Requiring Send on Traced tightens thread safety for state guarded by the isolate lock.

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

Requiring Send keeps std::rc::Rc out of lock-guarded state. Each unsafe impl Send states a specific invariant. Wrapping the inspector session in LockGuarded would be optional hardening.


📖 AGENTS.md: ✅ LGTM

src/rust/AGENTS.md now says only jsg::Cell reads its value in place.


📋 Code Quality: ✅ LGTM

The new bounds are consistent: HoldsNoGcReferences requires Traced, Arc<T> also needs T: Sync, and jsg_traced! restricts generic impls with where $t: Send. jsg::Cell restores its flag through a Drop guard.


⚡ Performance: ✅ LGTM

The new Traced impls do nothing at runtime, and the Mutex snapshot path uses try_lock, so it never blocks.


📝 Documentation: ✅ LGTM

jsg-macros/README.md now states the Sync requirement for Arc.


Reviewed commit: 1effdc15

@nathanwhit
nathanwhit merged commit bb1bb9c into main Nov 12, 2026
23 checks passed
@nathanwhit
nathanwhit deleted the nathanwhit/rust-traced-send branch November 12, 2026 04:59
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