Skip to content

Cache Rust JSG struct field names and DictionaryTemplate per realm - #8484

Merged
littledivy merged 2 commits into
mainfrom
littledivy/2026-11-16-audit-rjsg-perf
Nov 17, 2026
Merged

littledivy merged 2 commits into
mainfrom
littledivy/2026-11-16-audit-rjsg-perf

Conversation

@littledivy

Copy link
Copy Markdown
Member

The code #[jsg_struct] generates interned every field name on every conversion, and built each object with Object::New and one CreateDataProperty per field. C++ JSG_STRUCT caches the names, and with fast_jsg_struct a v8::DictionaryTemplate that creates the object in one call. In bench-jsg, a Rust struct converted to JavaScript took 7.5x as long as the C++ one with fast_jsg_struct.

In this patch the Realm caches, per struct type, a v8::Global of each interned field name and, with fast_jsg_struct, a DictionaryTemplate declaring the fields. ToJS creates the object from the template when the flag is on, and otherwise sets the fields by the cached names. FromJS reads the fields by the cached names. The handles are reset when the Realm is dropped and before a startup snapshot is created. bench-jsg gains RustStructFast to compare with CppStructFast.

Rust/C++ CPU time per op before after
fast_jsg_struct struct/octet-out 7.52x 1.96x
fast_jsg_struct struct/pair-roundtrip 4.25x 2.10x
struct/octet-out 1.56x 1.12x
struct/pair-roundtrip 2.29x 1.59x
struct/octet-in 2.29x 1.70x
struct/pair-in 3.04x 2.28x

Measured with bench-jsg on Linux, statically linked, median of 5 processes.

@littledivy
littledivy requested review from a team as code owners November 16, 2026 05:20

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

This review, of dff9b078

✅ Approved — No correctness, safety or performance issues found. The cached handles have a sound lifetime, are reset before snapshot creation, and the shims respect the pending-exception rules.

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

Nothing exploitable here. The shims check exceptionPending(). The cached handles are cleared only while no Lock is in use, and the second clear call has nothing left to free, so there is no double free. The template path defines data properties, so prototype setters don't run.


📖 AGENTS.md: ✅ LGTM

The existing Rust JSG guidance on persistent handles and lock rules still applies to the new cache.


📋 Code Quality: ✅ LGTM

Shape lifetime, Realm drop order, the snapshot reset path, the pending-exception checks in the new shims, and the value-count assertion are all sound. The new tests cover handle reuse with and without fast_jsg_struct, field order, and recaching after the templates are taken.


⚡ Performance: ✅ LGTM

This is a performance improvement. The cache grows only with the number of struct types, and each conversion costs one TypeId hash lookup. kj::SmallArray allocates on the heap only for structs with more than 16 fields.


📝 Documentation: ✅ LGTM

The README and comment updates match the new behaviour.


Reviewed commit: dff9b078

@codecov-commenter

codecov-commenter commented Nov 16, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 6.25000% with 150 lines in your changes missing coverage. Please review.
✅ Project coverage is 66.40%. Comparing base (5713cd2) to head (31bb834).
⚠️ Report is 2 commits behind head on main.

Files with missing lines Patch % Lines
src/rust/jsg/structs.rs 5.82% 97 Missing ⚠️
src/rust/jsg/ffi.c++ 0.00% 33 Missing ⚠️
src/rust/jsg/v8.rs 0.00% 17 Missing ⚠️
src/rust/jsg/lib.rs 57.14% 3 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main    #8484      +/-   ##
==========================================
- Coverage   66.44%   66.40%   -0.05%     
==========================================
  Files         794      795       +1     
  Lines      202976   203135     +159     
  Branches    31536    31540       +4     
==========================================
+ Hits       134868   134883      +15     
- Misses      49646    49792     +146     
+ Partials    18462    18460       -2     

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

Comment thread src/rust/jsg/ffi.c++ Resolved
@littledivy
littledivy force-pushed the littledivy/2026-11-16-audit-rjsg-perf branch from dff9b07 to 4b16064 Compare November 16, 2026 15:22

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

This review, of 4b16064b

✅ Approved — No correctness, safety or performance problems in the changes since the last review. The cached handles' lifetime, the snapshot reset path and the pending-exception checks in the new shims are still sound.

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

Nothing exploitable:

  • Pending exceptions: the new shims check exceptionPending().
  • Handle lifetime: the cached handles are dropped exactly once, and never while a Lock is in use.
  • Template path: it defines data properties, so setters on Object.prototype don't run.
  • Cache keys: struct field names are fixed at compile time.

📖 AGENTS.md: ✅ LGTM

The new cache follows the repository's Rust JSG guidance on persistent handles and the pending-exception rules.


📋 Code Quality: ✅ LGTM

