|
| 1 | +# 3 Layers in Dart Interop |
| 2 | + |
| 3 | +Dart native interop can be structured into three layers: |
| 4 | +* Low level interop |
| 5 | +* Dart-y API |
| 6 | +* SDK-tailoring |
| 7 | + |
| 8 | +## Layer 1: Low level interop |
| 9 | + |
| 10 | +The goal of this layer is to provide a no-compromise, high-performance layer to |
| 11 | +make non-Dart APIs and libraries accessible from Dart. This layer is designed to |
| 12 | +be unopinionated, allowing threading, data transfer, and isolate life cycle to |
| 13 | +be built upon it. The APIs provided and generated are very thin Dart wrappers |
| 14 | +around the native APIs. They favor zero-cost abstractions such as [extension types][extension-types]. |
| 15 | +While using this layer directly offers the most possibilities, it can lead to |
| 16 | +writing creole[^1] and presents footguns regarding memory management, threading, and |
| 17 | +the [isolate and VM life cycle][isolate-lifecycle]. |
| 18 | + |
| 19 | +**Technologies in this layer:** |
| 20 | +* Low-level SDK libraries for calling native code, such as [`dart:ffi`][dart-ffi] and |
| 21 | + [`dart:js_interop`][dart-js-interop]. |
| 22 | +* Code generators such as [FFIgen][ffigen], [JNIgen][jnigen], and [web_generator][web-generator]. |
| 23 | + |
| 24 | +**Design principles for tech in this layer:** |
| 25 | +* Performance comes first, usability second. |
| 26 | +* It is either implemented as a compiler backend or as a code generator built on |
| 27 | + top of one. |
| 28 | +* Zero-configuration should be used if possible. The generator technologies do |
| 29 | + not know how their code will be used, so it's preferable to generate code that |
| 30 | + permits multiple usage patterns. |
| 31 | + |
| 32 | +## Layer 2: Dart-y API |
| 33 | + |
| 34 | +The objective of this layer is to offer a Dart-y API that bridges the impedance |
| 35 | +mismatch between Dart and the target language. Technologies in this layer are |
| 36 | +opinionated and may make domain-specific choices about value conversions |
| 37 | +(shallow or deep), concurrency models, etc.. They might sacrifice performance |
| 38 | +for improved usability and may provide adapters for implementing Dart types such |
| 39 | +as `Map` and `List`. |
| 40 | + |
| 41 | +**Technologies in this layer:** |
| 42 | +* Hand-written Dart wrappers around a layer 1 API for C libraries, such as |
| 43 | + [SQLite3][sqlite3]. |
| 44 | +* [Pigeon][pigeon], which decides on a full serialization and concurrency model. |
| 45 | + |
| 46 | +**Design principles for tech in this layer:** |
| 47 | +* APIs should have the feel of Dart APIs. No layer 1 types should be exposed, |
| 48 | + and [Effective Dart][effective-dart] guidelines should be followed. |
| 49 | +* Users should not need to worry about the underlying native code. [Native |
| 50 | + finalizers][native-finalizers] should be used to free resources. |
| 51 | +* APIs should be structured to work with Dart's threading and isolate life |
| 52 | + cycle. |
| 53 | +* This layer is typically hand-crafted or built with a generator that has a high |
| 54 | + degree of configuration fidelity. |
| 55 | +* If different platforms offer non-identical feature sets, the preference is to |
| 56 | + publish platform-specific Dart APIs as packages and then build a |
| 57 | + platform-agnostic package on top of them. |
| 58 | + |
| 59 | +## Layer 3: SDK-tailoring (optional) |
| 60 | + |
| 61 | +This layer's purpose is to provide integration with specific SDKs built on Dart. |
| 62 | +This layer is optional. If a solution can be provided as a layer 2 solution, it |
| 63 | +should be, as this makes it reusable across multiple SDKs. |
| 64 | + |
| 65 | +**Technologies in this layer:** |
| 66 | +* [Flutter Plugin API][flutter-plugin-api]: Provides access to Flutter-defined elements such as [App |
| 67 | + lifecycle][app-lifecycle], [Android Context][android-context], etc. |
| 68 | +* [Flutter Plugins][flutter-plugins]: These can, for example, hide the Android Context from the API |
| 69 | + they expose to a Dart developer. |
| 70 | + |
| 71 | +## Cross-layer design principles |
| 72 | + |
| 73 | +Layer 2 solutions have the option to provide "native escape hatches" to layer 1. |
| 74 | +This allows layer 1 to give immediate access to new OS APIs while layer 2 is |
| 75 | +being updated. |
| 76 | + |
| 77 | +[^1]: A "creole" language, in this context, refers to code that is technically |
| 78 | + Dart but is written using the objects and patterns of the underlying native |
| 79 | + language (e.g., Objective-C). This creates a "mixed" language with its own |
| 80 | + learning curve and challenges, particularly around memory management and |
| 81 | + concurrency. |
| 82 | + |
| 83 | +[android-context]: https://developer.android.com/reference/android/content/Context |
| 84 | +[app-lifecycle]: https://api.flutter.dev/flutter/widgets/AppLifecycleListener-class.html |
| 85 | +[dart-ffi]: https://api.dart.dev/dart-ffi/ |
| 86 | +[dart-js-interop]: https://api.dart.dev/dart-js_interop/ |
| 87 | +[effective-dart]: https://dart.dev/guides/language/effective-dart |
| 88 | +[extension-types]: https://dart.dev/language/extension-types |
| 89 | +[ffigen]: ../pkgs/ffigen/ |
| 90 | +[flutter-plugin-api]: https://docs.flutter.dev/packages-and-plugins/developing-packages |
| 91 | +[flutter-plugins]: https://docs.flutter.dev/packages-and-plugins/using-packages |
| 92 | +[isolate-lifecycle]: https://dart.dev/language/concurrency |
| 93 | +[jnigen]: ../pkgs/jnigen/ |
| 94 | +[native-finalizers]: https://api.dart.dev/dart-ffi/NativeFinalizer-class.html |
| 95 | +[pigeon]: https://pub.dev/packages/pigeon |
| 96 | +[sqlite3]: https://pub.dev/packages/sqlite3 |
| 97 | +[web-generator]: https://github.com/dart-lang/web/tree/main/web_generator |
0 commit comments