[vm/ffi] Add Since annotations to dart:ffi

Closes: #48711 Change-Id: Iac0bcecdf81b02bcb2feb746aa94a1bef6caf600 Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/240045 Reviewed-by: Lasse Nielsen <[email protected]> Commit-Queue: Daco Harkes <[email protected]>
dart-lang · Apr 12, 2022 · 5ca6eec · 5ca6eec
1 parent 02fc734
commit 5ca6eec
Show file tree

Hide file tree

Showing 18 changed files with 118 additions and 56 deletions.
diff --git a/pkg/front_end/testcases/general/ffi_sample.dart.weak.expect b/pkg/front_end/testcases/general/ffi_sample.dart.weak.expect
@@ -40,7 +40,7 @@ constants  {
 
 Constructor coverage from constants:
 org-dartlang-testcase:///ffi_sample.dart:
-- Double. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:114:9)
-- _NativeDouble. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:34:9)
+- Double. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:115:9)
+- _NativeDouble. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:35:9)
 - NativeType. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:12:9)
 - Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general/ffi_sample.dart.weak.modular.expect b/pkg/front_end/testcases/general/ffi_sample.dart.weak.modular.expect
@@ -40,7 +40,7 @@ constants  {
 
 Constructor coverage from constants:
 org-dartlang-testcase:///ffi_sample.dart:
-- Double. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:114:9)
-- _NativeDouble. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:34:9)
+- Double. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:115:9)
+- _NativeDouble. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:35:9)
 - NativeType. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:12:9)
 - Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general/ffi_sample.dart.weak.transformed.expect b/pkg/front_end/testcases/general/ffi_sample.dart.weak.transformed.expect
@@ -74,7 +74,7 @@ constants  {
 
 Constructor coverage from constants:
 org-dartlang-testcase:///ffi_sample.dart:
-- Double. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:114:9)
-- _NativeDouble. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:34:9)
+- Double. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:115:9)
+- _NativeDouble. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:35:9)
 - NativeType. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:12:9)
 - Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd/ffi_sample.dart.strong.expect b/pkg/front_end/testcases/nnbd/ffi_sample.dart.strong.expect
@@ -34,7 +34,7 @@ constants  {
 
 Constructor coverage from constants:
 org-dartlang-testcase:///ffi_sample.dart:
-- Double. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:114:9)
-- _NativeDouble. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:34:9)
+- Double. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:115:9)
+- _NativeDouble. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:35:9)
 - NativeType. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:12:9)
 - Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd/ffi_sample.dart.strong.transformed.expect b/pkg/front_end/testcases/nnbd/ffi_sample.dart.strong.transformed.expect
@@ -65,7 +65,7 @@ constants  {
 
 Constructor coverage from constants:
 org-dartlang-testcase:///ffi_sample.dart:
-- Double. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:114:9)
-- _NativeDouble. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:34:9)
+- Double. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:115:9)
+- _NativeDouble. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:35:9)
 - NativeType. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:12:9)
 - Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd/ffi_sample.dart.weak.expect b/pkg/front_end/testcases/nnbd/ffi_sample.dart.weak.expect
@@ -34,7 +34,7 @@ constants  {
 
 Constructor coverage from constants:
 org-dartlang-testcase:///ffi_sample.dart:
-- Double. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:114:9)
-- _NativeDouble. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:34:9)
+- Double. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:115:9)
+- _NativeDouble. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:35:9)
 - NativeType. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:12:9)
 - Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd/ffi_sample.dart.weak.modular.expect b/pkg/front_end/testcases/nnbd/ffi_sample.dart.weak.modular.expect
@@ -34,7 +34,7 @@ constants  {
 
 Constructor coverage from constants:
 org-dartlang-testcase:///ffi_sample.dart:
-- Double. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:114:9)
-- _NativeDouble. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:34:9)
+- Double. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:115:9)
+- _NativeDouble. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:35:9)
 - NativeType. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:12:9)
 - Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd/ffi_sample.dart.weak.transformed.expect b/pkg/front_end/testcases/nnbd/ffi_sample.dart.weak.transformed.expect
