- Add different types for persistent and weak persistent handles

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
  *
  * Dart is a class-based programming language for creating structured
@@ skipping 158 matching lines @@
  * Dart_EnterScope) and go away when the current scope exits. Unless
  * otherwise indicated, callers should assume that all functions in
  * the Dart embedding api return local handles.
  *
  * Persistent handles are allocated within the current isolate. They
  * can be used to store objects across scopes. Persistent handles have
  * the lifetime of the current isolate unless they are explicitly
  * deallocated (see Dart_DeletePersistentHandle).
  */
 typedef struct _Dart_Handle* Dart_Handle;
+typedef struct _Dart_PersistentHandle* Dart_PersistentHandle;
+typedef struct _Dart_WeakPersistentHandle* Dart_WeakPersistentHandle;
 
-typedef void (*Dart_WeakPersistentHandleFinalizer)(Dart_Handle handle,
-                                                   void* peer);
+typedef void (*Dart_WeakPersistentHandleFinalizer)(
+    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 162 matching lines @@
  * This is equivalent to using the triple-equals (===) operator.
  *
  * \param obj1 An object to be compared.
  * \param obj2 An object to be compared.
  *
  * \return True if the objects are identically equal.  False otherwise.
  */
 DART_EXPORT bool Dart_IdentityEquals(Dart_Handle obj1, Dart_Handle obj2);
 
 /**
+ * Allocates a handle in the current scope from a persistent handle.
+ */
+DART_EXPORT Dart_Handle Dart_HandleFromPersistent(Dart_PersistentHandle object);
+
+/**
+ * Allocates a handle in the current scope from a weak persistent handle.
+ */
+DART_EXPORT Dart_Handle Dart_HandleFromWeakPersistent(
+    Dart_WeakPersistentHandle object);
+
+/**
  * Allocates a persistent handle for an object.
  *
  * This handle has the lifetime of the current isolate unless it is
  * explicitly deallocated by calling Dart_DeletePersistentHandle.
  *
  * Requires there to be a current isolate.
  */
-DART_EXPORT Dart_Handle Dart_NewPersistentHandle(Dart_Handle object);
+DART_EXPORT Dart_PersistentHandle Dart_NewPersistentHandle(Dart_Handle object);
 
 /**
  * Deallocates a persistent handle.
  *
  * Requires there to be a current isolate.
  */
-DART_EXPORT void Dart_DeletePersistentHandle(Dart_Handle object);
+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_DeletePersistentHandle.
  *
  * 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 callback A function pointer that will be invoked sometime
  *   after the object is garbage collected.
  *
  * \return Success if the weak persistent handle was
  *   created. Otherwise, returns an error.
  */
-DART_EXPORT Dart_Handle Dart_NewWeakPersistentHandle(
+DART_EXPORT Dart_WeakPersistentHandle Dart_NewWeakPersistentHandle(
     Dart_Handle object,
     void* peer,
     Dart_WeakPersistentHandleFinalizer callback);
 
-/**
- * Is this object a weak persistent handle?
- *
- * Requires there to be a current isolate.
- */
-DART_EXPORT bool Dart_IsWeakPersistentHandle(Dart_Handle object);
+DART_EXPORT void Dart_DeleteWeakPersistentHandle(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_DeletePersistentHandle.
  *
  * 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 callback A function pointer that will be invoked sometime
  *   after the object is garbage collected.
  *
  * \return Success if the prologue weak persistent handle was created.
  *   Otherwise, returns an error.
  */
-DART_EXPORT Dart_Handle Dart_NewPrologueWeakPersistentHandle(
+DART_EXPORT Dart_WeakPersistentHandle Dart_NewPrologueWeakPersistentHandle(
     Dart_Handle object,
     void* peer,
     Dart_WeakPersistentHandleFinalizer callback);
 
 /**
  * Is this object a prologue weak persistent handle?
  *
  * Requires there to be a current isolate.
  */
-DART_EXPORT bool Dart_IsPrologueWeakPersistentHandle(Dart_Handle object);
+DART_EXPORT bool Dart_IsPrologueWeakPersistentHandle(
+    Dart_WeakPersistentHandle object);
 
 /**
  * Constructs a set of weak references from the Cartesian product of
  * the objects in the key set and the objects in values set.
  *
  * \param keys A set of object references.  These references will be
  *   considered weak by the garbage collector.
  * \param num_keys the number of objects in the keys set.
  * \param values A set of object references.  These references will be
  *   considered weak by garbage collector unless any object reference
  *   in 'keys' is found to be strong.
  * \param num_values the size of the values set
  *
  * \return Success if the weak reference set could be created.
  *   Otherwise, returns an error handle.
  */
-DART_EXPORT Dart_Handle Dart_NewWeakReferenceSet(Dart_Handle* keys,
-                                                 intptr_t num_keys,
-                                                 Dart_Handle* values,
-                                                 intptr_t num_values);
+DART_EXPORT Dart_Handle Dart_NewWeakReferenceSet(
+    Dart_WeakPersistentHandle* keys,

[Anton Muhin, 2013/05/27 15:45:49]

there was one fancy trick in our code which currently not applicable: we need to
render some weak persistent handles as strong for GC.  We did it by creating a
set with strong persistent handle.

I implemented trivial workaround for now: I create a weak persistent handle for
an object held by strong persistent handle, but if we can direct this case in
API directly, that'd be great.

One simple approach would be either add a function or add a special semantics
for references set with empty key sets.

[Ivan Posva, 2013/05/28 21:12:20]

I am not sure I understand your usage of this API function, but to me it sounds
like this:
Occasionally you have a bunch of weak handles, which need to be preserved during
a GC. You used to create one strong persistent handle, use that as the "keys"
and the to-be-preserved weak handles as the values. Do I understand that
correctly?

If that is the case, then I suggest that you create a weak persistent handle
using Dart_True for each of your isolates. Keep this weak persistent handle
around, so that you can pass it as the key. I am not sure, but it sort of sounds
like you are already doing something similar.

[Anton Muhin, 2013/05/29 07:43:13]

Yes, that's exactly what we do: weak persistent handle to always reachable
object.

On 2013/05/28 21:12:20, Ivan Posva wrote:

+    intptr_t num_keys,
+    Dart_WeakPersistentHandle* values,
+    intptr_t num_values);
 
 // --- Garbage Collection Callbacks ---
 
 /**
  * Callbacks signal the beginning and end of a garbage collection.
  *
  * These signals are intended to be used by the embedder to manage the
  * lifetime of native objects with a managed object peer.
  */
 
@@ skipping 1283 matching lines @@
  * \param type The type of the data array.
  * \param value A data array. This array must not move.
  * \param length The length of the data array (length in type units).
  * \param peer An external pointer to associate with this array.
  *
  * \return The TypedData object if no error occurs. Otherwise returns
  *   an error handle. The TypedData object is returned in a
  *   WeakPersistentHandle which needs to be deleted in the specified callback
  *   using Dart_DeletePersistentHandle.
  */
-DART_EXPORT Dart_Handle Dart_NewExternalTypedData(
-    Dart_TypedData_Type type,
-    void* data,
-    intptr_t length,
-    void* peer,
-    Dart_WeakPersistentHandleFinalizer callback);
-
-/**
- * Retrieves the peer pointer associated with an external TypedData object.
- */
-DART_EXPORT Dart_Handle Dart_ExternalTypedDataGetPeer(Dart_Handle object,

[Anton Muhin, 2013/05/27 15:45:49]

there still should be a way to fetch peer object associated with external typed
data.

For now I use Dart_SetPeer/Dart_GetPeer, but I recall that assumption was they
are not used too much which might be not the case for typed data.

[Ivan Posva, 2013/05/28 21:12:20]

For now, please use Dart_SetPeer and Dart_GetPeer if you need to have access to
a peer value.

-                                                      void** peer);
+DART_EXPORT Dart_Handle Dart_NewExternalTypedData(Dart_TypedData_Type type,
+                                                  void* data,
+                                                  intptr_t length);
 
 /**
  * Acquires access to the internal data address of a TypedData object.
  *
  * \param object The typed data object whose internal data address is to
  *    be accessed.
  * \param type The type of the object is returned here.
  * \param data The internal data address is returned here.
  * \param len Size of the typed array is returned here.
  *
@@ skipping 844 matching lines @@
  *
  * \param object An object.
  * \param peer A value to store in the peer field.
  *
  * \return Returns an error if 'object' is a subtype of Null, num, or
  *   bool.
  */
 DART_EXPORT Dart_Handle Dart_SetPeer(Dart_Handle object, void* peer);
 
 #endif  // INCLUDE_DART_API_H_