[breaking change] Add an nullable nativeFree getter to Allocator

[HosseinYousefi]

Change Intent

Add a nullable nativeFree getter to Allocator to ease working with native finalizers.

Justification

This would simplify the API for adding native finalizers. The allocator argument can be defaulted to e.g. malloc, and methods using this allocator could attach native finalizers to the objects allocated using allocator.nativeFree if it's not null.

For example:

Int8List getRange(int start, int end, {Allocator allocator = malloc}) {
  RangeError.checkValidRange(start, end, length);
  final rangeLength = end - start;
  final buffer = allocator<JByteMarker>(rangeLength);
  Jni.env.GetByteArrayRegion(reference.pointer, start, rangeLength, buffer);
  return buffer.asTypedList(rangeLength, finalizer: allocator.nativeFree); // Passing nativeFree here
}

Impact

We provide some allocators in package:ffi, but a search here on GitHub shows that not many people implement Allocator themselves.

Older versions of package:ffi will stop working on newer SDKs, and we don't have a way of retroactively adding an SDK upper bound to those versions.

Most people should just be able to update their package:ffi, but apps that have pinned their deps might see compile errors.

Mitigation

package:ffi's MallocAllocator and CallocAllocator already have nativeFree getters.

We can safely add Pointer<NativeFinalizerFunction>? get nativeFree => null to all the existing Allocator subclasses that have a no-op free like Arena.

Alternatives Considered

We could introduce a NativeFreeableAllocator implements Allocator that has a nativeFree getter, and this was the original design for this PR: dart-archive/ffi#203

However @lrhn raised some issues with this design here and here.

Change Timeline

No response

Associated CLs

No response

[dcharkes]

Pointer<NativeFinalizerFunction> get nativeFree => null

That should be either Pointer<NativeFinalizerFunction>? get nativeFree => null; or Pointer<NativeFinalizerFunction> get nativeFree => nullptr;

Impact

Older versions of package:ffi will stop working on newer SDKs, and we don't have a way of retroactively adding an SDK upper bound to those versions.

Most people should just be able to update their package:ffi, but apps that have pinned their deps might see compile errors.

[HosseinYousefi]

Original PR adding the nativeFree getter to package:ffi – dart-archive/ffi#203
Prior discussions: dart-lang/native#910

@dcharkes Thanks, edited the Impact section.

[itsjustkevin]

@vsmenon @leonsenft @Hixie breaking change request.

[Hixie]

no objection, sorry for the delay

[dcharkes]

Friendly holiday bump for @vsmenon and @leonsenft.

[vsmenon]

lgtm

[leonsenft]

lgtm

[itsjustkevin]

@HosseinYousefi this breaking change request has been approved