Auto delete persistent weak handles during finalization after invoking the callback associated with…

runtime/include/dart_api.h

 /*
  * Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
  * for details. All rights reserved. Use of this source code is governed by a
  * BSD-style license that can be found in the LICENSE file.
  */
 
 #ifndef INCLUDE_DART_API_H_
 #define INCLUDE_DART_API_H_
 
 /** \mainpage Dart Embedding API Reference
@@ skipping 191 matching lines @@
  * The type Dart_Handle represents a handle (both local and persistent).
  * The type Dart_PersistentHandle is a Dart_Handle and it is used to
  * document that a persistent handle is expected as a parameter to a call
  * or the return value from a call is a persistent handle.
  */
 typedef struct _Dart_Handle* Dart_Handle;
 typedef Dart_Handle Dart_PersistentHandle;
 typedef struct _Dart_WeakPersistentHandle* Dart_WeakPersistentHandle;
 
 typedef void (*Dart_WeakPersistentHandleFinalizer)(
-    Dart_Isolate isolate,
+    void* isolate_callback_data,
     Dart_WeakPersistentHandle handle,
     void* peer);
 typedef void (*Dart_PeerFinalizer)(void* peer);
 
 /**
  * Is this an error handle?
  *
  * Requires there to be a current isolate.
  */
 DART_EXPORT bool Dart_IsError(Dart_Handle handle);
@@ skipping 205 matching lines @@
 /**
  * Deallocates a persistent handle.
  *
  * Requires there to be a current isolate.
  */
 DART_EXPORT void Dart_DeletePersistentHandle(Dart_PersistentHandle object);
 
 /**
  * Allocates a weak persistent handle for an object.
  *
- * This handle has the lifetime of the current isolate unless it is
- * explicitly deallocated by calling Dart_DeleteWeakPersistentHandle.
+ * This handle has the lifetime of the current isolate 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_DeleteWeakPersistentHandle.
  *
  * If the object becomes unreachable the callback is invoked with the weak
  * persistent handle and the peer as arguments. This gives the native code the
- * ability to cleanup data associated with the object and to delete the weak
- * persistent handle. It is illegal to call into the VM from the callback,
- * except to delete the weak persistent handle. If the handle is deleted before
- * the object becomes unreachable, the callback is never invoked.
+ * 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 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.
  * \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 Success if the weak persistent handle was
  *   created. Otherwise, returns an error.
  */
 DART_EXPORT Dart_WeakPersistentHandle Dart_NewWeakPersistentHandle(
     Dart_Handle object,
     void* peer,
     intptr_t external_allocation_size,
     Dart_WeakPersistentHandleFinalizer callback);
 
 DART_EXPORT void Dart_DeleteWeakPersistentHandle(
     Dart_Isolate isolate,
     Dart_WeakPersistentHandle object);
 
 /**
  * Allocates a prologue weak persistent handle for an object.
  *
  * Prologue weak persistent handles are similar to weak persistent
  * handles but exhibit different behavior during garbage collections
  * that invoke the prologue and epilogue callbacks.  While weak
  * persistent handles always weakly reference their referents,
  * prologue weak persistent handles weakly reference their referents
  * only during a garbage collection that invokes the prologue and
  * epilogue callbacks.  During all other garbage collections, prologue
  * weak persistent handles strongly reference their referents.
  *
- * This handle has the lifetime of the current isolate unless it is
- * explicitly deallocated by calling Dart_DeleteWeakPersistentHandle.
+ * This handle has the lifetime of the current isolate 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_DeleteWeakPersistentHandle.
+ *
+ * If the object becomes unreachable the callback is invoked with the weak
+ * persistent handle and the peer as arguments. This gives the native code 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 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.
  * \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 Success if the prologue weak persistent handle was created.
  *   Otherwise, returns an error.
  */
 DART_EXPORT Dart_WeakPersistentHandle Dart_NewPrologueWeakPersistentHandle(
     Dart_Handle object,
     void* peer,
     intptr_t external_allocation_size,
     Dart_WeakPersistentHandleFinalizer callback);
 
@@ skipping 2014 matching lines @@
  * NOTE: If multiple callbacks with the same name are registered, only the
  * last callback registered will be remembered.
  */
 DART_EXPORT void Dart_RegisterRootServiceRequestCallback(
     const char* name,
     Dart_ServiceRequestCallback callback,
     void* user_data);
 
 
 #endif  /* INCLUDE_DART_API_H_ */  /* NOLINT */