Function dart_sys::Dart_NewFinalizableHandle

pub unsafe extern "C" fn Dart_NewFinalizableHandle(
    object: Dart_Handle,
    peer: *mut c_void,
    external_allocation_size: isize,
    callback: Dart_HandleFinalizer
) -> Dart_FinalizableHandle

Allocates a finalizable handle for an object.

This handle has the lifetime of the current isolate group unless the object pointed to by the handle is garbage collected, in this case the VM automatically deletes the handle after invoking the callback associated with the handle. The handle can also be explicitly deallocated by calling Dart_DeleteFinalizableHandle.

If the object becomes unreachable the callback is invoked with the the peer as argument. The callback can be executed on any thread, will have an isolate group, but will not have a current isolate. The callback can only call Dart_DeletePersistentHandle or Dart_DeleteWeakPersistentHandle. This gives the embedder the ability to cleanup data associated with the object and clear out any cached references to the handle. All references to this handle after the callback will be invalid. It is illegal to call into the VM with any other Dart_* functions from the callback. If the handle is deleted before the object becomes unreachable, the callback is never invoked.

Requires there to be a current isolate.

\param object An object with identity. \param peer A pointer to a native object or NULL. This value is provided to callback when it is invoked. \param external_allocation_size The number of externally allocated bytes for peer. Used to inform the garbage collector. \param callback A function pointer that will be invoked sometime after the object is garbage collected, unless the handle has been deleted. A valid callback needs to be specified it cannot be NULL.

\return The finalizable handle or NULL. NULL is returned in case of bad parameters.