Skip to content

fix: keep the base class of runtime-resolved types in large apps - #2111

Merged
edusperoni merged 5 commits into
mainfrom
fix/runtime-type-node-ids
Nov 16, 2026
Merged

edusperoni merged 5 commits into
mainfrom
fix/runtime-type-node-ids

Conversation

@edusperoni

@edusperoni edusperoni commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

Description

The symptom. In a large app, iterating Java collections from JS stops working:

const it = map.entrySet().iterator();
while (it.hasNext()) { … }          // TypeError: it.hasNext is not a function

jsonObject.keys().hasNext();          // TypeError: … hasNext is not a function
unmodifiableList.iterator();          // TypeError: … iterator is not a function

ArrayList.iterator() keeps working, and so does everything else in the app, which makes it look like something specific to iterators.

Cause. These objects are instances of private JDK classes (java.util.HashMap$EntryIterator, java.util.LinkedHashMap$LinkedKeyIterator, java.util.Collections$UnmodifiableRandomAccessList, …) that are not in the static metadata, so the runtime resolves them on first use and appends a node for each to the metadata node table. For such a type the base class was stored as a 16-bit node id, the same slot a static class record uses. But appended nodes sit after the static nodes plus a 1000-slot gap, so once the static tree has more than about 64.5k nodes their ids no longer fit: the id wraps and the type is linked to an unrelated node as its base.

The JS wrapper then has the members the class itself declares and nothing from its real base class:

Runtime class Real base (also runtime-resolved) Member lost
HashMap$KeyIterator / ValueIterator / EntryIterator HashMap$HashIterator hasNext()
LinkedHashMap$Linked*Iterator (also JSONObject.keys()) LinkedHashMap$LinkedHashIterator hasNext()
TreeMap$*Iterator, ConcurrentHashMap$*Iterator their private base iterators hasNext()
Collections$UnmodifiableList, $SynchronizedList, List.of(…) their private base collections iterator()

A type whose base class is in the static metadata (ArrayList$Itr extends Object) is linked correctly, which is why only some collections break.

Nothing in this path changed recently; it is a size cliff. An app gets there by growing: a newer compile SDK (android-36 alone has 246 more classes than android-35) or more dependencies.

The fix.

  • A runtime-resolved type holds its base class as a node pointer (MetadataTreeNode::runtimeBaseClass), and GetBaseClassNode returns it. The value record keeps its layout, with the id slot unused.
  • Node ids are 32-bit wherever a runtime-created node can appear. The other place is the element type of an array (ARRAY_OFFSET + id), which was narrowed to 16 bits the same way.
  • Runtime-created nodes are numbered from 65536 in every app, in their own vector, instead of right after the static ones. Static ids are 16-bit by format, so the two ranges never overlap, and the wide-id path now runs in a small app too. That is what lets the test app cover this.
  • The unused 1000-slot gap in the static table is gone.

Thread safety. The metadata tree is shared by every runtime in the process, and auditing it for this change turned up two existing races around runtime-resolved nodes:

  • A runtime-resolved type was appended to its parent's children vector under the reader's state lock, but MetadataNode walks those vectors with no lock in four places: building a package object, defining a class's inner types, looking up a package member, and creating the top-level namespaces. A worker resolving HashMap$KeyIterator while another runtime materializes java.util.HashMap could reallocate the vector mid-iteration.
  • Two runtimes resolving the same unknown type at once could each publish a node for it: resolving the base class can release the lock, after the only re-check. That was benign (a duplicate node).

Both are closed without adding a lock to any MetadataNode path:

  • Nodes created at run time go into a table the reader owns, keyed by parent, and are never appended to MetadataTreeNode::children. The static tree is written only while it is built at startup, so walking it unlocked is safe, and MetadataNode.cpp ends up unchanged by this PR. (An intermediate commit guarded those walks with the state lock and a copy of the list; the last commit replaces that, because those paths run under the isolate lock.)
  • The base class is resolved first, and the lookup is repeated right before the node is created and published, with no unlock in between.

The base class link is written before its node is published and never changes, and the reader's node vectors and table are only touched under the state lock.

Interface records. ReadInterfaceImplementationTypeName reads a prefix flag and a name offset that follow the type byte and base class id in a static interface record. A type resolved at run time only gets the type byte and the id slot, so for a runtime-resolved interface that read would take whatever bytes come next in the value buffer and use them as an offset into the names. Before this PR that was reachable by name, in the same timing-dependent way described under the behavior change below; with runtime nodes out of the static tree, tracing its two callers turned up none that can still get there. The function now returns an empty name for a runtime-resolved node, so it stays safe if a path to it is ever added.