No problems found:

  • Field indices: they match the order of the names passed to StructShape::of.
  • Shape lifetime: boxed shapes are freed only in StructShapes::clear.
  • FFI layout: MaybeLocal has the same size and alignment as v8::MaybeLocal<Value>, which ffi-inl.h asserts.
  • Value count: new_instance asserts it.
  • Tests: they cover handle reuse with and without fast_jsg_struct, field order, absent optional fields, and recaching after the templates are taken.

⚡ Performance: ✅ LGTM

This is a performance improvement:

  • Per-conversion cost: each conversion does one TypeId lookup and then reuses the cached names and template.
  • Value passing: values are passed as a stack array without copying.
  • One-time setup: names are interned and the template is built once per struct type per realm.

📝 Documentation: ✅ LGTM

The README and comment updates match the new behaviour.


Reviewed commit: 4b16064b

@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 with the shape local renamed, see the inline comment.

Comment thread src/rust/jsg-macros/lib.rs Resolved
The code `#[jsg_struct]` generates interned every field name on every
conversion, and built each object with `Object::New` and one
`CreateDataProperty` per field. C++ `JSG_STRUCT` caches the names, and
with `fast_jsg_struct` a `v8::DictionaryTemplate` that creates the
object in one call. In bench-jsg, a Rust struct converted to JavaScript
took 7.5x as long as the C++ one with `fast_jsg_struct`.

In this patch the Realm caches, per struct type, a `v8::Global` of each
interned field name and, with `fast_jsg_struct`, a DictionaryTemplate
declaring the fields. ToJS creates the object from the template when
the flag is on, and otherwise sets the fields by the cached names.
FromJS reads the fields by the cached names. The handles are reset when
the Realm is dropped and before a startup snapshot is created.
bench-jsg gains `RustStructFast` to compare with `CppStructFast`.

Rust/C++ CPU time per op (bench-jsg, Linux, statically linked, median
of 5 processes):

  case                         before   after
  fast struct/octet-out         7.52x   1.96x
  fast struct/pair-roundtrip    4.25x   2.10x
  struct/octet-out              1.56x   1.12x
  struct/pair-roundtrip         2.29x   1.59x
  struct/octet-in               2.29x   1.70x
  struct/pair-in                3.04x   2.28x
@littledivy
littledivy force-pushed the littledivy/2026-11-16-audit-rjsg-perf branch from 4b16064 to 8358c62 Compare November 17, 2026 03:38

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

This review, of 8358c622

✅ Approved — The shape local is renamed to __jsg_shape at every use and a regression test covers it. Nothing else in the changes since the last review introduces a correctness, safety or performance problem.

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

Nothing exploitable in the changes since the last review.


📖 AGENTS.md: ✅ LGTM

The changes follow the repository's guidance for Rust JSG.


📋 Code Quality: ✅ LGTM

No problems found:

  • Rename: src/rust/jsg-macros/lib.rs uses __jsg_shape at every site that used to use shape.
  • Regression test: ShapeFieldStruct covers the case that used to fail to compile.
  • Refactor: moving the empty-struct handling into empty_struct_body does not change behaviour. get_shape is None exactly when the struct has no fields.

⚡ Performance: ✅ LGTM

Each conversion still does one TypeId lookup in StructShape::of and then reuses the cached names and template. The changes add no new allocation to the hot path.


📝 Documentation: ✅ LGTM

The doc comments match the renamed local.


Reviewed commit: 8358c622

@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 — The shape local is renamed to __jsg_shape at every use and a regression test covers it. Nothing else in the changes since the last review introduces a correctness, safety or performance problem.

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

Nothing exploitable in the changes since the last review.


📖 AGENTS.md: ✅ LGTM

The changes follow the repository's guidance for Rust JSG.


📋 Code Quality: ✅ LGTM

No problems found:

  • Rename: src/rust/jsg-macros/lib.rs uses __jsg_shape at every site that used to use shape.
  • Regression test: ShapeFieldStruct covers the case that used to fail to compile.
  • Refactor: moving the empty-struct handling into empty_struct_body does not change behaviour. get_shape is None exactly when the struct has no fields.

⚡ Performance: ✅ LGTM

Each conversion still does one TypeId lookup in StructShape::of and then reuses the cached names and template. The changes add no new allocation to the hot path.


📝 Documentation: ✅ LGTM

The doc comments match the renamed local.


Reviewed commit: 31bb834f — same changes as 8358c622, so this is that commit's review (no new review was run; line numbers are as of 8358c622)

@littledivy
littledivy merged commit 4613a9a into main Nov 17, 2026
23 checks passed
@littledivy
littledivy deleted the littledivy/2026-11-16-audit-rjsg-perf branch November 17, 2026 05:16
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