Skip to content

Commit 08faf64

Browse files
authored
[pigeon] Pass data classes and collections in a single buffer per native interop call (#13265)
Updates Kotlin JNI and Swift FFI native interop so that data classes, `List`, `Map`, and `Object` values are passed in a single buffer per call while keeping scalars, strings, enums, and typed data direct. ### Background & Motivation Previously, native interop converted every data class, `List`, `Map`, and `Object` into a graph of JVM or Objective-C objects, making a separate call across the language boundary for every field and collection element. For calls passing large or deeply nested data classes and collections, this per-element boundary overhead made native interop significantly slower than platform channels. ### Summary of Changes - **Single-Buffer Composite Value Transport**: - **Direct Types**: Scalars (`bool`, `int`, `double`), `String`, enums, and typed data (`Uint8List`, `Int32List`, `Int64List`, `Float64List`)—both non-nullable and nullable—continue to cross the JNI / FFI boundary directly as their own parameters and return values. - **Buffered Composite Types**: Data classes (including `sealed` class hierarchies), `List`, `Map`, and `Object`/`Any` arguments in a method call are encoded together into a single byte buffer using the generated `PigeonInteropCodec` (`StandardMessageCodec` format) and decoded in one pass on the receiving side. Composite return values and Kotlin `FlutterError.details` are similarly passed as a single encoded buffer. - **Unchanged User-Facing APIs**: The public Dart, Kotlin, and Swift APIs and registration methods (`HostApiRegistrar` / `HostApiSetup`, `FlutterApiRegistrar` / `FlutterApiProtocol`, data classes, and method signatures) are unchanged. - **Reduced Binding Surface**: Because composite types cross as `ByteArray` / `NSData` buffers, `jnigen` and `ffigen` only need to generate bindings for the `*Registrar`, `*Setup`, and `*Bridge` classes—not for every data class, sealed subclass, or enum. - **Additional Native Interop Optimizations**: - **Kotlin**: Replaces `entries.firstOrNull { it.raw == raw }` with constant-time `entries.getOrNull(raw)` in generated enum `ofRaw` lookups. - **Dart (JNI / FFI)**: Caches `JClass` lookups per class in lazy top-level variables (`_jniClass$<Name>`), converts JNI typed-data arrays directly via typed helpers, and copies FFI `NSData` to `Uint8List` once when deriving typed list views. - **Tests & Documentation**: - Updates the native interop integration test suite (`pigeons/native_interop_tests.dart`) and unit tests across the Dart, Kotlin, Swift, `jnigen`, and `ffigen` generators. - Updates `README.md` and `native_interop_guide.md`. # Pigeon Benchmark Comparison: Platform Channels vs. Native Interop (Objects) vs. Native Interop (Hybrid) This document compares the evolution of Pigeon's cross-language transport across three versions using measured release-mode benchmarks: &nbsp; 1. **Platform Channel Pigeon** (`BasicMessageChannel` \+ `StandardMessageCodec`) 2. **Native Interop — Objects** (`NativeInteropTransport.objects` — JNI/FFI object-graph transport) 3. **Native Interop — Hybrid** (`NativeInteropTransport.hybrid` — direct interop for scalars/strings/enums/typed-data \+ single-buffer `StandardMessageCodec` for data classes and collections) &nbsp; --- ## 1\. Architectural Evolution Across the Three Versions | Dimension | 1\. Platform Channel Pigeon | 2\. Native Interop (`objects`) | 3\. Native Interop (`hybrid`) | | :---- | :---- | :---- | :---- | | **Call Dispatch** | Asynchronous (`BinaryMessenger` hop across platform thread) | Direct synchronous JNI (`package:jni`) / FFI (`dart:ffi`) | Direct synchronous JNI (`package:jni`) / FFI (`dart:ffi`) | | **Scalars, Strings, Enums** | Serialized into `ByteData` \+ async channel hop | **1 JNI/FFI call** per parameter | **1 JNI/FFI call** per parameter | | **Top-Level Typed Data (`Uint8List`, etc.)** | Copied through channel `ByteData` | **1 bulk buffer copy** (`getRange` / `memcpy`) | **1 bulk buffer copy** (`getRange` / `memcpy`) | | **Data Classes & Collections** | **1 buffer** (`StandardMessageCodec`) | **\$O(N \\cdot F)\$ JNI/FFI calls** (1 call per field, collection element, and wrapper allocation) | **1 JNI/FFI call** carrying a single `StandardMessageCodec` `Uint8List` buffer | | **Boundary Crossings for `List<AllNullableTypes>` (\$N=100\$)** | 1 async channel message | **\~7,500+ JNI/FFI calls** | **1 synchronous JNI/FFI call** | &nbsp; > \[\!IMPORTANT\] **Why `NativeInteropTransport.objects` regressed on complex types:** While `objects` mode eliminated the async platform-channel hop (making `noop` and scalar calls 35×–3,000× faster), it translated every class field and collection element into individual JNI/FFI calls (`JArrayList.add`, `JHashMap.put`, `JLong.valueOf`, and per-field getters/constructors). Under `hybrid` mode, Pigeon keeps the 1-call fast path for primitives, strings, enums, and `Uint8List`, while packing data classes and collections into a single contiguous `Uint8List` payload that crosses JNI/FFI in one bulk transfer. &nbsp; --- ## 2\. Release-Mode Per-Call Latency (`tool/benchmark.dart`) Measured via [`tool/benchmark.dart`](file:///Users/tarrinneal/work/packages/packages/pigeon/tool/benchmark.dart) running [`native_interop_benchmarks.dart`](file:///Users/tarrinneal/work/packages/packages/pigeon/platform_tests/shared_test_plugin_code/lib/native_interop_benchmarks.dart) in `--release` mode (up to 500 ms warmup and 201 timed samples per workload; `objects` mode includes the Phase 1 object-graph fixes such as cached `JClass`, bulk `JByteBuffer`, and pre-sized `JArrayList`). ### macOS Release (Swift FFI, Apple Silicon arm64) | Benchmark Workload | 1\. Platform Channel (p50) | 2\. Native Interop `objects` (p50 / p90) | 3\. Native Interop `hybrid` (p50 / p90) | `objects` vs. Channel | `hybrid` vs. `objects` | `hybrid` vs. Channel | | :---- | ----: | ----: | ----: | ----: | ----: | ----: | | `noop` | 11.63 µs | 0.20 µs / 0.23 µs | **0.20 µs** / 0.22 µs | 58.15× faster | 1.00× | **58.15× faster** | | `echoInt` | 14.00 µs | 0.39 µs / 0.44 µs | **0.39 µs** / 0.42 µs | 35.90× faster | 1.00× | **35.90× faster** | | `echoString` | 14.18 µs | 1.23 µs / 3.73 µs | **1.22 µs** / 3.64 µs | 11.53× faster | 1.01× | **11.62× faster** | | `echoUint8List 1MB` | 289.00 µs | 263.00 µs / 449.00 µs | **228.00 µs** / 442.00 µs | 1.10× faster | 1.15× faster | **1.27× faster** | | `echoAllTypes` (1 object) | 198.00 µs | 1.03 ms / 1.60 ms | **136.50 µs** / 142.50 µs | 🔴 5.20× slower | **7.55× faster** | **1.45× faster** | | `echoClassList` (`AllNullableTypes` ×1) | 254.00 µs | 1.35 ms / 1.93 ms | **162.00 µs** / 171.00 µs | 🔴 5.32× slower | **8.34× faster** | **1.57× faster** | | `echoClassList` (`AllNullableTypes` ×10) | 2.37 ms | 14.52 ms / 15.70 ms | **1.62 ms** / 1.69 ms | 🔴 6.13× slower | **8.96× faster** | **1.46× faster** | | `echoClassList` (`AllNullableTypes` ×100) | 23.94 ms | 149.62 ms / 155.24 ms | **16.36 ms** / 17.03 ms | 🔴 6.25× slower | **9.15× faster** | **1.46× faster** | | `echoClassList` (`AllNullableTypes` ×1000) | 246.17 ms | 1,482.94 ms / 1,554.68 ms | **170.37 ms** / 174.54 ms | 🔴 6.02× slower | **8.70× faster** | **1.44× faster** | | `echoIntList` (×10) | 21.13 µs | 17.42 µs / 18.33 µs | **2.10 µs** / 2.69 µs | 1.21× faster | **8.30× faster** | **10.06× faster** | | `echoIntList` (×100) | 62.00 µs | 138.00 µs / 145.00 µs | **9.26 µs** / 9.96 µs | 🔴 2.23× slower | **14.90× faster** | **6.70× faster** | | `echoIntList` (×1000) | 433.00 µs | 1.31 ms / 1.38 ms | **77.33 µs** / 83.33 µs | 🔴 3.02× slower | **16.91× faster** | **5.60× faster** | | `echoIntList` (×10000) | 4.10 ms | 18.79 ms / 19.48 ms | **756.00 µs** / 890.00 µs | 🔴 4.58× slower | **24.85× faster** | **5.42× faster** | | `echoIntMap` (×1000) | 891.00 µs | 8.87 ms / 14.44 ms | **178.00 µs** / 189.00 µs | 🔴 9.96× slower | **49.83× faster** | **5.01× faster** | | `callFlutterEchoClassList` (×100) | 49.50 ms | 1,620.53 ms / 1,818.44 ms | **33.00 ms** / 34.24 ms | 🔴 32.74× slower | **49.11× faster** | **1.50× faster** | ### Android Release (Kotlin JNI, `emulator-5554` arm64) | Benchmark Workload | 1\. Platform Channel (p50) | 2\. Native Interop `objects` (p50 / p90) | 3\. Native Interop `hybrid` (p50 / p90) | `objects` vs. Channel | `hybrid` vs. `objects` | `hybrid` vs. Channel | | :---- | ----: | ----: | ----: | ----: | ----: | ----: | | `noop` | 671.00 µs | 0.23 µs / 1.66 µs | **0.20 µs** / 0.67 µs | 2,917× faster | 1.15× faster | **3,355× faster** | | `echoInt` | 512.00 µs | 0.53 µs / 2.83 µs | **0.23 µs** / 0.51 µs | 966× faster | 2.30× faster | **2,226× faster** | | `echoString` | 362.00 µs | 6.33 µs / 33.95 µs | **6.38 µs** / 16.16 µs | 57.19× faster | 0.99× | **56.74× faster** | | `echoUint8List 1MB` | 8.22 ms | 2.77 ms / 9.23 ms | **3.48 ms** / 10.60 ms | 2.96× faster | 0.80× | **2.37× faster** | | `echoAllTypes` (1 object) | 1.06 ms | 2.61 ms / 4.75 ms | **370.00 µs** / 1.35 ms | 🔴 2.47× slower | **7.05× faster** | **2.86× faster** | | `echoClassList` (`AllNullableTypes` ×1) | 1.01 ms | 3.35 ms / 6.05 ms | **414.00 µs** / 3.15 ms | 🔴 3.30× slower | **8.09× faster** | **2.45× faster** | | `echoClassList` (`AllNullableTypes` ×10) | 5.92 ms | 42.78 ms / 68.42 ms | **3.01 ms** / 6.62 ms | 🔴 7.23× slower | **14.20× faster** | **1.96× faster** | | `echoClassList` (`AllNullableTypes` ×100) | 24.98 ms | 717.45 ms / 936.56 ms | **35.67 ms** / 58.50 ms | 🔴 28.72× slower | **20.11× faster** | **0.70×** (parity) | | `echoClassList` (`AllNullableTypes` ×1000) | 431.27 ms | 8,006.16 ms / 9,503.80 ms | **338.73 ms** / 421.96 ms | 🔴 18.56× slower | **23.64× faster** | **1.27× faster** | | `echoIntList` (×10) | 103.50 µs | 188.40 µs / 390.80 µs | **14.50 µs** / 17.00 µs | 🔴 1.82× slower | **12.99× faster** | **7.14× faster** | | `echoIntList` (×100) | 311.00 µs | 1.61 ms / 4.48 ms | **72.33 µs** / 129.33 µs | 🔴 5.18× slower | **22.26× faster** | **4.30× faster** | | `echoIntList` (×1000) | 1.06 ms | 24.75 ms / 41.37 ms | **705.00 µs** / 1.72 ms | 🔴 23.33× slower | **35.11× faster** | **1.50× faster** | | `echoIntList` (×10000) | 9.77 ms | 258.70 ms / 330.16 ms | **7.37 ms** / 14.15 ms | 🔴 26.48× slower | **35.12× faster** | **1.33× faster** | | `echoIntMap` (×1000) | 2.53 ms | 41.48 ms / 71.02 ms | **1.56 ms** / 2.88 ms | 🔴 16.40× slower | **26.63× faster** | **1.62× faster** | | `callFlutterEchoClassList` (×100) | 92.82 ms | 1,577.38 ms / 1,764.70 ms | **69.23 ms** / 106.86 ms | 🔴 16.99× slower | **22.78× faster** | **1.34× faster** | &nbsp; --- ## 3\. Pre-Optimization `objects` Baseline (`comparison_benchmarks.dart`) Before the Phase 1 object-graph fixes (when `objects` mode also performed uncached `JClass.forName` lookups on every call and element-by-element byte buffer copies), the original `comparison_benchmarks.dart` workloads measured in [baseline\_android\_release.log](file:///Users/tarrinneal/.gemini/jetski/brain/b230b33f-5257-469a-98b7-0ebfb02a2fca/scratch/baseline_android_release.log) and [baseline\_macos.log](file:///Users/tarrinneal/.gemini/jetski/brain/b230b33f-5257-469a-98b7-0ebfb02a2fca/scratch/baseline_macos.log) showed even larger gaps: &nbsp; | Legacy Workload (15-object list of `AllNullableTypes`) | 1\. Platform Channels | 2\. Original `objects` (Pre-Phase 1\) | 3\. Phase 1 `objects` | 4\. `hybrid` | Total Speedup (`hybrid` vs. Original `objects`) | | :---- | ----: | ----: | ----: | ----: | ----: | | **Android Host `echoClassList` (×15)** | 11.0 ms | 593.0 ms | 64.2 ms | **4.5 ms** | **131.8× faster** | | **Android Flutter `callFlutterEchoClassList` (×15)** | 11.0 ms | 1,485.0 ms | 236.6 ms | **10.4 ms** | **142.8× faster** | | **macOS Host `echoClassList` (×15)** | 16.0 ms | 176.0 ms | 21.8 ms | **2.4 ms** | **73.3× faster** | | **macOS Flutter `callFlutterEchoClassList` (×15)** | 53.0 ms | 294.0 ms | 243.1 ms | **4.9 ms** | **60.0× faster** | &nbsp; --- ## 4\. Summary of Key Takeaways 1. **Platform Channels → Native Interop (`objects`):** - Delivered **36×–3,355×** lower latency on `noop` and scalar calls by replacing asynchronous platform channel messages with synchronous JNI/FFI calls. - However, even *with* Phase 1 optimizations (cached `JClass`, bulk `JByteBuffer`, pre-sized `JArrayList`), `objects` mode remained **5×–33× slower** than Platform Channels on complex data classes and collections (`1,482.94 ms` on macOS and `8,006.16 ms` on Android for 1,000 `AllNullableTypes` objects) because every field and collection element still crossed the JNI/FFI boundary individually. 2. **Native Interop (`objects`) → Native Interop (`hybrid`):** - Preserves **100% of the scalar/primitive/string/typed-data speedups** of `objects` mode (`0.20 µs` `noop` on both macOS and Android). - Speeds up data class and collection workloads by **7.5×–49.8×** over Phase 1 `objects` mode (and **60×–143×** over the original unoptimized `objects` mode) by serializing complex payloads into a single `StandardMessageCodec` byte buffer that crosses JNI/FFI in **1 call**. - Outperforms **Platform Channels** across both simple and complex workloads: - **36×–3,355× faster** on scalars and `noop` - **11.6×–56.7× faster** on strings - **1.33×–10.06× faster** on `List<int>` and `Map<int, int>` collections - **1.27×–2.86× faster** on deeply nested `AllNullableTypes` data classes &nbsp;
1 parent 3b97f56 commit 08faf64

55 files changed

Lines changed: 35107 additions & 28274 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎packages/pigeon/CHANGELOG.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,12 @@
1+
## 29.2.0
2+
3+
* [dart] [kotlin] [swift] Passes data class, `List`, `Map` and `Object` values
4+
of Kotlin JNI and Swift FFI calls in one buffer per call instead of making a
5+
call across the language boundary for every field and collection element,
6+
making calls with large data classes and collections many times faster while
7+
keeping scalars, strings, enums and typed data direct.
8+
* [kotlin] Makes enum `ofRaw` constant time.
9+
110
## 29.1.2
211

312
* [dart] Fixes `@FlutterApi` methods named `register` or `dartApi` failing with `useJni`.

‎packages/pigeon/README.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -121,7 +121,7 @@ Pigeon supports two distinct models for communication between Dart and native co
121121
| **Platform Support** | All supported platforms (Android, iOS, macOS, Windows, Linux) | Android, iOS, and macOS |
122122
| **Threading Model** | Main UI thread or custom background `TaskQueue` | Direct execution on caller thread (`TaskQueue` is not supported) |
123123
| **Dart Isolate Support** | Requires `BackgroundIsolateBinaryMessenger` | Supported for Host APIs |
124-
| **Serialization Overhead** | High (serialization and multiple copies) | Low (minimal copying) |
124+
| **Serialization Overhead** | Every value is encoded into one message and copied | Scalars, strings, enums and typed data cross directly; data classes, lists and maps are encoded into one buffer per call |
125125
| **Latency** | Higher (requires message loop scheduling) | Extremely low (direct execution) |
126126
| **Synchronous Host Calls** | Not supported | Fully supported |
127127
| **Setup Complexity** | Simple | Complex (requires external tools) |
@@ -133,7 +133,6 @@ Pigeon supports two distinct models for communication between Dart and native co
133133
- Your plugin targets Windows or Linux (Native Interop is not supported on these platforms, though you can generate platform channel code for them from the same pigeon file alongside Native Interop).
134134
- Your plugin primarily passes simple data objects or has low-frequency communication.
135135
- You want a simpler setup with no external dependencies or additional command-line tools.
136-
- Your data classes contain many nested fields or custom collections where conversion overhead might offset performance gains. There are plans to address this issue in the future.
137136
- **Consider Native Interop if**:
138137
- Your plugin handles high-frequency messaging, large typed arrays (e.g., image processing, sensor data streams), or latency-sensitive communication where serialization overhead is a bottleneck.
139138
- You need synchronous execution for platform APIs on the host thread.

‎packages/pigeon/example/app/android/app/src/main/kotlin/dev/flutter/pigeon_example_app/Messages.g.kt‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -209,8 +209,10 @@ enum class Code(val raw: Int) {
209209
TWO(1);
210210

211211
companion object {
212+
private val pigeonValues = values()
213+
212214
fun ofRaw(raw: Int): Code? {
213-
return values().firstOrNull { it.raw == raw }
215+
return pigeonValues.getOrNull(raw)
214216
}
215217
}
216218
}

‎packages/pigeon/example/app/lib/src/messages.g.dart‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -226,7 +226,6 @@ class ExampleHostApi {
226226
);
227227
final Future<Object?> pigeonVar_sendFuture = pigeonVar_channel.send(null);
228228
final pigeonVar_replyList = await pigeonVar_sendFuture as List<Object?>?;
229-
230229
final Object? pigeonVar_replyValue = _extractReplyValueOrThrow(
231230
pigeonVar_replyList,
232231
pigeonVar_channelName,
@@ -245,7 +244,6 @@ class ExampleHostApi {
245244
);
246245
final Future<Object?> pigeonVar_sendFuture = pigeonVar_channel.send(<Object?>[a, b]);
247246
final pigeonVar_replyList = await pigeonVar_sendFuture as List<Object?>?;
248-
249247
final Object? pigeonVar_replyValue = _extractReplyValueOrThrow(
250248
pigeonVar_replyList,
251249
pigeonVar_channelName,
@@ -264,7 +262,6 @@ class ExampleHostApi {
264262
);
265263
final Future<Object?> pigeonVar_sendFuture = pigeonVar_channel.send(<Object?>[message]);
266264
final pigeonVar_replyList = await pigeonVar_sendFuture as List<Object?>?;
267-
268265
final Object? pigeonVar_replyValue = _extractReplyValueOrThrow(
269266
pigeonVar_replyList,
270267
pigeonVar_channelName,

‎packages/pigeon/example/native_interop_app/android/app/src/main/kotlin/dev/flutter/pigeonnativeinteropapp/NativeInteropExample.g.kt‎

Lines changed: 47 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,9 @@ package dev.flutter.pigeonnativeinteropapp
99

1010
import android.util.Log
1111
import androidx.annotation.Keep
12+
import io.flutter.plugin.common.StandardMessageCodec
13+
import java.io.ByteArrayOutputStream
14+
import java.nio.ByteBuffer
1215

1316
private object NativeInteropExamplePigeonUtils {
1417

@@ -43,6 +46,41 @@ class FlutterError(
4346
) : RuntimeException()
4447

4548
private const val defaultInstanceName = "PigeonDefaultClassName32uh4ui3lh445uh4h3l2l455g4y34u"
49+
50+
private open class NativeInteropExamplePigeonCodec : StandardMessageCodec() {
51+
override fun readValueOfType(type: Byte, buffer: ByteBuffer): Any? {
52+
return super.readValueOfType(type, buffer)
53+
}
54+
55+
override fun writeValue(stream: ByteArrayOutputStream, value: Any?) {
56+
super.writeValue(stream, value)
57+
}
58+
}
59+
60+
/**
61+
* Encodes and decodes the buffers that native interop calls pass to and from Dart, in the same
62+
* format as the message codec.
63+
*/
64+
private object NativeInteropExamplePigeonInteropCodec : NativeInteropExamplePigeonCodec() {
65+
fun encode(value: Any?): ByteArray {
66+
val stream = ByteArrayOutputStream()
67+
writeValue(stream, value)
68+
return stream.toByteArray()
69+
}
70+
71+
fun encodeOrNull(value: Any?): ByteArray? {
72+
return if (value == null) null else encode(value)
73+
}
74+
75+
fun decode(bytes: ByteArray): Any? {
76+
return decodeMessage(ByteBuffer.wrap(bytes))
77+
}
78+
79+
fun decodeArguments(bytes: ByteArray): List<Any?> {
80+
return decode(bytes) as List<Any?>
81+
}
82+
}
83+
4684
val NativeInteropExampleApiInstances: MutableMap<String, NativeInteropExampleApiRegistrar> =
4785
mutableMapOf()
4886

@@ -52,7 +90,7 @@ interface NativeInteropExampleApi {
5290
}
5391

5492
@Keep
55-
class NativeInteropExampleApiRegistrar : NativeInteropExampleApi {
93+
class NativeInteropExampleApiRegistrar {
5694
private var api: NativeInteropExampleApi? = null
5795

5896
fun register(
@@ -73,14 +111,14 @@ class NativeInteropExampleApiRegistrar : NativeInteropExampleApi {
73111
return NativeInteropExampleApiInstances[name]
74112
}
75113

76-
override fun doSomething() {
77-
api?.let {
78-
try {
79-
return it.doSomething()
80-
} catch (e: Exception) {
81-
throw e
82-
}
114+
fun doSomething() {
115+
val pigeonVar_api = this.api ?: error("NativeInteropExampleApi has not been registered")
116+
try {
117+
pigeonVar_api.doSomething()
118+
} catch (e: FlutterError) {
119+
throw FlutterError(
120+
e.code, e.message, NativeInteropExamplePigeonInteropCodec.encodeOrNull(e.details))
121+
.apply { stackTrace = e.stackTrace }
83122
}
84-
error("NativeInteropExampleApi has not been registered")
85123
}
86124
}

0 commit comments

Comments
 (0)