Behavior change. A type resolved at run time is no longer reachable by name from its parent package or class. It used to be, but only in a runtime that had not yet materialized that parent when the type was first seen, so it depended on timing. Such types are still wrapped normally when Java hands one to JS.

Cost.

  • Nothing is added to method calls, wrapper creation, or class and package materialization, apart from one branch when an interface's node is first created (the check above).
  • Resolving a type that is in the static metadata looks it up in the static child list first, as before; the reader's own table is consulted only on a miss, which previously went straight to a Java call.
  • Resolving a runtime type no longer does a linear search of the whole node table for its base class id.
  • MetadataTreeNode stays at 64 bytes on 64-bit ABIs (the new pointer fits after reordering its members; a static_assert holds it), and there is one per metadata node.
  • All of this state is process-wide, not per isolate.

Not covered here. The static tree itself is limited to 65,535 nodes by the metadata format. The generator fails the build past that ("Metadata is too big and has overflown our current limit"), and this change does not raise the limit; it removes the cliff about 1,000 nodes below it.

Does your commit message include the wording below to reference a specific issue in this repo?

No issue.

Related Pull Requests

None.

Does your pull request have unit tests?

Yes. testJavaIterators.js (46 specs) drains iterators with hasNext()/next() over the JDK list, set and map implementations (key sets, values and entry sets), List.of, unmodifiable and synchronized wrappers, org.json.JSONObject.keys(), android.os.Bundle.keySet(), android.util.ArrayMap, an Enumeration, Kotlin collections, and app-defined iterator classes: package-private, private nested, anonymous, lambda-backed, one whose hasNext() is inherited from a non-public base class, and an array of a private class. There were no iterator specs before.

Runs, all on an API 36 arm64 emulator:

Build Result
main, node table padded so runtime nodes start past 65535 (simulates a large app) 26 of these specs fail, everything else passes
This branch 1598 / 1598 pass
This branch with the 16-bit base id read restored the same 26 specs fail

./gradlew runtestsAndVerifyResults on the final tree: 1598 / 1598.

The two races have no spec: each needs a runtime to resolve a type in the same instant another one walks its parent, and a type is only resolved once per process, so a test could not hit the window reliably. They were found by reading the accesses to the tree's child lists; BuildTree is now their only writer. The interface record read has no spec either: no path to it with a runtime-resolved interface was found to test.

The array spec passes in all three: a wrapped element-type id still resolves to an object type, which is enough to read elements, so that narrowing is fixed by inspection rather than by a failing spec.

Summary by CodeRabbit

  • Bug Fixes
    • Improved runtime handling of dynamically resolved Java types, including classes, interfaces, and array types.
    • Improved compatibility with Java iterators and enumerations across collections and map views, including implementations with inherited or non-public methods.
  • Tests
    • Expanded coverage for Java and Kotlin collections, JSON objects, bundles, iterator exhaustion, and JavaScript-wrapped iterators.
    • Added checks for iterator behavior across additional Java collection and iterable implementations.

A type missing from the static metadata, such as the private class behind
a java.util iterator, is resolved at run time and appended to the metadata
node table. Its base class was recorded as a 16-bit node id, but appended
nodes sit after the static ones plus a 1000-slot gap, so in an app whose
static tree approaches the 16-bit node limit (about 64.5k nodes) the id
wrapped and the type was linked to an unrelated base.

The wrapper then lost every member declared on the real base class:
HashMap, LinkedHashMap, TreeMap and ConcurrentHashMap iterators had no
hasNext(), org.json.JSONObject.keys() had no hasNext(), and unmodifiable,
synchronized and immutable collections had no iterator(). Types whose
base is in the static metadata were unaffected, which is why only some
collections broke.

Runtime-resolved types now hold their base class as a node pointer, and
node ids are 32-bit wherever a runtime-created node can appear (array
element types). Runtime-created nodes are numbered from 65536 in every
app instead of right after the static ones, so the wide-id path runs in
small apps too and the new iterator specs cover it.
@coderabbitai

coderabbitai Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The metadata reader now assigns 32-bit IDs to runtime-created nodes and resolves runtime children and base-class pointers separately from the static tree. The test app adds Java and Kotlin iterator coverage, Java iterator fixtures, and loads the new test suite.

Changes: Runtime Metadata

