Dart Finalizable用法及代碼示例

不應過早完成的對象的標記接口。

任何具有includes Finalizable 的靜態類型的局部變量都保證是活動的，直到執行退出該變量在範圍內的代碼塊。

類型 includes Finalizable 如果有的話

• 該類型是 Finalizable 的非 Never 子類型，或
• 類型是 T? 或 FutureOr<T> 其中 T 包括 Finalizable 。

換句話說，當一個對象被這樣的變量引用時，它保證not被認為是不可達的，並且變量本身在其作用域的整個持續時間內被認為是活動的，即使在它最後一次引用之後也是如此。

Without this marker interface on the variable's type, a variable's value might be garbage collected before the surrounding scope has been completely executed, as long as the variable is definitely not referenced again. That can, in turn, trigger a NativeFinalizer to perform a callback. When the variable's type includes Finalizable, The NativeFinalizer callback is prevented from running until the current code using that variable is complete.

例如，finalizable 在 someNativeCall 執行期間保持活動狀態：

void myFunction() {
  final finalizable = MyFinalizable(Pointer.fromAddress(0));
  someNativeCall(finalizable.nativeResource);
}

void someNativeCall(Pointer nativeResource) {
  // ..
}

class MyFinalizable implements Finalizable {
  final Pointer nativeResource;

  MyFinalizable(this.nativeResource);
}

實現Finalizable 的類上的方法在方法執行期間保持this 對象處於活動狀態。 The this value is treated like a local variable.

例如，this 在 myFunction 中的 someNativeCall 執行期間保持活動狀態：

class MyFinalizable implements Finalizable {
  final Pointer nativeResource;

  MyFinalizable(this.nativeResource);

  void myFunction() {
    someNativeCall(nativeResource);
  }
}

void someNativeCall(Pointer nativeResource) {
  // ..
}

在實現 Finalizable 的類上實現涉及可終結性的邏輯作為方法是一種很好的做法。

如果在聲明變量的塊作用域內創建了閉包，並且該閉包包含對該變量的任何引用，則隻要閉包對象存在，或者隻要此類閉包的主體正在執行，該變量就會保持活動狀態。

例如，finalizable 由閉包對象保持活動狀態，直到閉包主體結束：

void doSomething() {
  final resourceAction = myFunction();
  resourceAction(); // `finalizable` is alive until this call returns.
}

void Function() myFunction() {
  final finalizable = MyFinalizable(Pointer.fromAddress(0));
  return () {
    someNativeCall(finalizable.nativeResource);
  };
}

void someNativeCall(Pointer nativeResource) {
  // ..
}

class MyFinalizable implements Finalizable {
  final Pointer nativeResource;

  MyFinalizable(this.nativeResource);
}

隻有捕獲的變量才能通過閉包保持活動狀態，而不是所有變量。

例如，finalizable 不會被返回的閉包對象保持活動狀態：

void Function() myFunction() {
  final finalizable = MyFinalizable(Pointer.fromAddress(0));
  final nativeResource = finalizable.nativeResource;
  return () {
    someNativeCall(nativeResource);
  };
}

void someNativeCall(Pointer nativeResource) {
  // ..
}

class MyFinalizable implements Finalizable {
  final Pointer nativeResource;

  MyFinalizable(this.nativeResource);
}

如果從可終結對象中提取的資源超出了它所取自的可終結變量的範圍，則很可能是一個錯誤。

Finalizable 變量的行為也適用於異步函數。隻要任何代碼仍然可以在聲明變量的範圍內執行，或者在捕獲變量的閉包中執行，這些變量就會保持活動狀態，即使在執行期間存在異步延遲。

例如，finalizable 在 await someAsyncCall() 期間保持活動狀態：

Future<void> myFunction() async {
  final finalizable = MyFinalizable();
  await someAsyncCall();
}

Future<void> someAsyncCall() async {
  // ..
}

class MyFinalizable implements Finalizable {
  // ..
}

同樣在異步代碼中，如果從可終結對象中提取的資源超出了它所取自的可終結變量的範圍，則可能會出現錯誤。如果您必須從 Finalizable 中提取資源，則應通過 await 使用任何使用該資源的異步代碼來確保定義 Finalizable 的範圍比資源更長。

例如，this 一直保持活動狀態，直到 resource 不再在 useAsync1 中使用，但在 useAsync2 和 useAsync3 中不再使用：

class MyFinalizable {
  final Pointer<Int8> resource;

  MyFinalizable(this.resource);

  Future<int> useAsync1() async {
    return await useResource(resource);
  }

  Future<int> useAsync2() async {
    return useResource(resource);
  }

  Future<int> useAsync3() {
    return useResource(resource);
  }
}

/// Does not use [resource] after the returned future completes.
Future<int> useResource(Pointer<Int8> resource) async {
  return resource.value;
}

It is possible for an asynchronous function to stall at an await, such that the runtime system can see that there is no possible way for that await to complete. In that case, no code after the await will ever execute, including finally blocks, and the variable may be considered dead along with everything else.

如果您自己不打算讓變量保持活動狀態，請確保將可終結對象傳遞給其他函數，而不僅僅是其資源。

例如，finalizable 在運行到其作用域的末尾後不會被 myFunction 保持活動狀態，而 someAsyncCall 仍然可以繼續執行。但是，finalizable 由 someAsyncCall 本身保持活動狀態：

void myFunction() {
  final finalizable = MyFinalizable();
  someAsyncCall(finalizable);
}

Future<void> someAsyncCall(MyFinalizable finalizable) async {
  // ..
}

class MyFinalizable implements Finalizable {
  // ..
}