Skip to content

Commit 9316bf0

Browse files
authored
[pigeon] Fix JNI/FFI typed data memory lifetime bugs and update docs (flutter#13061)
Fixes flutter#193465 **JNI (Android):** `JArray.getRange` returns a typed list backed by `malloc`'d memory whose finalizer runs when the isolate that created it exits. If a Pigeon call was made in `Isolate.run`, the returned `Int64List`/`Float64List`/etc. was freed as soon as the result was sent back, so the receiving isolate read garbage. The generated codec now copies these into Dart-heap typed lists. **FFI (iOS/macOS):** When reading `PigeonTypedData`, the `NSData` that owns the bytes could become unreachable (and be released by its finalizer) while `fromList` was still copying from its buffer. The generated code now uses `data` after the copy so it stays alive, and returns empty lists directly for empty data instead of calling `asTypedList` on a possibly-null pointer. The JNI fix adds one copy per array. Removing it would need `package:jni` to fill Dart-heap lists directly; that's better done upstream. ## Pre-Review Checklist - [] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. **Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed. [^1]: Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling.
1 parent d4fb76a commit 9316bf0

9 files changed

Lines changed: 208 additions & 111 deletions

File tree

‎packages/pigeon/CHANGELOG.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,11 @@
1+
## 29.0.5
2+
3+
* [dart] Fixes JNI typed data arrays being backed by native memory that is freed when
4+
the isolate that read them exits.
5+
* [dart] Fixes a potential use-after-free when reading FFI typed data arrays.
6+
* Updates native interop guides and migration skill for `jnigen` 1.0.0 and
7+
current tooling requirements.
8+
19
## 29.0.4
210

311
* [swift] Fixes FFI number wrapping for Objective-C `CFBoolean` and floating-point `NSNumber` values.

‎packages/pigeon/example/native_interop_app/lib/src/native_interop_example.g.dart‎

Lines changed: 29 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -68,16 +68,16 @@ class _PigeonJniCodec {
6868
return value.as(JBoolean.type).booleanValue();
6969
} else if (value.isA<JByteArray>(JByteArray.type)) {
7070
final JByteArray array = value.as(JByteArray.type);
71-
return array.getRange(0, array.length).buffer.asUint8List();
71+
return Uint8List.fromList(array.getRange(0, array.length).buffer.asUint8List());
7272
} else if (value.isA<JIntArray>(JIntArray.type)) {
7373
final JIntArray array = value.as(JIntArray.type);
74-
return array.getRange(0, array.length);
74+
return Int32List.fromList(array.getRange(0, array.length));
7575
} else if (value.isA<JLongArray>(JLongArray.type)) {
7676
final JLongArray array = value.as(JLongArray.type);
77-
return array.getRange(0, array.length);
77+
return Int64List.fromList(array.getRange(0, array.length));
7878
} else if (value.isA<JDoubleArray>(JDoubleArray.type)) {
7979
final JDoubleArray array = value.as(JDoubleArray.type);
80-
return array.getRange(0, array.length);
80+
return Float64List.fromList(array.getRange(0, array.length));
8181
} else if (value.isA<JList<JObject>>(JList.type as JType<JList<JObject>>)) {
8282
final List<JObject?> list = value.as(JList.type).asDart();
8383
final res = <Object?>[];
@@ -299,15 +299,31 @@ ffi_bridge.NativeInteropExamplePigeonTypedData _toPigeonTypedData(TypedData valu
299299

300300
Object? _getValueFromPigeonTypedData(ffi_bridge.NativeInteropExamplePigeonTypedData value) {
301301
final NSData data = value.data;
302-
final Pointer<Void> bytes = data.bytes;
303-
return switch (value.type) {
304-
0 => Uint8List.fromList(bytes.cast<Uint8>().asTypedList(data.length)),
305-
1 => Int32List.fromList(bytes.cast<Int32>().asTypedList(data.length ~/ 4)),
306-
2 => Int64List.fromList(bytes.cast<Int64>().asTypedList(data.length ~/ 8)),
307-
3 => Float32List.fromList(bytes.cast<Float>().asTypedList(data.length ~/ 4)),
308-
4 => Float64List.fromList(bytes.cast<Double>().asTypedList(data.length ~/ 8)),
309-
_ => throw ArgumentError.value(value),
310-
};
302+
final ObjCObjectRef dataRef = data.object$.ref;
303+
try {
304+
final int lengthInBytes = data.length;
305+
if (lengthInBytes == 0) {
306+
return switch (value.type) {
307+
0 => Uint8List(0),
308+
1 => Int32List(0),
309+
2 => Int64List(0),
310+
3 => Float32List(0),
311+
4 => Float64List(0),
312+
_ => throw ArgumentError.value(value),
313+
};
314+
}
315+
final Pointer<Void> bytes = data.bytes;
316+
return switch (value.type) {
317+
0 => Uint8List.fromList(bytes.cast<Uint8>().asTypedList(lengthInBytes)),
318+
1 => Int32List.fromList(bytes.cast<Int32>().asTypedList(lengthInBytes ~/ 4)),
319+
2 => Int64List.fromList(bytes.cast<Int64>().asTypedList(lengthInBytes ~/ 8)),
320+
3 => Float32List.fromList(bytes.cast<Float>().asTypedList(lengthInBytes ~/ 4)),
321+
4 => Float64List.fromList(bytes.cast<Double>().asTypedList(lengthInBytes ~/ 8)),
322+
_ => throw ArgumentError.value(value),
323+
};
324+
} finally {
325+
dataRef.release();
326+
}
311327
}
312328

313329
Object? _convertNumberWrapperToDart(ffi_bridge.NativeInteropExampleNumberWrapper value) {

‎packages/pigeon/lib/src/dart/dart_generator.dart‎

Lines changed: 44 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -2547,16 +2547,16 @@ class _PigeonJniCodec {
25472547
return value.as(JBoolean.type).booleanValue();
25482548
} else if (value.isA<JByteArray>(JByteArray.type)) {
25492549
final JByteArray array = value.as(JByteArray.type);
2550-
return array.getRange(0, array.length).buffer.asUint8List();
2550+
return Uint8List.fromList(array.getRange(0, array.length).buffer.asUint8List());
25512551
} else if (value.isA<JIntArray>(JIntArray.type)) {
25522552
final JIntArray array = value.as(JIntArray.type);
2553-
return array.getRange(0, array.length);
2553+
return Int32List.fromList(array.getRange(0, array.length));
25542554
} else if (value.isA<JLongArray>(JLongArray.type)) {
25552555
final JLongArray array = value.as(JLongArray.type);
2556-
return array.getRange(0, array.length);
2556+
return Int64List.fromList(array.getRange(0, array.length));
25572557
} else if (value.isA<JDoubleArray>(JDoubleArray.type)) {
25582558
final JDoubleArray array = value.as(JDoubleArray.type);
2559-
return array.getRange(0, array.length);
2559+
return Float64List.fromList(array.getRange(0, array.length));
25602560
} else if (value.isA<JList<JObject>>(JList.type as JType<JList<JObject>>)) {
25612561
final List<JObject?> list = value.as(JList.type).asDart();
25622562
final res = <Object?>[];
@@ -2930,25 +2930,48 @@ $_ffiBridgePrefix.${_classNamePrefix}PigeonTypedData _toPigeonTypedData(TypedDat
29302930
}
29312931
29322932
2933+
''');
2934+
// `bytes` is owned by `data`, so `data` must stay alive until the copy is
2935+
// complete. `NSData` itself isn't `Finalizable`, so holding the local isn't
2936+
// enough; holding its `ObjCObjectRef` and releasing it explicitly in
2937+
// `finally` guarantees liveness, and frees it immediately rather than
2938+
// waiting for its finalizer.
2939+
indent.format('''
29332940
Object? _getValueFromPigeonTypedData($_ffiBridgePrefix.${_classNamePrefix}PigeonTypedData value) {
29342941
final NSData data = value.data;
2935-
final Pointer<Void> bytes = data.bytes;
2936-
return switch (value.type) {
2937-
0 => Uint8List.fromList(bytes.cast<Uint8>().asTypedList(data.length)),
2938-
1 => Int32List.fromList(
2939-
bytes.cast<Int32>().asTypedList(data.length ~/ 4),
2940-
),
2941-
2 => Int64List.fromList(
2942-
bytes.cast<Int64>().asTypedList(data.length ~/ 8),
2943-
),
2944-
3 => Float32List.fromList(
2945-
bytes.cast<Float>().asTypedList(data.length ~/ 4),
2946-
),
2947-
4 => Float64List.fromList(
2948-
bytes.cast<Double>().asTypedList(data.length ~/ 8),
2949-
),
2950-
_ => throw ArgumentError.value(value),
2951-
};
2942+
final ObjCObjectRef dataRef = data.object\$.ref;
2943+
try {
2944+
final int lengthInBytes = data.length;
2945+
if (lengthInBytes == 0) {
2946+
return switch (value.type) {
2947+
0 => Uint8List(0),
2948+
1 => Int32List(0),
2949+
2 => Int64List(0),
2950+
3 => Float32List(0),
2951+
4 => Float64List(0),
2952+
_ => throw ArgumentError.value(value),
2953+
};
2954+
}
2955+
final Pointer<Void> bytes = data.bytes;
2956+
return switch (value.type) {
2957+
0 => Uint8List.fromList(bytes.cast<Uint8>().asTypedList(lengthInBytes)),
2958+
1 => Int32List.fromList(
2959+
bytes.cast<Int32>().asTypedList(lengthInBytes ~/ 4),
2960+
),
2961+
2 => Int64List.fromList(
2962+
bytes.cast<Int64>().asTypedList(lengthInBytes ~/ 8),
2963+
),
2964+
3 => Float32List.fromList(
2965+
bytes.cast<Float>().asTypedList(lengthInBytes ~/ 4),
2966+
),
2967+
4 => Float64List.fromList(
2968+
bytes.cast<Double>().asTypedList(lengthInBytes ~/ 8),
2969+
),
2970+
_ => throw ArgumentError.value(value),
2971+
};
2972+
} finally {
2973+
dataRef.release();
2974+
}
29522975
}
29532976
''');
29542977
}

‎packages/pigeon/lib/src/generator_tools.dart‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ import 'generator.dart';
1616
/// The current version of pigeon.
1717
///
1818
/// This must match the version in pubspec.yaml.
19-
const String pigeonVersion = '29.0.4';
19+
const String pigeonVersion = '29.0.5';
2020

2121
/// Default plugin package name.
2222
const String defaultPluginPackageName = 'dev.flutter.pigeon';

‎packages/pigeon/native_interop_guide.md‎

Lines changed: 26 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -46,12 +46,8 @@ Using Native Interop in pigeon follows the standard pigeon workflow, with a few
4646
To use Native Interop, your development environment and the corresponding external tools must be configured:
4747

4848
### Android (JNI / JNIgen)
49-
- **Java 17**: Required specifically by the Android build tools and JNIgen.
50-
- **Android SDK**: Must be installed and configured in your path.
51-
- **Kotlin Version (`<= 2.1.0`)**: JNIgen uses `kotlinx-metadata-jvm` to parse Kotlin class metadata. It currently supports Kotlin metadata versions up to **2.1.0**. If the Android Gradle project uses a higher Kotlin plugin version (e.g. Kotlin 2.4.0), JNIgen will throw `IllegalArgumentException: Provided Metadata instance has version ... while maximum supported version is ...`. Ensure `settings.gradle.kts` sets Kotlin to `2.1.0`:
52-
```kotlin
53-
id("org.jetbrains.kotlin.android") version "2.1.0" apply false
54-
```
49+
- **Android SDK**: Must be installed and configured in your path. JNIgen uses the JDK bundled with Flutter by default, so a separate JDK installation is not required.
50+
- **`jnigen` 1.0.0 or later**: Earlier versions of JNIgen cannot parse metadata from newer Kotlin compilers and fail with `IllegalArgumentException: Provided Metadata instance has version ... while maximum supported version is ...`. `jnigen` 1.0.0 supports Kotlin metadata up to 2.4.
5551

5652
### iOS/macOS (FFI / FFIgen)
5753
- **LLVM (version 9+) / Xcode Command Line Tools**: Required by FFIgen to parse C/Objective-C headers (`xcode-select --install`).
@@ -62,24 +58,27 @@ To use Native Interop, your development environment and the corresponding extern
6258

6359
### Step 1: Add Dependencies
6460

65-
Add the required runtime dependencies to `dependencies` and code generators to `dev_dependencies`. Using `flutter pub add` ensures runtime packages resolve to the latest compatible versions:
61+
Add the required runtime dependencies to `dependencies` and code generators/config-script dependencies to `dev_dependencies` in the package where Pigeon runs (for a plugin package, add these to the **plugin's** `pubspec.yaml`, not `example/pubspec.yaml`, unless the example app runs Pigeon directly).
62+
63+
Because Pigeon generates helper scripts in `tool/pigeon/` (`*_ffigen_config.dart` and `*_jnigen_config.dart`), `dart pub publish --dry-run` requires every package imported by `lib/` or `tool/` to be explicitly declared in `pubspec.yaml`:
6664

6765
```bash
6866
# Add Pigeon:
6967
flutter pub add dev:pigeon
7068

7169
# For iOS/macOS Swift FFI:
72-
flutter pub add ffi
73-
flutter pub add objective_c
74-
# Pigeon requires this specific version for compatibility with its generated FFIgen configuration:
75-
flutter pub add dev:[email protected]
70+
flutter pub add ffi objective_c meta
71+
# Code generators and packages imported by tool/pigeon/*_ffigen_config.dart:
72+
flutter pub add dev:ffigen dev:swift2objc dev:swiftgen dev:path dev:pub_semver
7673

7774
# For Android Kotlin JNI:
7875
flutter pub add jni
79-
# Pigeon requires this specific version for compatibility with its generated JNIgen configuration:
80-
flutter pub add dev:jnigen@1.0.0
76+
# Code generator and packages imported by tool/pigeon/*_jnigen_config.dart:
77+
flutter pub add dev:jnigen dev:logging dev:path
8178
```
8279

80+
*Note: Ensure the resolved `objective_c` version in `pubspec.yaml` matches the version expected by your `ffigen` version (e.g., `ffigen: ^22.0.0` generates bindings that require `objective_c: ^9.6.0`).*
81+
8382
### Step 2: Configure Pigeon Options
8483

8584
Enable Native Interop for your target platforms by setting the configuration options in your Pigeon file:
@@ -133,11 +132,11 @@ dart run pigeon --input <path/to/pigeon_file.dart>
133132
When Native Interop options (`useJni` or `useFfi`) are enabled, Pigeon automatically orchestrates running `jnigen` and `ffigen` as part of the generation process:
134133

135134
- **Android (JNI)**: When `kotlinOptions.useJni` is enabled:
136-
1. Generates the JNI-compatible Kotlin bridge and the `jnigen_config.dart` script in `tool/pigeon/`.
135+
1. Generates the JNI-compatible Kotlin bridge and the `<input_name>_jnigen_config.dart` script in `tool/pigeon/`.
137136
2. Runs `jnigen` via the config script to parse the Kotlin bridge and produce Dart JNI bindings.
138137
3. Generates the final pigeon Dart output that wraps and imports those JNI bindings.
139138
- **iOS/macOS (FFI)**: When `swiftOptions.useFfi` is enabled:
140-
1. Generates the Objective-C compatible Swift bridge and the `ffigen_config.dart` script in `tool/pigeon/`.
139+
1. Generates the Objective-C compatible Swift bridge and the `<input_name>_ffigen_config.dart` script in `tool/pigeon/`.
141140
2. Runs `ffigen` via the config script to parse the Objective-C bridge and produce Dart FFI bindings.
142141
3. Generates the final pigeon Dart output that wraps and imports those FFI bindings.
143142

@@ -231,15 +230,15 @@ For standalone Flutter Applications, JNIgen defaults to searching `build/app/tmp
231230

232231
### 5.3 Manual Configuration Script Execution
233232

234-
Pigeon writes the interop configuration scripts to `tool/pigeon/jnigen_config.dart` and `tool/pigeon/ffigen_config.dart`.
233+
Pigeon writes the interop configuration scripts to `tool/pigeon/<input_name>_jnigen_config.dart` and `tool/pigeon/<input_name>_ffigen_config.dart`.
235234

236235
- **Solution**: Run the generated config scripts directly to view verbose stderr logs and diagnose toolchain errors:
237236
```bash
238237
# Debug JNIgen (Android):
239-
dart run tool/pigeon/jnigen_config.dart
238+
dart run tool/pigeon/<input_name>_jnigen_config.dart
240239

241240
# Debug FFIgen (iOS/macOS):
242-
dart run tool/pigeon/ffigen_config.dart
241+
dart run tool/pigeon/<input_name>_ffigen_config.dart
243242
```
244243

245244
### 5.4 Failed to Load Objective-C Class (`<ffiModuleName>.<Api>Setup`)
@@ -248,6 +247,15 @@ If your app crashes at startup with `FailedToLoadClassException: Failed to load
248247
- **Module Name Mismatch**: Ensure `ffiModuleName` matches your app's Swift module name. If iOS and macOS share the same generated Dart FFI file, ensure both platforms use the same module name (e.g., align macOS by setting `PRODUCT_MODULE_NAME` in `macos/Runner/Configs/AppInfo.xcconfig`).
249248
- **Linker Dead-Code Stripping**: Ensure your native host code instantiates and registers the implementation (e.g. `MyApiSetup.register(api: api)` in `MainFlutterWindow.swift` on macOS or `AppDelegate.swift` on iOS) so the linker does not strip the class.
250249

250+
### 5.5 Startup Crash on Android (`VmServiceDisappearedException` / `JNI is not initialized`)
251+
252+
If your app or integration test crashes at startup on Android with `adb logcat` showing:
253+
```text
254+
F DartJNI : JNI is not initialized. Are you trying to invoke a Java API from Dart code too early, before 'main()' (such as during Dart plugin class registration)?
255+
```
256+
- **Cause**: Your plugin's `registerWith()` method (invoked by Flutter's `_PluginRegistrant.register()` before `main()`) constructed your Dart plugin class, and its constructor eagerly called `<MyApi>.createWithNativeInteropApi()` before `JniPlugin` initialized `DartJNI`.
257+
- **Solution**: Initialize `<MyApi>.createWithNativeInteropApi()` lazily using `late final` rather than eagerly in the constructor initializer list (see [Section 4 of the Migration Guide](./native_interop_migration_guide.md#4-dart-client-adaptation)).
258+
251259
---
252260

253261
## 6. Migration from Platform Channels

0 commit comments

Comments
 (0)