@@ -65,7 +65,7 @@ constants  {
 
 Constructor coverage from constants:
 org-dartlang-testcase:///ffi_sample.dart:
-- Double. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:114:9)
-- _NativeDouble. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:34:9)
+- Double. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:115:9)
+- _NativeDouble. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:35:9)
 - NativeType. (from org-dartlang-sdk:///sdk/lib/ffi/native_type.dart:12:9)
 - Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/runtime/tools/ffi/sdk_lib_ffi_generator.dart b/runtime/tools/ffi/sdk_lib_ffi_generator.dart
@@ -24,12 +24,13 @@ const configuration = [
   Config("Uint16", "int", "Uint16List", 2),
   Config("Uint32", "int", "Uint32List", 4),
   Config("Uint64", "int", "Uint64List", 8),
-  Config("IntPtr", "int", kDoNotEmit, kIntPtrElementSize),
   Config("Float", "double", "Float32List", 4),
   Config("Double", "double", "Float64List", 8),
-  Config("Bool", "bool", kDoNotEmit, 1),
+  Config("Bool", "bool", kDoNotEmit, 1, since: Version(2, 15)),
 ];
 
+const arrayVersion = Version(2, 13);
+
 //
 // Generator.
 //
@@ -81,8 +82,6 @@ void generatePublicExtension(
   final elementSize = config.elementSize;
 
   final bits = sizeOfBits(elementSize);
-  // final sizeInBytes =
-  // "${sizeOf(elementSize)} byte${elementSize != 1 ? "s" : ""}";
 
   String property;
   if (_isInt(nativeType)) {
@@ -178,9 +177,10 @@ $alignment  external $typedListType asTypedList(int length);
 """;
 
   if (container == "Pointer") {
+    final since = config.since?.sinceAnnotation ?? '';
     buffer.write("""
 /// Extension on [Pointer] specialized for the type argument [$nativeType].
-extension ${nativeType}Pointer on Pointer<$nativeType> {
+$since extension ${nativeType}Pointer on Pointer<$nativeType> {
   /// The $property at [address].
 $platform$truncate$alignment  external $dartType get value;
 
@@ -197,9 +197,11 @@ $asTypedList
 
 """);
   } else {
+    final since =
+        Version.latest(config.since, arrayVersion)?.sinceAnnotation ?? '';
     buffer.write("""
 /// Bounds checking indexing methods on [Array]s of [$nativeType].
-extension ${nativeType}Array on Array<$nativeType> {
+$since extension ${nativeType}Array on Array<$nativeType> {
   external $dartType operator [](int index);
 
   external void operator []=(int index, $dartType value);
@@ -288,32 +290,11 @@ void generateFooter(StringBuffer buffer) {
 bool _isInt(String type) => type.startsWith("Int") || type.startsWith("Uint");
 bool _isSigned(String type) => type.startsWith("Int");
 
-String sizeOf(int size) {
-  switch (size) {
-    case kIntPtrElementSize:
-      return "4 or 8";
-    default:
-      return "$size";
-  }
-}
+String sizeOf(int size) => "$size";
 
-String sizeOfBits(int size) {
-  switch (size) {
-    case kIntPtrElementSize:
-      return "32 or 64";
-    default:
-      return "${size * 8}";
-  }
-}
+String sizeOfBits(int size) => "${size * 8}";
 
-String sizeOfIntPtrSize(int size) {
-  switch (size) {
-    case kIntPtrElementSize:
-      return "_intPtrSize";
-    default:
-      return "$size";
-  }
-}
+String sizeOfIntPtrSize(int size) => "$size";
 
 String bracketOr(String input) {
   if (input.contains("or")) {
@@ -348,9 +329,32 @@ class Config {
   final String dartType;
   final String typedListType;
   final int elementSize;
+  final Version? since;
   const Config(
-      this.nativeType, this.dartType, this.typedListType, this.elementSize);
+      this.nativeType, this.dartType, this.typedListType, this.elementSize,
+      {Version? since})
+      : since = since;
 }
 
 const String kDoNotEmit = "donotemit";
-const int kIntPtrElementSize = -1;
+
+class Version {
+  final int major;
+  final int minor;
+
+  const Version(this.major, this.minor);
+
+  @override
+  String toString() => '$major.$minor';
+
+  static Version? latest(Version? a, Version? b) {
+    if (a == null) return b;
+    if (b == null) return a;
+    if (a.major > b.major) return a;
+    if (b.major > a.major) return b;
+    if (a.minor > b.minor) return a;
+    return b;
+  }
+
+  String get sinceAnnotation => "@Since('$this')";
+}
diff --git a/sdk/lib/ffi/abi.dart b/sdk/lib/ffi/abi.dart
@@ -14,6 +14,7 @@ part of dart.ffi;
 /// The Dart VM can run on a variety of operating systems and architectures.
 /// Supported ABIs are represented by `Abi` objects.
 /// See [values] for all the supported ABIs.
+@Since('2.16')
 class Abi {
   /// The application binary interface for Android on the Arm architecture.
   static const androidArm = _androidArm;

diff --git a/sdk/lib/ffi/abi_specific.dart b/sdk/lib/ffi/abi_specific.dart
@@ -43,13 +43,15 @@ part of dart.ffi;
 ///   const UintPtr();
 /// }
 /// ```
+@Since('2.16')
 class AbiSpecificInteger extends NativeType {
   const AbiSpecificInteger();
 }
 
 /// Mapping for a subtype of [AbiSpecificInteger].
 ///
 /// See documentation on [AbiSpecificInteger].
+@Since('2.16')
 class AbiSpecificIntegerMapping {
   final Map<Abi, NativeType> mapping;
 

diff --git a/sdk/lib/ffi/allocation.dart b/sdk/lib/ffi/allocation.dart
@@ -5,6 +5,7 @@
 part of dart.ffi;
 
 /// Manages memory on the native heap.
+@Since('2.12')
 abstract class Allocator {
   /// This interface is meant to be implemented, not extended or mixed in.
   Allocator._() {
@@ -28,6 +29,7 @@ abstract class Allocator {
 }
 
 /// Extension on [Allocator] to provide allocation with [NativeType].
+@Since('2.12')
 extension AllocatorAlloc on Allocator {
   /// Allocates `sizeOf<T>() * count` bytes of memory using
   /// `allocator.allocate`.

diff --git a/sdk/lib/ffi/c_type.dart b/sdk/lib/ffi/c_type.dart
@@ -21,6 +21,7 @@ part of dart.ffi;
 /// Dart code.
 /// It occurs only in native type signatures and as annotation on [Struct] and
 /// [Union] fields.
+@Since('2.17')
 @AbiSpecificIntegerMapping({
   Abi.androidArm: Uint8(),
   Abi.androidArm64: Uint8(),
@@ -57,6 +58,7 @@ class Char extends AbiSpecificInteger {
 /// Dart code.
 /// It occurs only in native type signatures and as annotation on [Struct] and
 /// [Union] fields.
+@Since('2.17')
 @AbiSpecificIntegerMapping({
   Abi.androidArm: Int8(),
   Abi.androidArm64: Int8(),
@@ -93,6 +95,7 @@ class SignedChar extends AbiSpecificInteger {
 /// Dart code.
 /// It occurs only in native type signatures and as annotation on [Struct] and
 /// [Union] fields.
+@Since('2.17')
 @AbiSpecificIntegerMapping({
   Abi.androidArm: Uint8(),
   Abi.androidArm64: Uint8(),
@@ -129,6 +132,7 @@ class UnsignedChar extends AbiSpecificInteger {
 /// Dart code.
 /// It occurs only in native type signatures and as annotation on [Struct] and
 /// [Union] fields.
+@Since('2.17')
 @AbiSpecificIntegerMapping({
   Abi.androidArm: Int16(),
   Abi.androidArm64: Int16(),
@@ -165,6 +169,7 @@ class Short extends AbiSpecificInteger {
 /// Dart code.
 /// It occurs only in native type signatures and as annotation on [Struct] and
 /// [Union] fields.
+@Since('2.17')
 @AbiSpecificIntegerMapping({
   Abi.androidArm: Uint16(),
   Abi.androidArm64: Uint16(),
@@ -201,6 +206,7 @@ class UnsignedShort extends AbiSpecificInteger {
 /// Dart code.
 /// It occurs only in native type signatures and as annotation on [Struct] and
 /// [Union] fields.
+@Since('2.17')
 @AbiSpecificIntegerMapping({
   Abi.androidArm: Int32(),
   Abi.androidArm64: Int32(),
@@ -237,6 +243,7 @@ class Int extends AbiSpecificInteger {
 /// Dart code.
 /// It occurs only in native type signatures and as annotation on [Struct] and
 /// [Union] fields.
+@Since('2.17')
 @AbiSpecificIntegerMapping({
   Abi.androidArm: Uint32(),
   Abi.androidArm64: Uint32(),
@@ -274,6 +281,7 @@ class UnsignedInt extends AbiSpecificInteger {
 /// Dart code.
 /// It occurs only in native type signatures and as annotation on [Struct] and
 /// [Union] fields.
+@Since('2.17')
 @AbiSpecificIntegerMapping({
   Abi.androidArm: Int32(),
   Abi.androidArm64: Int64(),
@@ -311,6 +319,7 @@ class Long extends AbiSpecificInteger {
 /// Dart code.
 /// It occurs only in native type signatures and as annotation on [Struct] and
 /// [Union] fields.
+@Since('2.17')
 @AbiSpecificIntegerMapping({
   Abi.androidArm: Uint32(),
   Abi.androidArm64: Uint64(),
@@ -347,6 +356,7 @@ class UnsignedLong extends AbiSpecificInteger {
 /// Dart code.
 /// It occurs only in native type signatures and as annotation on [Struct] and
 /// [Union] fields.
+@Since('2.17')
 @AbiSpecificIntegerMapping({
   Abi.androidArm: Int64(),
   Abi.androidArm64: Int64(),
@@ -383,6 +393,7 @@ class LongLong extends AbiSpecificInteger {
 /// in Dart code.
 /// It occurs only in native type signatures and as annotation on [Struct] and
 /// [Union] fields.
+@Since('2.17')
 @AbiSpecificIntegerMapping({
   Abi.androidArm: Uint64(),
   Abi.androidArm64: Uint64(),
@@ -447,6 +458,7 @@ class IntPtr extends AbiSpecificInteger {
 /// Dart code.
 /// It occurs only in native type signatures and as annotation on [Struct] and
 /// [Union] fields.
+@Since('2.17')
 @AbiSpecificIntegerMapping({
   Abi.androidArm: Uint32(),
   Abi.androidArm64: Uint64(),
@@ -479,6 +491,7 @@ class UintPtr extends AbiSpecificInteger {
 /// Dart code.
 /// It occurs only in native type signatures and as annotation on [Struct] and
 /// [Union] fields.
+@Since('2.17')
 @AbiSpecificIntegerMapping({
   Abi.androidArm: Uint32(),
   Abi.androidArm64: Uint64(),
@@ -514,6 +527,7 @@ class Size extends AbiSpecificInteger {
 /// Dart code.
 /// It occurs only in native type signatures and as annotation on [Struct] and
 /// [Union] fields.
+@Since('2.17')
 @AbiSpecificIntegerMapping({
   Abi.androidArm: Uint32(),
   Abi.androidArm64: Uint32(),