[vm/ffi] API: Pointer.asExternalTypedData as extension method

[dcharkes]

Split off #37773 to keep the CL sizes manageable.

These methods would be better exposed as extension methods:

• Pointer.asExternalTypedData (but keep original)

  /// Creates an *external* typed data array backed by this pointer.
  ///
  /// The typed data array returned is only valid for as long as the backing
  /// [Pointer]. Accessing any element of the type data array after this
  /// [Pointer] has been [Pointer.free()]d will cause undefined behavior.
  ///
  /// Since [Pointer]s do not know their length, the size of the typed data is
  /// controlled by `count`, in units of the size of the native type for this
  /// [Pointer] (similarly to [Pointer.allocate]).
  ///
  /// The kind of TypedData produced depends on the native type:
  ///
  ///   Pointer<Int8> -> Int8List
  ///   Pointer<Uint8> -> Uint8List
  ///   etc. up to Int64/Uint64
  ///   Pointer<IntPtr> -> Int32List/Int64List depending on platform word size
  ///   Pointer<Float> -> Float32List
  ///   Pointer<Double> -> Float64List
  ///
  /// Creation of a [Uint8ClampedList] is not supported. Creation of a typed
  /// data from a [Pointer] to any other native type is not supported.
  ///
  /// The pointer must be aligned to a multiple of the native type's size.
  //
  // TODO(37773): Use extension methods to articulate more precise return types.
  // We should still keep this member though as a generic way to access a
  // Pointer of unknown type.
  external TypedData asExternalTypedData({int count: 1});

@sjindel-google how did you envision this? Instance methods shadow extension methods.

[sjindel-google]

We would change the name of the instance method to asExternalTypedDataDynamic or such.

[dcharkes]

(1) Using extension methods and a generic method:

• pro: precise return type.
• con: API pollution with both the precise and the dynamic method.
• con: dynamic method has imprecise receiver type, throws on non-integer type arguments.

(2) Using only extension methods:

• pro: precise return type.
• pro: precise receiver type.
• pro: only one (extension) method (per Pointer type argument) in the API.
• con: users (or package:ffi) have to write the generic one by hand if they want it.

(3) Using only generic method (current situation):

• pro: only one method in API.
• con: imprecise return type.
• con: imprecise receiver type, throws on non-integer type arguments.

@sjindel-google I don't like the API pollution of option 1.

I think option 2 is a better option.

[sjindel-google]

I'm in favor or #1 or #3. The ability to manipulate a pointer generically is one of the advantages of asExternalTypedData.

[dcharkes]

I'm fine with option 3 as well, keeping the return type generic.

We should still move it to an extension method on Pointer<_NativeInteger> so that the receiver type is precise.

(3b) Generic extension method on Pointer<_NativeInteger>:

• pro: only one method in API.
• pro: precise receiver type.
• con: imprecise return type.

[sjindel-google]

Could you elaborate on your concern with two versions of asExternalTypedData from solution #1?

[dcharkes]

Option 1:

final Pointer<Int8> p = fromSomewhere();
final td = p.// x

x: Here we would have two methods with exactly the same functionality with slightly different names, but one with a more precise return type. I think that is confusing from a public API point of view.

Option 3b:

If a user wants the more precise return type, (s)he can always write:

final Pointer<Int8> p = fromSomewhere();
final Int8List td = p.asExternalTypedData();

Or option 2:

If the user wants to have a generic one, (s)he can always write a wrapper.

Both option 3b and 2 do not confuse/penalize the user that wants no generic version or no precise return type.

[sjindel-google]

x: Here we would have two methods with exactly the same functionality with slightly different names, but one with a more precise return type. I think that is confusing from a public API point of view.

But, they don't have the exact same functionality. One is slower but can be called on a generic pointer. If the function is named like asExternalTypedDataDynamic, I don't see how that's confusing.

[dcharkes]

/cc @lrhn @mkustermann

[lrhn]

I'd make the count argument positional instead of named.

Providing an Int8List (or any typed-data view) means that you can extract its ByteBuffer buffer and then view it as, e.g., a Uint32List (maybe subject to alignment?).
Consider whether you actually want to support this. If so, this is fine. If not, maybe don't make it return an Int8List, just a List<int> which happens to truncate on store. (Do not make it an Int8List which throws if you extract the buffer, or give a buffer which throws on any of the asUintXList() methods).

Going through the buffer seems like the only way to get, say, a Uint8ClampedList, unless you add an extra method to Pointer<Uint8>.

Alternatively, you can provide a function to go directly to the buffer:

Pointer<Int8> p = fromSomewhere();
ByteBuffer buffer = p.asExternalTypedDataBuffer(count); // count * Int8.size bytes of buffer.
Int8List list = buffer.asInt8List();
// perhaps with shorthand:
Int8List alsoList = p.asExternalTypedDataList(count); // count elements.