Skip to content

Commit fcf3a7e

Browse files
committed
Address Liam's review comments and add cupertino_http/cronet_http examples
1 parent 650cbb7 commit fcf3a7e

3 files changed

Lines changed: 44 additions & 20 deletions

File tree

‎sites/docs/src/content/interop/dart-ffi.md‎

Lines changed: 15 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -14,38 +14,37 @@ or [JNIgen](/interop/jnigen),
1414
`dart:ffi` is the underlying technology that powers these tools
1515
and enables native memory interop.
1616

17-
## When to use `dart:ffi`
17+
## When to use `dart:ffi` and `package:ffi`
1818

19-
When you use FFIgen or JNIgen to generate Dart bindings,
20-
the generated code doesn't automatically convert Dart objects
21-
like `String` or `List` into native formats.
2219
Dart memory is automatically garbage collected while native C memory is
23-
manually managed, so use `dart:ffi` to bridge this gap.
20+
manually managed, so use `dart:ffi` and `package:ffi` to bridge this gap.
2421

25-
The two most common scenarios when `dart:ffi` is needed are
26-
memory allocation and data conversion.
22+
The two most common scenarios when `package:ffi` is needed alongside `dart:ffi`
23+
are memory allocation and C string conversion.
2724

28-
With memory allocation, use `dart:ffi` to allocate space on the system heap
25+
With memory allocation, use `package:ffi` to allocate space on the system heap
2926
for native arguments, and manually free that memory when done
3027
to prevent memory leaks.
3128

32-
With data conversion, use `dart:ffi` to convert Dart data types
33-
so they can be read by native code.
29+
With data conversion, use `package:ffi` to convert Dart strings into C strings
30+
(`Pointer<Utf8>` or `Pointer<Utf16>`) so they can be read by native C code.
3431

3532
## Core tools: `dart:ffi` and `package:ffi`
3633

37-
To write interop code, use two libraries:
34+
To write C interop code, use two libraries:
3835

39-
- **`dart:ffi`:** Built into the core Dart SDK.
40-
It provides native representation types and lookup signatures.
41-
- **`package:ffi`:** A required dependency for working with `dart:ffi`.
42-
It provides memory allocation methods and conversion helpers.
36+
- **`dart:ffi`:** Built into the core Dart SDK and required for doing FFI
37+
interop. It provides native representation types, pointers, structs, and
38+
function lookup signatures.
39+
- **`package:ffi`:** A companion package that contains utilities helpful in
40+
common C interop use cases, such as memory allocation (`calloc` and `malloc`)
41+
and C string conversion helpers.
4342

4443
## Concurrency in Flutter
4544

4645
FFI calls are synchronous and run on the thread on which they're called.
4746
If you invoke a heavy or blocking C function on your Flutter app's
48-
main UI thread, your app freezes or drops frames.
47+
main UI thread, your app may freeze or drop frames.
4948
To prevent this, execute blocking FFI calls inside a background Dart isolate
5049
using `Isolate.run`.
5150

‎sites/docs/src/content/interop/ffigen.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,10 @@ The `add` example highlights the general flow with a toy native API
7575
The `code_assets` examples highlight real-world examples like
7676
system hostname lookups and audio playback.
7777

78+
For a production package on pub.dev that uses FFIgen to wrap Apple's
79+
`NSURLSession` API, check out [`package:cupertino_http`][cupertino-http-pub]
80+
([source on GitHub][cupertino-http-src]).
81+
7882
## Constraints and limitations
7983

8084
Some general considerations when working with FFIgen:
@@ -112,13 +116,15 @@ as shown in the [Objective-C memory management guide][objc-gc-doc].
112116
FFIgen wrappers enforce Dart static types,
113117
but the underlying Objective-C object might have a different runtime subclass,
114118
so Dart's `is` and `as` keywords won't work as expected.
115-
Use `.isA()` and `.as()` instead.
119+
Use `.isA()` and `.as()` instead, as shown in the
120+
[Objective-C runtime types guide][objc-runtime-types-doc].
116121

117122
### Objective-C multithreading
118123

119124
UI-related Objective-C calls must run on the iOS main platform thread.
120125
Also, some types of callbacks can crash your app
121126
if they're executed on the wrong thread.
127+
To learn more, consult the [Objective-C threading guide][objc-threading-doc].
122128

123129
### Swift compatibility
124130