Layer / File(s) Summary
Runtime node IDs and storage
test-app/runtime/src/main/cpp/MetadataReader.h, test-app/runtime/src/main/cpp/MetadataReader.cpp
Node ID APIs now use 32-bit IDs. Runtime nodes use separate storage, and static-tree initialization and node lookup use the updated ID model.
Runtime child access and array nodes
test-app/runtime/src/main/cpp/MetadataReader.h, test-app/runtime/src/main/cpp/MetadataReader.cpp
Child lookup checks static children before runtime children. Array and forwarding nodes are registered in runtime storage.
Runtime type and base-class resolution
test-app/runtime/src/main/cpp/MetadataTreeNode.h, test-app/runtime/src/main/cpp/MetadataTreeNode.cpp, test-app/runtime/src/main/cpp/MetadataReader.cpp
Metadata resolution rechecks for existing children and registers new nodes as runtime children. MetadataTreeNode stores runtime base-class pointers.

Java Iterator Coverage

Layer / File(s) Summary
Iterator fixture implementations
test-app/app/src/main/java/com/tns/tests/IteratorFixtures.java
The fixtures provide package-private, private nested, anonymous, and inherited-method iterators, plus a lambda-backed iterable and an array of private nested iterators.
Iterator tests and suite registration
test-app/app/src/main/assets/app/tests/testJavaIterators.js, test-app/app/src/main/assets/app/mainpage.js
The suite tests Java and Kotlin collection iterators, map views, enumerations, ListIterator, non-public implementations, and a Java iterator wrapped in a JavaScript Proxy. The main page loads the suite.

Estimated code review effort: 4 (Complex) | ~40 minutes

Change: Bug fix

Merge Risk: Minimal · up to 27210

The change keeps base classes for runtime-resolved types in large apps and adds iterator test coverage. No concrete merge-blocking risk was identified.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title names the main change: runtime-resolved types keep their base class, which the objectives say fixes missing Java collection methods in JS wrappers when base-class node IDs exceed 16 bits. Th…
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.
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Full details: Title check

Explanation

The title names the main change: runtime-resolved types keep their base class, which the objectives say fixes missing Java collection methods in JS wrappers when base-class node IDs exceed 16 bits. The changeset matches this, since the runtime-resolved base class is stored as a node pointer and node IDs widen to 32 bits. The title is concise and specific, and it does not use vague terms.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between 46e5b16 and 27210e8.

Files selected for processing: 1

  • test-app/runtime/src/main/cpp/MetadataReader.h

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 1 remain after this review.

The metadata tree is shared by every runtime in the process. A type
resolved at run time is appended to its parent's child list under the
reader's state lock, but MetadataNode walked those lists with no lock
when building a package object, defining a class's inner types, looking
up a package member and creating the top-level namespaces. A worker
resolving HashMap$KeyIterator while another runtime materialized
java.util.HashMap could reallocate the vector under the reader.

Those four sites now go through MetadataReader::GetChildren, which
copies the list under the lock, or MetadataReader::GetChild.

Publishing a runtime-resolved node is also atomic now. Resolving its
base class can release the lock, after the only re-check for a node
another thread published meanwhile, so two runtimes resolving the same
type could each add a node for it. The base class is resolved first and
the lookup repeated right before the node is created and published.
There is one node per metadata entry, up to 65,535 of them. The base
class pointer for runtime-resolved types took the node from 64 to 72
bytes on 64-bit ABIs. Ordering the members so the two narrow ones share
a word brings it back to 64, and a static_assert holds it there.
Guarding MetadataNode's walks of a node's child list with the reader's
state lock put a lock, and a copy of the list, on class materialization
and package member lookup, which run under the isolate lock.

Nodes created at run time now go into a table the reader owns, keyed by
parent, instead of being appended to MetadataTreeNode::children. The
static tree is therefore never written after it is built, and
MetadataNode walks it without a lock again, exactly as before. The
reader looks a child up in the static list first and only then in its
own table, so resolving a type that is in the static metadata costs what
it did.

A type resolved at run time is consequently no longer reachable by name
from its parent package or class. It used to be, but only in a runtime
that had not yet materialized that parent when the type was first seen.
…terface

A static interface record carries a prefix flag and a name offset after
its type byte and base class id. A type resolved at run time gets only
the type byte and the id slot, so reading the name for one used whatever
bytes followed in the value buffer as an offset into the names.

No caller can currently reach this with a runtime-resolved interface,
since such nodes are no longer part of the static tree. The check keeps
it that way for one branch on a path that runs once per interface node.
@edusperoni
edusperoni merged commit b8cc3cf into main Nov 16, 2026
8 checks passed
@edusperoni
edusperoni deleted the fix/runtime-type-node-ids branch November 16, 2026 17:13
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.

1 participant