dcharkes
commented
1 year ago Backend Implementation
@mraleph suggested to embed the resolution in kernel files and the Dart VM rather than let embedders do the resolution. This way we don't have to reimplement resolution in each embedder. Each embedder needs to provide the mapping as input to the kernel compiler instead. (This makes the first post obsolete.)
Dart API
@mraleph suggested to let assetId's default to library name.
If we combine that with our wish to make @Ffinatives more concise (https://github.com/dart-lang/sdk/issues/50097), and to do it in a non-breaking way, the Dart API would be as follows:
/// Annotation to be used for marking an external function as FFI native.
///
/// Example:
///
/// ```dart template:top
/// @FfiNative<Int64 Function(Int64, Int64)>('FfiNative_Sum', isLeaf:true)
/// external int sum(int a, int b);
/// ```
///
/// Calling such functions will throw an exception if no resolver
/// was set on the library or the resolver failed to resolve the name.
///
/// See `Dart_SetFfiNativeResolver` in `dart_api.h`
///
/// NOTE: This is an experimental feature and may change in the future.
@Since('2.14')
@Deprecated('Use Native instead.')
class FfiNative<T> {
final String nativeName;
final bool isLeaf;
const FfiNative(this.nativeName, {this.isLeaf: false});
}
/// Annotation to be used for marking an external function as native.
///
/// Example:
///
/// ```dart template:top
/// @Native<Int64 Function(Int64, Int64)>()
/// external int sum(int a, int b);
/// ```
///
/// Calling such function will try to resolve the [symbol] in
/// 1. the provided [asset],
/// 2. the native resolver set with `Dart_SetFfiNativeResolver` in
/// `dart_api.h`, and
/// 3. the current process.
///
/// Calling such function will throw an exception if the symbol fails to
/// resolve in all cases.
///
/// NOTE: This is an experimental feature and may change in the future.
@Since('2.19')
class Native<T> {
/// The [symbol] to be resolved.
///
/// If not specified, defaults to the annotated function name.
///
/// Example:
///
/// ```dart
/// @Native<Int64 Function(Int64, Int64)>()
/// external int sum(int a, int b);
/// ```
///
/// Example 2:
///
/// ```dart
/// @Native<Int64 Function(Int64, Int64)>(symbol: 'sum')
/// external int sum(int a, int b);
/// ```
///
/// The above two examples are identical.
///
/// Prefer omitting [symbol].
final String? symbol;
/// The [asset] in which [symbol] is resolved.
///
/// If not specified, defaults to [Asset] annotation on the `library`.
/// If [Asset] on library is omitted, defaults to library name.
///
/// Example (file `package:a/a.dart`):
///
/// ```dart
/// @Native<Int64 Function(Int64, Int64)>()
/// external int sum(int a, int b);
/// ```
///
/// Example 2 (file `package:a/b.dart`):
///
/// ```dart
/// @Asset('package:a/a.dart')
/// library;
///
/// @Native<Int64 Function(Int64, Int64)>()
/// external int sum(int a, int b);
/// ```
///
/// Example 3 (file `package:a/b.dart`):
///
/// ```dart
/// @Native<Int64 Function(Int64, Int64)>(asset: 'package:a/a.dart')
/// external int sum(int a, int b);
/// ```
///
/// The above three examples are identical.
///
/// Prefer using the library name as `Asset` over specifying it.
/// Prefer specifying [Asset] on `library` over specifying on [Native].
final String? asset;
/// Native function does not call back into Dart code or the Dart VM.
///
/// Leaf calls are faster than non-leaf calls.
final bool isLeaf;
const Native({
this.asset,
this.isLeaf: false,
this.symbol,
});
}
/// Annotation to be used for specifying the default asset on a library.
///
/// If no annotation is provided, defaults to library name.
///
/// Example (file `package:a/a.dart`):
///
/// ```dart
/// @Native<Int64 Function(Int64, Int64)>()
/// external int sum(int a, int b);
/// ```
///
/// Example 2 (file `package:a/b.dart`):
///
/// ```dart
/// @Asset('package:a/a.dart')
/// library;
///
/// @Native<Int64 Function(Int64, Int64)>()
/// external int sum(int a, int b);
/// ```
///
/// The above two examples are identical.
///
/// Prefer using the library name as `Asset` over specifying it.
@Since('2.19')
class Asset {
final String asset;
const Asset(
this.asset,
);
}cc @lrhn @mraleph @mkustermann @mit-mit
Some questions to answer:
- Do we want the optional
assetonNative? If not, we force people to write an extra file if they want to resolve in multiple assets. - Do things need different names for annotations or fields?
mkustermann
lrhn
mraleph
blaugold
eseidel
Dampfwalze
Given the following Dart code.
Update 2022-10-19: We're taking a different approach. Below is no longer applicable.
The embedder can register a resolver function to look up symbols in assets.The Dart standalone embedder can receive a mapping fromassettopaththrough a flag. (As follow up, this mapping will be provided automatically by packages which want to bundle native assets.)Internal design doc