@@ -141,5 +147,9 @@ refer to the following resources:
141147
[ffigen-pub]: {{site.pub-pkg}}/ffigen
142148
[objc-pub]: {{site.pub-pkg}}/objective_c
143149
[swiftgen-pub]: {{site.pub-pkg}}/swiftgen
150+
[cupertino-http-pub]: {{site.pub-pkg}}/cupertino_http
151+
[cupertino-http-src]: https://github.com/dart-lang/http/tree/master/pkgs/cupertino_http
144152
[ffigen-examples]: https://github.com/dart-lang/native/tree/main/pkgs/ffigen/example
145153
[objc-gc-doc]: https://github.com/dart-lang/native/blob/main/pkgs/ffigen/doc/objc_gc.md
154+
[objc-runtime-types-doc]: https://github.com/dart-lang/native/blob/main/pkgs/ffigen/doc/objc_runtime_types.md
155+
[objc-threading-doc]: https://github.com/dart-lang/native/blob/main/pkgs/ffigen/doc/objc_threading.md

‎sites/docs/src/content/interop/jnigen.md‎

Lines changed: 18 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,10 @@ refer to the [`permissions_plugin` demo][permissions-demo] and the
6969
[`android_toast_demo`][toast-demo] in the official Flutter native interop
7070
demos repository.
7171

72+
For a production package on pub.dev that uses JNIgen to wrap the Android
73+
Cronet HTTP library, check out [`package:cronet_http`][cronet-http-pub]
74+
([source on GitHub][cronet-http-src]).
75+
7276
## Constraints and limitations
7377

7478
Keep these general considerations and limitations in mind when working with
@@ -85,27 +89,32 @@ Watch out for two common scenarios:
8589
This can lead to deadlocks if a blocked Java thread waits for a blocked
8690
Dart thread.
8791

92+
To learn more, consult the [JNIgen threading guide][jnigen-threading-doc].
93+
8894
### Lifecycle of Java objects
8995

9096
JNI wrappers use Java global references.
9197
There is a hard limit of 50,000 active references.
9298
Call `.release()` or use `.using()` blocks to prevent memory leaks.
9399
Use `WeakReference` to break reference cycles between Dart and Java GCs
94-
when implementing interfaces.
100+
when implementing interfaces, as shown in the
101+
[JNI object lifecycle guide][jnigen-lifecycle-doc].
95102

96103
### JVM runtime type checks
97104

98105
JNI wrappers are Dart extension types that compile down to `JObject`
99106
at runtime, so Dart's native `is` and `as` keywords don't check the Java
100107
runtime type.
101-
Use `x.isA(Foo.type)` and `x.as(Foo.type)` instead.
108+
Use `x.isA(Foo.type)` and `x.as(Foo.type)` instead, as shown in the
109+
[Java runtime types guide][jnigen-runtime-types-doc].
102110

103111
### General debugging
104112

105113
Tracking down JNI memory allocation bugs like `DoubleReleaseError`
106114
and `UseAfterReleaseError` can be difficult.
107115
Set `Jni.captureStackTraceOnRelease = true` to log stack traces
108-
and help trace leaks.
116+
and help trace leaks, as explained in the
117+
[JNIgen debugging guide][jnigen-debugging-doc].
109118

110119
## Resources
111120

@@ -118,7 +127,13 @@ refer to the following resources:
118127

119128
[jnigen-pub]: {{site.pub-pkg}}/jnigen
120129
[jni-pub]: {{site.pub-pkg}}/jni
130+
[cronet-http-pub]: {{site.pub-pkg}}/cronet_http
131+
[cronet-http-src]: https://github.com/dart-lang/http/tree/master/pkgs/cronet_http
121132
[jnigen-examples]: https://github.com/dart-lang/native/tree/main/pkgs/jnigen/example
122133
[permissions-demo]: {{site.repo.demos}}/tree/main/native_interop_demos/permissions_plugin
123134
[toast-demo]: {{site.repo.demos}}/tree/main/native_interop_demos/android_toast_demo
124135
[run-on-platform-thread]: {{site.api}}/flutter/dart-ui/runOnPlatformThread.html
136+
[jnigen-threading-doc]: https://github.com/dart-lang/native/blob/main/pkgs/jnigen/doc/threading.md
137+
[jnigen-lifecycle-doc]: https://github.com/dart-lang/native/blob/main/pkgs/jnigen/doc/lifecycle.md
138+
[jnigen-runtime-types-doc]: https://github.com/dart-lang/native/blob/main/pkgs/jnigen/doc/java_runtime_types.md
139+
[jnigen-debugging-doc]: https://github.com/dart-lang/native/blob/main/pkgs/jnigen/doc/debugging.md

0 commit comments

Comments
 (0)