Repository navigation
Docs: Direct Interop spike and decision - #37
Conversation
|
Warning Review limit reachedYou've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. Next included review available in 59 minutes. View limit details
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. |
|
Claude finished @krassx's task in 44s —— View job Review of PR #37: Direct Interop spike and decision
This PR adds documentation only. It doesn't change any code or CI. I did not build or run the spike app, and I did not re-measure anything. The device numbers are taken from the doc as written. Overall risk: Low. Merge recommendation: Approve once the Pigeon pin is corrected. The two P3 items are optional follow-ups. Findings (inline)
Merge blockersOnly the P2 pin correction. It's a one-word fix. Positives
|
| revisit when Pigeon's interop mode leaves preview. Measured 2026-11-12; sources: the | ||
| [3.50 post](https://flutter.dev/blog/whats-new-in-flutter-3-50), the [interop docs](https://docs.flutter.dev/interop) and the guide shipped in | ||
| Pigeon 30.0.2 (`native_interop_guide.md`). The spike app is the files in `doc/interop-spike/` (`.txt`, so analysis ignores them): a fresh | ||
| `flutter create` app with Pigeon 30.0.2 (we pin 29.0.11), `jni`, `objective_c`, `jnigen` 1.0.1, `ffigen`, `swift2objc`, `swiftgen`, one |
There was a problem hiding this comment.
P2 Medium: the pinned Pigeon version is stated wrongly (here and on line 43).
Problem: The doc says "we pin 29.0.11", but the repo pins 29.0.7: native-versions.json (pigeon.version), pigeons/pubspec.yaml:9, and the "Autogenerated from Pigeon (v29.0.7)" header of lib/bridge/messages.g.dart. The same wrong number is on line 43, and finding 8 in that line says the pin "is a decision in native-versions.json", which is the file that says 29.0.7.
Impact: CLAUDE.md requires that "a doc claim about code (a name, default, limit, command, path) is checked against the code". A reader who relies on this page to size the 29 → 30 jump starts from the wrong baseline. Nothing guards this page, because test/native_versions_test.dart doesn't scan doc/.
Fix: Use 29.0.7 in both places, or drop the patch number and write "we pin 29.x (native-versions.json)". The second option goes stale less easily.
| The channel baseline is a plain `MethodChannel` (Pigeon's channel mode adds a codec of similar cost). Interop is two to three orders of | ||
| magnitude faster per call and the typed list is ten times faster than a `List<int>`. Both ran on the main thread (`thread()` returns `main`). | ||
| None of our paths is limited by call latency: secure rectangles, the view-hierarchy cache, network events and log lines publish at most | ||
| once per frame or per event, and the native SDK work dominates. |
There was a problem hiding this comment.
P3 Low: the headline speed-up claim doesn't match the table.
Problem: "two to three orders of magnitude faster per call" holds for Android only. Android is 378–776 us against 1.4 us, about 270–550x. On the iPhone, ping is 30 us against 0.6–0.7 us, about 45x, and echo is 30 against 1.1–1.2, about 25x. That is under two orders. The 256-int case is 30–39 us against 1.6–1.8 us, about 20x. The List<int> interop case is only 1.3–1.7x faster than the channel on iOS (23–26 us against 30–39 us), and on Android it is 3–4x (132–139 us against 415–605 us).
Impact: This is the number a later reader would use when deciding to revisit. It doesn't change the decision, because the call rate is low either way. Still, "orders of magnitude" is the figure people will quote.
Fix: Give it per platform: "about 250–550x on Android, 20–45x on iOS for scalar calls; a List<int> payload narrows the gap to about 1.3–1.7x on iOS and 3–4x on Android". Add a line noting that the interop calls are synchronous on the main isolate and the channel calls are async.
| blocked about 1.5 ms until the main isolate ran the handler; from the main thread 3 ms). That is a hard conflict with our report-handler | ||
| and view-hierarchy rules (the SDK calls us on the main thread and Dart's reply needs it; a blocking cross-thread call can deadlock). | ||
| Our channel design never blocks. |
There was a problem hiding this comment.
P3 Low: findings 4 and 5 are weaker evidence than the framing suggests.
- Finding 4: The measurement shows the native worker blocking for about 1.5 ms and then returning. No deadlock was observed. "Can deadlock" comes from reading the rules, not from the spike. The report-handler and view-hierarchy cases were not run; the closing section admits this when it says to add them before deciding. Reword it as "blocks the calling native thread until the Dart handler runs (measured 1.5 ms from a worker, 3 ms from main); not tested against the report-handler or view-hierarchy paths".
- Finding 5: The doc itself says the hang is "not diagnosed" and "may be a spike error". The spike's iOS
AppDelegate.swift.txtnever registers aSpikeEventsimplementation natively. Native calls it throughSpikeEventsRegistrar.registeredSpikeEvents, and Dart callsSpikeEvents.setUp(...). It's worth stating the exact hang point, for example the lastsay(...)line reached, so the later re-run can compare. A single device, one iOS version and an undiagnosed result shouldn't weigh as much as the Kotlin-only and preview facts (1–3), which on their own settle the decision.
Neither point changes the recommendation.
| | [design-rules.md](design-rules.md) | The detailed invariants per area (secure rectangles, report handlers, view hierarchy, options, facade, network, logs, exceptions, attachments, feedback, harness) with the guards that hold them | | ||
| | [workbook-conformance.md](workbook-conformance.md) | Each step, trap and minimum-viable-wrapper item of the wrapper workbook mapped to its implementation, guard and device scenario, with the gaps | | ||
| | [verification.md](verification.md) | The device verification harness, its default guards, the environment, results per scenario, findings and what was not covered | | ||
| | [direct-interop-spike.md](direct-interop-spike.md) | Whether to replace the Pigeon channel bridge with Direct Interop (Flutter 3.50): measurements on the phone and iPhone, findings, decision | |
There was a problem hiding this comment.
P3 Low: the decision isn't recorded in PLAN.md.
CLAUDE.md says PLAN.md holds "the status, the decisions (D1 to D12), the open questions". D5 already cites Direct Interop as a reason for the 3.50 floor, and D7 chooses Pigeon for the bridge. This PR makes a bridge decision ("keep the channel bridge for 10.0; revisit when interop leaves preview") without adding a D-row or an open question, and without a pointer from D7. Someone reading PLAN.md to see why the floor moved to get Direct Interop won't learn that 10.0 doesn't use it. Add a short D13 or an addendum to D7 that links this page.
|
Claude finished @krassx's task in 51s —— View job Re-review of PR #37 after the new commit (
|
| Severity | Where | Issue |
|---|---|---|
| P3 | doc/direct-interop-spike.md:70 |
The blocking-callback figures disagree with finding 4: 219 ms on the phone against "about 1.5 ms", with no device named in finding 4. The iOS worker-blocking result is run in main_ios.dart.txt but not reported. Line 71 says "listener blocks", which reads backwards. |
| P3 | doc/direct-interop-spike.md:3 |
The headline decision, findings 1-3 and 5-8, and the "later" list are all about Pigeon's interop mode. The second spike shows JNIgen and FFIgen work on a Java class without Pigeon, so finding 2 doesn't apply to that path. The doc never says what is decided for it. |
Checked and fine
- The second-spike sources match what the doc describes (static store,
ping,echo, 256-int publish, listener). - The keep rule in
proguard-rules.pro.txtmatches the "ClassNotFoundExceptionwithout a keep rule" finding. It is relevant toandroid/consumer-rules.proif the stable generators are ever used. - The "Decision input" caveat is stated honestly: a synchronous call can't help the main-thread callbacks (the view-hierarchy answer and the iOS report handler). That matches the repo's "never block" rules.
- The frame-capture hypothesis is labelled as a hypothesis, not a result.
Summary
- Overall risk: Low (documentation only; nothing runs in CI or ships).
- Merge recommendation: Approve after the Pigeon pin is corrected (P2). The P3 items are optional follow-ups, though the headline scope (line 3) is worth fixing in the same pass.
- Most important to fix: 29.0.7 instead of 29.0.11 in two places. Then reconcile the 1.5 ms and 219 ms figures and scope the headline to Pigeon.
- Positives: the new section reports its caveats, such as the keep rule, the empty-output FFIgen trap and the build-environment dependence. The sources are reproducible and committed as
.txt.
· branchdocs/direct-interop-spike
|
|
||
| * **Dart to native is a plain static call:** no engine routing (a process-wide store has none), the same thread as Dart (`main`), a Java exception | ||
| arrives as a `JThrowable`, a background isolate can call it (no setup), and the call works from the main thread inside the same frame. | ||
| * **Native to Dart, blocking:** the main thread inside a Dart call took 1 ms (Android) and worked on iOS; a **worker thread blocked 219 ms** on the phone |
There was a problem hiding this comment.
P3 Low: the blocking-callback numbers contradict finding 4 and aren't reconciled; the iOS result is missing.
Problem: Finding 4 (lines 32-35) says a worker blocked "about 1.5 ms" and 3 ms from main. This section says a worker blocked 219 ms on the phone, and that 1.2 ms was on an emulator. Finding 4 doesn't say which device the 1.5 ms came from. If it was the emulator, the first spike understated the cost by about 150x on real hardware. If it was the phone, the two runs disagree by the same factor, and neither run explains why an idle main isolate took 219 ms. Separately, main_ios.dart.txt:64-70 runs a worker-blocking fire on iOS, but no number for it appears here. "A blocking callback has no usable bound" is therefore a statement about Android only. Line 71 also says "FFIgen listener blocks", which reads backwards: a listener block is the non-blocking one.
Impact: This is the evidence for the rule "never block" against Direct Interop, and a later re-run compares against it. Mixed devices and a missing iOS figure make that comparison unreliable.
Fix: State the device next to every blocking figure, including finding 4. Add the iOS worker-blocking time (or say it wasn't captured). Reword line 71 to "FFIgen .listener is fire-and-forget (it ran on a background thread on the iPhone)". Optionally record why the phone took 219 ms (for example, whether the isolate was idle in Future.delayed).
| @@ -0,0 +1,84 @@ | |||
| # Direct Interop spike (Pigeon native-interop mode, Flutter 3.50 / Dart 3.14) | |||
|
|
|||
| Question: should 10.0 replace the Pigeon platform-channel bridge with Direct Interop? Answer from this spike: **not for 10.0**; | |||
There was a problem hiding this comment.
P3 Low: the top-line decision and the "findings" no longer match the second spike.
Problem: The answer on lines 3-4 ("not for 10.0; revisit when Pigeon's interop mode leaves preview") and findings 1-3 and 5-8 are all about Pigeon's interop mode. The section added in the second commit uses JNIgen 1.0.1 and FFIgen directly, which the repo's own native-versions.json describes as stable. It shows they work on a Java class (SpikeStore.java.txt), so finding 2 ("Kotlin only") doesn't apply to that path. Finding 8 (Pigeon 30 needed) doesn't apply either. The "What is worth trying later" list (lines 45-51) mentions only Pigeon and has no entry for the direct generators. The "Decision input" section (line 78) ends in a hypothesis and a possible next measurement but doesn't say what is decided.
Impact: Someone reading only the first paragraph, or doc/README.md's one-line summary, concludes that interop is closed until Pigeon stabilises. The second spike shows a different, stable path that could be tried for the secure-rectangle store without Pigeon. The doc's own words ("a hypothesis: nothing here measured frames") leave that open, and a reader of the headline would never find it.
Fix: Scope the headline to "Pigeon's interop mode: not for 10.0". Add one sentence saying the stable generators were also spiked and what is decided for them (for example: not for 10.0; candidate for the secure-rectangle store after the frame-capture measurement). Add the same pointer to the "later" list and to the doc/README.md row. The same pointer belongs in the PLAN.md entry I flagged earlier.
0c7a57e to
2e88f93
Compare
|
Claude finished @krassx's task in 34s —— View job Re-review of PR #37 after commit
|
| Severity | Where | Issue |
|---|---|---|
| P3 | doc/direct-interop-spike.md:93-94 |
The reason a synchronous call can't help the SDK's main-thread calls is "a helper thread waiting for it deadlocks". The doc's own measurements show a blocking call made from the main thread running inline and working. The real constraint is that the Dart handler would have to be synchronous, and our report handlers are async. The sentence should name the design that deadlocks and the rule that blocks the other one. |
Summary
- Overall risk: Low (documentation only; nothing runs in CI or ships).
- Merge recommendation: Approve. The one remaining item is optional wording and doesn't change the decision.
- Most important to fix: the explanation at lines 93-94, if you want the recorded reasoning to match the measurements.
- Positives: every earlier finding was addressed in one commit. The doc says where evidence is thin (single runs, the uncaptured iOS time, the unreconciled 219 ms against 1.5 ms). The decision is recorded in
PLAN.mdD13 and indexed indoc/README.md. The spike sources are committed as.txtand match what the doc describes.
· branchdocs/direct-interop-spike
| here measured frames. A synchronous call into Dart cannot help the calls the SDK makes on the main thread (the view-hierarchy answer, the iOS report | ||
| handler): Dart's isolate is that thread, so a helper thread waiting for it deadlocks. **Decided:** the stable generators are not used in 10.0 |
There was a problem hiding this comment.
P3 Low: the reason given for the main-thread calls is narrower than what the spike showed.
Problem: The doc says a synchronous call into Dart "cannot help" the SDK's main-thread calls because "a helper thread waiting for it deadlocks". Lines 78-80 report that a blocking call made from the main thread worked (1 ms on Android, worked on iOS), because it runs inline on the isolate's thread. So the deadlock applies to a helper-thread design only. A direct main-thread call is not ruled out by anything measured. The actual obstacle is different: the Dart handler would have to answer synchronously. Our report handlers are async (Dart's reply needs the main thread, so the pipeline must not block). The view-hierarchy answer must come from the native cache within 500 ms.
Impact: This is the sentence a later reader will use to close the question. If it rests on the wrong mechanism, someone could re-open it (or wrongly dismiss the view-hierarchy case) without seeing the real constraint. The decision itself is not affected.
Fix: Say which design deadlocks and which one is blocked by the rules. For example: "a helper thread waiting for the isolate deadlocks when the isolate is itself waiting on the main thread; a direct call on the main thread runs inline, but the Dart handler has to be synchronous, and the report handlers are async (design-rules: never block) while the view-hierarchy answer is already served from a native cache."
2e88f93 to
0ed4b18
Compare
|
Claude finished @krassx's task in 15s —— View job Re-review of PR #37 after commit
|
… and the decision not to adopt it for 10.0 Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WeiJxNbNUdWru1zs68bYV8 Change-Id: Iab578e0b48892ecb4e2ed771ef97641f0f4035be
…he phone and the iPhone Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WeiJxNbNUdWru1zs68bYV8 Change-Id: I8204f93681726badaf15ff978d29429d7eb97794
…he evidence behind the blocking claims, the scope of the decision, D13 Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WeiJxNbNUdWru1zs68bYV8 Change-Id: Ifbb07466eff6956fe54ff3f2d029391b307594be
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WeiJxNbNUdWru1zs68bYV8 Change-Id: Iab986d5fe059751e791bcf37b6b3b3b6741cb8dd
0ed4b18 to
dffb3df
Compare
|
Claude finished @krassx's task in 20s —— View job Re-review of PR #37 at head
|
Spike of Pigeon's native-interop mode on the physical phone and iPhone (release builds): interop is orders of magnitude faster per call, but it is preview, Kotlin-only on Android, blocks native threads on native-to-Dart callbacks, and a FlutterApi registration hung on the iPhone XS. Recommendation: keep the channel bridge for 10.0. Stacked on #36.
🤖 Generated with Claude Code
https://claude.ai/code/session_01WeiJxNbNUdWru1zs68bYV8