Lazy peer API.

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 2593 matching lines @@
 DART_EXPORT void Dart_GetPprofSymbolInfo(void** buffer, int* buffer_size);
 
 typedef void (*Dart_FileWriterFunction)(const char* buffer, int64_t num_bytes);
 
 // Support for generating symbol maps for use by the Linux perf tool.
 DART_EXPORT void Dart_InitPerfEventsSupport(Dart_FileWriterFunction function);
 
 // Support for generating flow graph compiler debugging output into a file.
 DART_EXPORT void Dart_InitFlowGraphPrinting(Dart_FileWriterFunction function);
 
+// --- Peers ---
+
+/**

[cshapiro, 2012/09/15 01:23:41]

I will add a comment here that peers are intended for low-frequency use ONLY.

+ * Every heap allocated object has a lazily allocated field known as
+ * its peer.

[siva, 2012/09/14 00:03:46]

Do we really want to allow peer fields for every heap allocated object? e.g:
ints, doubles, bool etc.

In addition we already have a bunch of External* objects which seem to already
have corresponding native values, do these also get peer fields?

Will only some objects of a particular type have peer fields or do we except all
objects created of a particular type to have peer fields. I am trying to figure
out why somebody could not just extend NativeWrapper and store the peer value in
the native field.

[cshapiro, 2012/09/15 01:23:41]

I have limited this to types which are not subtypes of Null, num, and bool.

A subsequent revision of this facility will make use of unused words after an
object to store a pointer to a lazily allocated field structure which can
contain the peer value, hash code, and so forth.

Until this is finished some objects will have more than one "peer".  While
confusing, this should be a temporary condition.

+ */
+
+/**
+ * Returns the value of peer field in 'peer'.  Sets 'peer' to NULL and
+ * returns an error if the peer field has not been allocated.

[siva, 2012/09/14 00:03:46]

Why do you return an error if there is no peer field for an
object. If you set 'peer' to NULL and returned success that
would be an indication that the object does not have a peer.

Currently one has to make two calls:
  result = Dart_HasPeer(obj)
  if (result == success) {
    result = Dart_GetPeer(obj, peer);
    if (result == success) {
       do something;
    }
  }

Would be preferable if I could just make one call:

  result = Dart_GetPeer(obj, peer);
  if (result == success && *peer != NULL) {
    do something;
  }

[cshapiro, 2012/09/15 01:23:41]

I am confused.  You can use second form.  The alternative would be completely
hide the laziness in the first place.  I have been thinking that might be a
better way to go.

+ *
+ * \param object A heap allocated object.
+ * \param peer An out parameter that returns the value of the peer
+ *   field.
+ *
+ * \return Success if 'object' is heap allocated and has its peer
+ *   field allocated.
+ */
+DART_EXPORT Dart_Handle Dart_GetPeer(Dart_Handle object, void** peer);
+
+/**
+ * Sets or replaces the value in the peer field of 'object'.  If
+ * 'peer' is NULL the peer field is deallocated.

[siva, 2012/09/14 00:03:46]

I find the notion of deleting a peer field by calling
Dart_SetPeer with a NULL peer value a bit overloaded.

Why not have a Dart_[Remove | Delete]Peer entry point.

[cshapiro, 2012/09/15 01:23:41]

The peer field being deleted is an implementation detail.  I think it really
doesn't make a difference as the getter always returns NULL.

+ *
+ * \param object A heap allocated object.
+ * \param peer A value to store in the peer field.
+ *
+ * \return Success if 'object' is heap allocated.
+ */
+DART_EXPORT Dart_Handle Dart_SetPeer(Dart_Handle object, void* peer);
+
+/**
+ * Returns true if object has its peer field set.
+ */
+DART_EXPORT bool Dart_HasPeer(Dart_Handle object);

[siva, 2012/09/14 00:03:46]

This call would not be needed if we go with the suggestion above.

[cshapiro, 2012/09/15 01:23:41]

It's gone.  Done.

+
 #endif  // INCLUDE_DART_API_H_