- Modify dart_api.h to be a proper C 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.
+/*
+ * 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
  * web applications. This reference describes the Dart embedding api,
  * which is used to embed the Dart Virtual Machine within an
  * application.
@@ skipping 17 matching lines @@
 typedef unsigned __int8 uint8_t;
 typedef unsigned __int16 uint16_t;
 typedef unsigned __int32 uint32_t;
 typedef unsigned __int64 uint64_t;
 #if defined(DART_SHARED_LIB)
 #define DART_EXPORT DART_EXTERN_C __declspec(dllexport)
 #else
 #define DART_EXPORT DART_EXTERN_C
 #endif
 #else
-// __STDC_FORMAT_MACROS has to be defined before including <inttypes.h> to
-// enable platform independent printf format specifiers.
+/* __STDC_FORMAT_MACROS has to be defined before including <inttypes.h> to
+ * enable platform independent printf format specifiers. */
 #ifndef __STDC_FORMAT_MACROS
 #define __STDC_FORMAT_MACROS
 #endif
 #include <inttypes.h>
 #include <stdbool.h>
 #if __GNUC__ >= 4
 #if defined(DART_SHARED_LIB)
 #define DART_EXPORT DART_EXTERN_C __attribute__ ((visibility("default")))
 #else
 #define DART_EXPORT DART_EXTERN_C
 #endif
 #else
 #error Tool chain not supported.
 #endif
 #endif
 
 #include <assert.h>
 
-// --- Handles ---
+/* --- Handles --- */
 
 /**
  * An object reference managed by the Dart VM garbage collector.
  *
  * Because the garbage collector may move objects, it is unsafe to
  * refer to objects directly. Instead, we refer to objects through
  * handles, which are known to the garbage collector and updated
  * automatically when the object is moved. Handles should be passed
  * by value (except in cases like out-parameters) and should never be
  * allocated on the heap.
@@ skipping 204 matching lines @@
 
 /**
  * Produces a new unhandled exception error handle.
  *
  * Requires there to be a current isolate.
  *
  * \param exception An instance of a Dart object to be thrown.
  */
 DART_EXPORT Dart_Handle Dart_NewUnhandledExceptionError(Dart_Handle exception);
 
-// Deprecated.
-// TODO(turnidge): Remove all uses and delete.
+/* Deprecated. */
+/* TODO(turnidge): Remove all uses and delete. */
 DART_EXPORT Dart_Handle Dart_Error(const char* format, ...);
 
 /**
  * Propagates an error.
  *
  * If the provided handle is an unhandled exception error, this
  * function will cause the unhandled exception to be rethrown.  This
  * will proceeed in the standard way, walking up Dart frames until an
  * appropriate 'catch' block is found, executing 'finally' blocks,
  * etc.
  *
  * If the error is not an unhandled exception error, we will unwind
  * the stack to the next C frame.  Intervening Dart frames will be
  * discarded; specifically, 'finally' blocks will not execute.  This
  * is the standard way that compilation errors (and the like) are
  * handled by the Dart runtime.
  *
  * In either case, when an error is propagated any current scopes
  * created by Dart_EnterScope will be exited.
  *
  * See the additonal discussion under "Propagating Errors" at the
  * beginning of this file.
  *
  * \param An error handle (See Dart_IsError)
  *
  * \return On success, this function does not return.  On failure, an
  *   error handle is returned.
  */
 DART_EXPORT Dart_Handle Dart_PropagateError(Dart_Handle handle);
-// TODO(turnidge): Should this really return an error handle?
-// Consider just terminating.
+/* TODO(turnidge): Should this really return an error handle? */
+/* Consider just terminating. */
 
-// Internal routine used for reporting error handles.
+/* Internal routine used for reporting error handles. */
 DART_EXPORT void _Dart_ReportErrorHandle(const char* file,
                                          int line,
                                          const char* handle_string,
                                          const char* error);
 
-// TODO(turnidge): Move DART_CHECK_VALID to some sort of dart_utils
-// header instead of this header.
+/* TODO(turnidge): Move DART_CHECK_VALID to some sort of dart_utils
+ * header instead of this header. */
 /**
  * Aborts the process if 'handle' is an error handle.
  *
  * Provided for convenience.
  */
 #define DART_CHECK_VALID(handle)                                               \
   {                                                                            \
     Dart_Handle __handle = handle;                                             \
     if (Dart_IsError((__handle))) {                                            \
       _Dart_ReportErrorHandle(__FILE__, __LINE__,                              \
@@ skipping 131 matching lines @@
  *
  * \return Success if the weak reference set could be created.
  *   Otherwise, returns an error handle.
  */
 DART_EXPORT Dart_Handle Dart_NewWeakReferenceSet(
     Dart_WeakPersistentHandle* keys,
     intptr_t num_keys,
     Dart_WeakPersistentHandle* values,
     intptr_t num_values);
 
-// --- Garbage Collection Callbacks ---
+/* --- 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.
  */
 
 /**
  * A callback invoked at the beginning of a garbage collection.
@@ skipping 49 matching lines @@
  * \param callback A function pointer to an epilogue callback
  *   function.  This function must have been added as an epilogue
  *   callback.
  *
  * \return Success if the callback was removed.  Otherwise, returns an
  *   error handle.
  */
 DART_EXPORT Dart_Handle Dart_RemoveGcEpilogueCallback(
     Dart_GcEpilogueCallback callback);
 
-// --- Initialization and Globals ---
+/* --- Initialization and Globals --- */
 
 /**
  * Gets the version string for the Dart VM.
  *
  * The version of the Dart VM can be accessed without initializing the VM.
  *
  * \return The version string for the embedded Dart VM.
  */
 DART_EXPORT const char* Dart_VersionString();
 
@@ skipping 60 matching lines @@
  * This callback, provided by the embedder, is called when an isolate
  * is interrupted as a result of a call to Dart_InterruptIsolate().
  * When the callback is called, Dart_CurrentIsolate can be used to
  * figure out which isolate is being interrupted.
  *
  * \return The embedder returns true if the isolate should continue
  *   execution. If the embedder returns false, the isolate will be
  *   unwound (currently unimplemented).
  */
 typedef bool (*Dart_IsolateInterruptCallback)();
-// TODO(turnidge): Define and implement unwinding.
+/* TODO(turnidge): Define and implement unwinding. */
 
 /**
  * An isolate unhandled exception callback function.
  *
  * This callback, provided by the embedder, is called when an unhandled
  * exception or internal error is thrown during isolate execution. When the
  * callback is invoked, Dart_CurrentIsolate can be used to figure out which
  * isolate was running when the exception was thrown.
  *
  * \param error The unhandled exception or error.  This handle's scope is
@@ skipping 89 matching lines @@
  *
  * \return True if VM flags set successfully.
  */
 DART_EXPORT bool Dart_SetVMFlags(int argc, const char** argv);
 
 /**
  * Returns true if the named VM flag is set.
  */
 DART_EXPORT bool Dart_IsVMFlagSet(const char* flag_name);
 
-// --- Isolates ---
+/* --- Isolates --- */
 
 /**
  * Creates a new isolate. The new isolate becomes the current isolate.
  *
  * A snapshot can be used to restore the VM quickly to a saved state
  * and is useful for fast startup. If snapshot data is provided, the
  * isolate will be started using that snapshot data.
  *
  * Requires there to be no current isolate.
  *
  * \param script_uri The name of the script this isolate will load.
  *   Provided only for advisory purposes to improve debugging messages.
  * \param main The name of the main entry point this isolate will run.
  *   Provided only for advisory purposes to improve debugging messages.
  * \param snapshot A buffer containing a VM snapshot or NULL if no
  *   snapshot is provided.
  * \param callback_data Embedder data.  This data will be passed to
  *   the Dart_IsolateCreateCallback when new isolates are spawned from
  *   this parent isolate.
  * \param error DOCUMENT
  *
  * \return The new isolate is returned. May be NULL if an error
  *   occurs duing isolate initialization.
  */
 DART_EXPORT Dart_Isolate Dart_CreateIsolate(const char* script_uri,
                                             const char* main,
                                             const uint8_t* snapshot,
                                             void* callback_data,
                                             char** error);
-// TODO(turnidge): Document behavior when there is already a current
-// isolate.
+/* TODO(turnidge): Document behavior when there is already a current
+ * isolate. */
 
 /**
  * Shuts down the current isolate. After this call, the current
  * isolate is NULL.
  *
  * Requires there to be a current isolate.
  */
 DART_EXPORT void Dart_ShutdownIsolate();
-// TODO(turnidge): Document behavior when there is no current isolate.
+/* TODO(turnidge): Document behavior when there is no current isolate. */
 
 /**
  * Returns the current isolate. Will return NULL if there is no
  * current isolate.
  */
 DART_EXPORT Dart_Isolate Dart_CurrentIsolate();
 
 /**
  * Returns the callback data which was passed to the isolate when it
  * was created.
  */
 DART_EXPORT void* Dart_CurrentIsolateData();
 
 /**
  * Returns the debugging name for the current isolate.
  *
  * This name is unique to each isolate and should only be used to make
  * debugging messages more comprehensible.
  */
 DART_EXPORT Dart_Handle Dart_DebugName();
 
 /**
  * Enters an isolate. After calling this function,
  * the current isolate will be set to the provided isolate.
  *
  * Requires there to be no current isolate.
  */
 DART_EXPORT void Dart_EnterIsolate(Dart_Isolate isolate);
-// TODO(turnidge): Describe what happens if two threads attempt to
-// enter the same isolate simultaneously. Check for this in the code.
-// Describe whether isolates are allowed to migrate.
+/* TODO(turnidge): Describe what happens if two threads attempt to
+ * enter the same isolate simultaneously. Check for this in the code.
+ * Describe whether isolates are allowed to migrate. */
 
 /**
  * Exits an isolate. After this call, Dart_CurrentIsolate will
  * return NULL.
  *
  * Requires there to be a current isolate.
  */
 DART_EXPORT void Dart_ExitIsolate();
-// TODO(turnidge): We don't want users of the api to be able to exit a
-// "pure" dart isolate. Implement and document.
+/* TODO(turnidge): We don't want users of the api to be able to exit a
+ * "pure" dart isolate. Implement and document. */
 
 /**
  * Creates a full snapshot of the current isolate heap.
  *
  * A full snapshot is a compact representation of the dart heap state and
  * can be used for fast initialization of an isolate. A Snapshot of the heap
  * can only be created before any dart code has executed.
  *
  * Requires there to be a current isolate.
  *
@@ skipping 48 matching lines @@
  * When isolates are spawned this function is used to indicate that
  * the creation and initialization (including script loading) of the
  * isolate is complete and the isolate can start.
  * This function does not expect there to be a current isolate.
  *
  * \param isolate The isolate to be made runnable.
  */
 DART_EXPORT bool Dart_IsolateMakeRunnable(Dart_Isolate isolate);
 
 
-// --- Messages and Ports ---
+/* --- Messages and Ports --- */
 
 /**
  * A port is used to send or receive inter-isolate messages
  */
 typedef int64_t Dart_Port;
 
 /**
  * ILLEGAL_PORT is a port number guaranteed never to be associated with a valid
  * port.
  */
@@ skipping 13 matching lines @@
  * Allows embedders to provide an alternative wakeup mechanism for the
  * delivery of inter-isolate messages. This setting only applies to
  * the current isolate.
  *
  * Most embedders will only call this function once, before isolate
  * execution begins. If this function is called after isolate
  * execution begins, the embedder is responsible for threading issues.
  */
 DART_EXPORT void Dart_SetMessageNotifyCallback(
     Dart_MessageNotifyCallback message_notify_callback);
-// TODO(turnidge): Consider moving this to isolate creation so that it
-// is impossible to mess up.
+/* TODO(turnidge): Consider moving this to isolate creation so that it
+ * is impossible to mess up. */
 
 /**
  * Handles the next pending message for the current isolate.
  *
  * May generate an unhandled exception error.
  *
  * \return A valid handle if no error occurs during the operation.
  */
 DART_EXPORT Dart_Handle Dart_HandleMessage();
 
 /**
  * Processes any incoming messages for the current isolate.
  *
  * This function may only be used when the embedder has not provided
  * an alternate message delivery mechanism with
  * Dart_SetMessageCallbacks. It is provided for convenience.
  *
  * This function waits for incoming messages for the current
  * isolate. As new messages arrive, they are handled using
  * Dart_HandleMessage. The routine exits when all ports to the
  * current isolate are closed.
  *
  * \return A valid handle if the run loop exited successfully.  If an
  *   exception or other error occurs while processing messages, an
  *   error handle is returned.
  */
 DART_EXPORT Dart_Handle Dart_RunLoop();
-// TODO(turnidge): Should this be removed from the public api?
+/* TODO(turnidge): Should this be removed from the public api? */
 
 /**
  * Gets the main port id for the current isolate.
  */
 DART_EXPORT Dart_Port Dart_GetMainPortId();
 
 /**
  * Does the current isolate have live ReceivePorts?
  *
  * A ReceivePort is live when it has not been closed.
  */
 DART_EXPORT bool Dart_HasLivePorts();
 
 /**
  * Posts a message for some isolate. The message is a serialized
  * object.
  *
  * Requires there to be a current isolate.
  *
  * \param port The destination port.
  * \param object An object from the current isolate.
  *
  * \return True if the message was posted.
  */
 DART_EXPORT bool Dart_Post(Dart_Port port_id, Dart_Handle object);
 
-// --- Message sending/receiving from native code ----
-
-/**
- * A Dart_CObject is used for representing Dart objects as native C
- * data outside the Dart heap. These objects are totally detached from
- * the Dart heap. Only a subset of the Dart objects have a
- * representation as a Dart_CObject.
- *
- * The string encoding in the 'value.as_string' is UTF-8.
- *
- * All the different types from dart:typed_data are exposed as type
- * kTypedData. The specific type from dart:typed_data is in the type
- * field of the as_typed_data structure. The length in the
- * as_typed_data structure is always in bytes.
- */
-typedef struct _Dart_CObject {
-  enum Type {
-    kNull = 0,
-    kBool,
-    kInt32,
-    kInt64,
-    kBigint,
-    kDouble,
-    kString,
-    kArray,
-    kTypedData,
-    kExternalTypedData,
-    kUnsupported,
-    kNumberOfTypes
-  } type;
-
-  enum TypedDataType {
-    kInt8Array = 0,
-    kUint8Array,
-    kUint8ClampedArray,
-    kInt16Array,
-    kUint16Array,
-    kInt32Array,
-    kUint32Array,
-    kInt64Array,
-    kUint64Array,
-    kFloat32Array,
-    kFloat64Array,
-    kNumberOfTypedDataTypes
-  };
-
-  union {
-    bool as_bool;
-    int32_t as_int32;
-    int64_t as_int64;
-    double as_double;
-    char* as_string;
-    char* as_bigint;
-    struct {
-      int length;
-      struct _Dart_CObject** values;
-    } as_array;
-    struct {
-      TypedDataType type;
-      int length;
-      uint8_t* values;
-    } as_typed_data;
-    struct {
-      TypedDataType type;
-      int length;
-      uint8_t* data;
-      void* peer;
-      Dart_WeakPersistentHandleFinalizer callback;
-    } as_external_typed_data;
-  } value;
-} Dart_CObject;
-
-/**
- * Posts a message on some port. The message will contain the
- * Dart_CObject object graph rooted in 'message'.
- *
- * While the message is being sent the state of the graph of
- * Dart_CObject structures rooted in 'message' should not be accessed,
- * as the message generation will make temporary modifications to the
- * data. When the message has been sent the graph will be fully
- * restored.
- *
- * \param port_id The destination port.
- * \param message The message to send.
- *
- * \return True if the message was posted.
- */
-DART_EXPORT bool Dart_PostCObject(Dart_Port port_id, Dart_CObject* message);
-
-/**
- * A native message handler.
- *
- * This handler is associated with a native port by calling
- * Dart_NewNativePort.
- *
- * The message received is decoded into the message structure. The
- * lifetime of the message data is controlled by the caller. All the
- * data references from the message are allocated by the caller and
- * will be reclaimed when returning to it.
- */
-
-typedef void (*Dart_NativeMessageHandler)(Dart_Port dest_port_id,
-                                          Dart_Port reply_port_id,
-                                          Dart_CObject* message);
-
-/**
- * Creates a new native port.  When messages are received on this
- * native port, then they will be dispatched to the provided native
- * message handler.
- *
- * \param name The name of this port in debugging messages.
- * \param handler The C handler to run when messages arrive on the port.
- * \param handle_concurrently Is it okay to process requests on this
- *                            native port concurrently?
- *
- * \return If successful, returns the port id for the native port.  In
- *   case of error, returns ILLEGAL_PORT.
- */
-DART_EXPORT Dart_Port Dart_NewNativePort(const char* name,
-                                         Dart_NativeMessageHandler handler,
-                                         bool handle_concurrently);
-// TODO(turnidge): Currently handle_concurrently is ignored.
-
-/**
- * Closes the native port with the given id.
- *
- * The port must have been allocated by a call to Dart_NewNativePort.
- *
- * \param native_port_id The id of the native port to close.
- *
- * \return Returns true if the port was closed successfully.
- */
-DART_EXPORT bool Dart_CloseNativePort(Dart_Port native_port_id);
-
 /**
  * Returns a new SendPort with the provided port id.
  */
 DART_EXPORT Dart_Handle Dart_NewSendPort(Dart_Port port_id);
 
 /**
  * Gets the ReceivePort for the provided port id, creating it if necessary.
  *
  * Note that there is at most one ReceivePort for a given port id.
  */
 DART_EXPORT Dart_Handle Dart_GetReceivePort(Dart_Port port_id);
 
-// --- Scopes ----
+/* --- Scopes ---- */
 
 /**
  * Enters a new scope.
  *
  * All new local handles will be created in this scope. Additionally,
  * some functions may return "scope allocated" memory which is only
  * valid within this scope.
  *
  * Requires there to be a current isolate.
  */
@@ skipping 25 matching lines @@
  * All the memory allocated this way will be reclaimed either on the
  * next call to Dart_ExitScope or when the native port handler exits.
  *
  * \param size Size of the memory to allocate.
  *
  * \return A pointer to the allocated memory. NULL if allocation
  *   failed. Failure might due to is no current VM zone.
  */
 DART_EXPORT uint8_t* Dart_ScopeAllocate(intptr_t size);
 
-// --- Objects ----
+/* --- Objects ---- */
 
 /**
  * Returns the null object.
  *
  * Requires there to be a current isolate.
  *
  * \return A handle to the null object.
  */
 DART_EXPORT Dart_Handle Dart_Null();
 
@@ skipping 30 matching lines @@
  * \param object An object.
  * \param type A type.
  * \param instanceof Return true if 'object' is an instance of type 'type'.
  *
  * \return A valid handle if no error occurs during the operation.
  */
 DART_EXPORT Dart_Handle Dart_ObjectIsType(Dart_Handle object,
                                           Dart_Handle type,
                                           bool* instanceof);
 
-// --- Instances ----
-// For the purposes of the embedding api, not all objects returned are
-// Dart language objects.  Within the api, we use the term 'Instance'
-// to indicate handles which refer to true Dart language objects.
-//
-// TODO(turnidge): Reorganize the "Object" section above, pulling down
-// any functions that more properly belong here.
+/* --- Instances ----
+ * For the purposes of the embedding api, not all objects returned are
+ * Dart language objects.  Within the api, we use the term 'Instance'
+ * to indicate handles which refer to true Dart language objects.
+ *
+ * TODO(turnidge): Reorganize the "Object" section above, pulling down
+ * any functions that more properly belong here. */
 
 /**
  * Does this handle refer to some Dart language object?
  */
 DART_EXPORT bool Dart_IsInstance(Dart_Handle object);
 
 /**
  * Gets the class for some Dart language object.
  *
  * \param instance Some Dart object.
  *
  * \return If no error occurs, the class is returned. Otherwise an
  *   error handle is returned.
  */
 DART_EXPORT Dart_Handle Dart_InstanceGetClass(Dart_Handle instance);
 
-// --- Numbers ----
+/* --- Numbers ---- */
 
 /**
  * Is this object a Number?
  */
 DART_EXPORT bool Dart_IsNumber(Dart_Handle object);
 
-// --- Integers ----
+/* --- Integers ---- */
 
 /**
  * Is this object an Integer?
  */
 DART_EXPORT bool Dart_IsInteger(Dart_Handle object);
 
 /**
  * Does this Integer fit into a 64-bit signed integer?
  *
  * \param integer An integer.
@@ skipping 69 matching lines @@
  * \param integer An Integer.
  * \param value Returns the value of the Integer as a hexadecimal C
  *   string. This C string is scope allocated and is only valid until
  *   the next call to Dart_ExitScope.
  *
  * \return A valid handle if no error occurs during the operation.
  */
 DART_EXPORT Dart_Handle Dart_IntegerToHexCString(Dart_Handle integer,
                                                  const char** value);
 
-// --- Booleans ----
+/* --- Booleans ---- */
 
 /**
  * Returns the True object.
  *
  * Requires there to be a current isolate.
  *
  * \return A handle to the True object.
  */
 DART_EXPORT Dart_Handle Dart_True();
 
@@ skipping 24 matching lines @@
 /**
  * Gets the value of a Boolean
  *
  * \param boolean_obj A Boolean
  * \param value Returns the value of the Boolean.
  *
  * \return A valid handle if no error occurs during the operation.
  */
 DART_EXPORT Dart_Handle Dart_BooleanValue(Dart_Handle boolean_obj, bool* value);
 
-// --- Doubles ---
+/* --- Doubles --- */
 
 /**
  * Is this object a Double?
  */
 DART_EXPORT bool Dart_IsDouble(Dart_Handle object);
 
 /**
  * Returns a Double with the provided value.
  *
  * \param value A double.
  *
  * \return The Double object if no error occurs. Otherwise returns
  *   an error handle.
  */
 DART_EXPORT Dart_Handle Dart_NewDouble(double value);
 
 /**
  * Gets the value of a Double
  *
  * \param double_obj A Double
  * \param value Returns the value of the Double.
  *
  * \return A valid handle if no error occurs during the operation.
  */
 DART_EXPORT Dart_Handle Dart_DoubleValue(Dart_Handle double_obj, double* value);
 
-// --- Strings ---
+/* --- Strings --- */
 
 /**
  * Is this object a String?
  */
 DART_EXPORT bool Dart_IsString(Dart_Handle object);
 
 /**
  * Is this object a Latin-1 (ISO-8859-1) String?
  */
 DART_EXPORT bool Dart_IsStringLatin1(Dart_Handle object);
@@ skipping 13 matching lines @@
  * (There is an implicit assumption that the C string passed in contains
  *  UTF-8 encoded characters and '\0' is considered as a termination
  *  character).
  *
  * \param value A C String
  *
  * \return The String object if no error occurs. Otherwise returns
  *   an error handle.
  */
 DART_EXPORT Dart_Handle Dart_NewStringFromCString(const char* str);
-// TODO(turnidge): Document what happens when we run out of memory
-// during this call.
+/* TODO(turnidge): Document what happens when we run out of memory
+ * during this call. */
 
 /**
  * Returns a String built from an array of UTF-8 encoded characters.
  *
  * \param utf8_array An array of UTF-8 encoded characters.
  * \param length The length of the codepoints array.
  *
  * \return The String object if no error occurs. Otherwise returns
  *   an error handle.
  */
@@ skipping 171 matching lines @@
  *  result = Dart_MakeExternalString(str, data, size, NULL, NULL);
  *
  */
 DART_EXPORT Dart_Handle Dart_MakeExternalString(Dart_Handle str,
                                                 void* array,
                                                 intptr_t length,
                                                 void* peer,
                                                 Dart_PeerFinalizer cback);
 
 
-// --- Lists ---
+/* --- Lists --- */
 
 /**
  * Is this object a List?
  */
 DART_EXPORT bool Dart_IsList(Dart_Handle object);
 
 /**
  * Returns a List of the desired length.
  *
  * \param length The length of the list.
@@ skipping 57 matching lines @@
                                             intptr_t length);
 
 /**
  * May generate an unhandled exception error.
  */
 DART_EXPORT Dart_Handle Dart_ListSetAsBytes(Dart_Handle list,
                                             intptr_t offset,
                                             uint8_t* native_array,
                                             intptr_t length);
 
-// --- Typed Data ---
+/* --- Typed Data --- */
 
 typedef enum {
-  kByteData = 0,
-  kInt8,
-  kUint8,
-  kUint8Clamped,
-  kInt16,
-  kUint16,
-  kInt32,
-  kUint32,
-  kInt64,
-  kUint64,
-  kFloat32,
-  kFloat64,
-  kFloat32x4,
-  kInvalid
+  Dart_TypedData_kByteData = 0,
+  Dart_TypedData_kInt8,
+  Dart_TypedData_kUint8,
+  Dart_TypedData_kUint8Clamped,
+  Dart_TypedData_kInt16,
+  Dart_TypedData_kUint16,
+  Dart_TypedData_kInt32,
+  Dart_TypedData_kUint32,
+  Dart_TypedData_kInt64,
+  Dart_TypedData_kUint64,
+  Dart_TypedData_kFloat32,
+  Dart_TypedData_kFloat64,
+  Dart_TypedData_kFloat32x4,
+  Dart_TypedData_kInvalid
 } Dart_TypedData_Type;
 
 /**
  * Return type if this object is a TypedData object.
  *
  * \return kInvalid if the object is not a TypedData object or the appropriate
  *   Dart_TypedData_Type.
  */
 DART_EXPORT Dart_TypedData_Type Dart_GetTypeOfTypedData(Dart_Handle object);
 
@@ skipping 62 matching lines @@
  *
  * \param object The typed data object whose internal data address is to be
  *   released.
  *
  * \return Success if the internal data address is released successfully.
  *   Otherwise, returns an error handle.
  */
 DART_EXPORT Dart_Handle Dart_TypedDataReleaseData(Dart_Handle object);
 
 
-// --- Closures ---
+/* --- Closures --- */
 
 /**
  * Is this object a Closure?
  */
 DART_EXPORT bool Dart_IsClosure(Dart_Handle object);
 
 /**
  * Retrieves the function of a closure.
  *
  * \return A handle to the function of the closure, or an error handle if the
  *   argument is not a closure.
  */
 DART_EXPORT Dart_Handle Dart_ClosureFunction(Dart_Handle closure);
 
 /**
  * Invokes a Closure with the given arguments.
  *
  * May generate an unhandled exception error.
  *
  * \return If no error occurs during execution, then the result of
  *   invoking the closure is returned. If an error occurs during
  *   execution, then an error handle is returned.
  */
 DART_EXPORT Dart_Handle Dart_InvokeClosure(Dart_Handle closure,
                                            int number_of_arguments,
                                            Dart_Handle* arguments);
 
-// --- Classes and Interfaces ---
+/* --- Classes and Interfaces --- */
 
 /**
  * Is this a class handle?
  */
 DART_EXPORT bool Dart_IsClass(Dart_Handle handle);
 
 /**
  * Is this an abstract class handle?
  */
 DART_EXPORT bool Dart_IsAbstractClass(Dart_Handle handle);
@@ skipping 54 matching lines @@
 /**
  * Returns a function handle representing the signature associated
  * with a function type.
  *
  * The return value is a function handle (See Dart_IsFunction, etc.).
  *
  * TODO(turnidge): Finish documentation.
  */
 DART_EXPORT Dart_Handle Dart_ClassGetFunctionTypeSignature(Dart_Handle clazz);
 
-// --- Function and Variable Declarations ---
+/* --- Function and Variable Declarations --- */
 
 /**
  * Returns a list of the names of all functions or methods declared in
  * a library or class.
  *
  * \param target A library or class.
  *
  * \return If no error occurs, a list of strings is returned.
  *   Otherwise an error handle is returned.
  */
@@ skipping 69 matching lines @@
 /**
  * Determines whether a function handle referes to a constructor.
  *
  * \param function A handle to a function or method declaration.
  * \param is_static Returns whether the function or method is a constructor.
  *
  * \return A valid handle if no error occurs during the operation.
  */
 DART_EXPORT Dart_Handle Dart_FunctionIsConstructor(Dart_Handle function,
                                                    bool* is_constructor);
-// TODO(turnidge): Document behavior for factory constructors too.
+/* TODO(turnidge): Document behavior for factory constructors too. */
 
 /**
  * Determines whether a function or method is a getter.
  *
  * \param function A handle to a function or method declaration.
  * \param is_static Returns whether the function or method is a getter.
  *
  * \return A valid handle if no error occurs during the operation.
  */
 DART_EXPORT Dart_Handle Dart_FunctionIsGetter(Dart_Handle function,
@@ skipping 155 matching lines @@
 
 /**
  * Returns the upper bound of a type variable.
  *
  * The upper bound of a type variable is ...
  *
  * \return A valid handle to a type, or an error handle if the
  *   argument is not a valid handle.
  */
 DART_EXPORT Dart_Handle Dart_TypeVariableUpperBound(Dart_Handle type_variable);
-// TODO(turnidge): Finish documentation.
+/* TODO(turnidge): Finish documentation. */
 
-// --- Constructors, Methods, and Fields ---
+/* --- Constructors, Methods, and Fields --- */
 
 /**
  * Invokes a constructor, creating a new object.
  *
  * This function allows hidden constructors (constructors with leading
  * underscores) to be called.
  *
  * \param clazz A class or an interface.
  * \param constructor_name The name of the constructor to invoke.  Use
  *   Dart_Null() to invoke the unnamed constructor.  This name should
@@ skipping 29 matching lines @@
  * \param arguments An array of arguments to the function.
  *
  * \return If the function or method is called and completes
  *   successfully, then the return value is returned. If an error
  *   occurs during execution, then an error handle is returned.
  */
 DART_EXPORT Dart_Handle Dart_Invoke(Dart_Handle target,
                                     Dart_Handle name,
                                     int number_of_arguments,
                                     Dart_Handle* arguments);
-// TODO(turnidge): Document how to invoke operators.
+/* TODO(turnidge): Document how to invoke operators. */
 
 /**
  * Gets the value of a field.
  *
  * The 'container' parameter may be an object, class, or library.  If
  * 'container' is an object, then this function will access an
  * instance field.  If 'container' is a class, then this function will
  * access a static field.  If 'container' is a library, then this
  * function will access a top-level variable.
  *
@@ skipping 58 matching lines @@
                                                     intptr_t* value);
 /**
  * Sets the value of a native field.
  *
  * TODO(turnidge): Document.
  */
 DART_EXPORT Dart_Handle Dart_SetNativeInstanceField(Dart_Handle obj,
                                                     int index,
                                                     intptr_t value);
 
-// --- Exceptions ----
-// TODO(turnidge): Remove these functions from the api and replace all
-// uses with Dart_NewUnhandledExceptionError.
+/* --- Exceptions ----
+ * TODO(turnidge): Remove these functions from the api and replace all
+ * uses with Dart_NewUnhandledExceptionError. */
 
 /**
  * Throws an exception.
  *
  * This function causes a Dart language exception to be thrown. This
  * will proceeed in the standard way, walking up Dart frames until an
  * appropriate 'catch' block is found, executing 'finally' blocks,
  * etc.
  *
  * If successful, this function does not return. Note that this means
@@ skipping 12 matching lines @@
  * successful, this function does not return. Note that this means
  * that the destructors of any stack-allocated C++ objects will not be
  * called. If there are no Dart frames on the stack, an error occurs.
  *
  * \return An error handle if the exception was not thrown.
  *   Otherwise the function does not return.
  */
 DART_EXPORT Dart_Handle Dart_RethrowException(Dart_Handle exception,
                                               Dart_Handle stacktrace);
 
-// --- Native functions ---
+/* --- Native functions --- */
 
 /**
  * The arguments to a native function.
  *
  * This object is passed to a native function to represent its
  * arguments and return value. It allows access to the arguments to a
  * native function by index. It also allows the return value of a
  * native function to be set.
  */
 typedef struct _Dart_NativeArguments* Dart_NativeArguments;
 
 /**
  * Gets the native argument at some index.
  */
 DART_EXPORT Dart_Handle Dart_GetNativeArgument(Dart_NativeArguments args,
                                                int index);
-// TODO(turnidge): Specify the behavior of an out-of-bounds access.
+/* TODO(turnidge): Specify the behavior of an out-of-bounds access. */
 
 /**
  * Gets the number of native arguments.
  */
 DART_EXPORT int Dart_GetNativeArgumentCount(Dart_NativeArguments args);
 
 /**
  * Sets the return value for a native function.
  */
 DART_EXPORT void Dart_SetReturnValue(Dart_NativeArguments args,
                                      Dart_Handle retval);
 
 /**
  * A native function.
  */
 typedef void (*Dart_NativeFunction)(Dart_NativeArguments arguments);
 
 /**
  * Native entry resolution callback.
  *
  * For libraries and scripts which have native functions, the embedder
  * can provide a native entry resolver. This callback is used to map a
  * name/arity to a Dart_NativeFunction. If no function is found, the
  * callback should return NULL.
  *
  * See Dart_SetNativeResolver.
  */
 typedef Dart_NativeFunction (*Dart_NativeEntryResolver)(Dart_Handle name,
                                                         int num_of_arguments);
-// TODO(turnidge): Consider renaming to NativeFunctionResolver or
-// NativeResolver.
+/* TODO(turnidge): Consider renaming to NativeFunctionResolver or
+ * NativeResolver. */
 
-// --- Scripts and Libraries ---
-// TODO(turnidge): Finish documenting this section.
+/* --- Scripts and Libraries ---
+ * TODO(turnidge): Finish documenting this section. */
 
 typedef enum {
-  kLibraryTag = 0,
-  kImportTag,
-  kSourceTag,
-  kCanonicalizeUrl
+  Dart_kLibraryTag = 0,
+  Dart_kImportTag,
+  Dart_kSourceTag,
+  Dart_kCanonicalizeUrl
 } Dart_LibraryTag;
 
-// TODO(turnidge): Document.
+/* TODO(turnidge): Document. */
 typedef Dart_Handle (*Dart_LibraryTagHandler)(Dart_LibraryTag tag,
                                               Dart_Handle library,
                                               Dart_Handle url);
 
 /**
  * Sets library tag handler for the current isolate. This handler is
  * used to handle the various tags encountered while loading libraries
  * or scripts in the isolate.
  *
  * \param handler Handler code to be used for handling the various tags
@@ skipping 70 matching lines @@
  * Lookup a class or interface by name from a Library.
  *
  * \param library The library containing the class or interface.
  * \param class_name The name of the class or interface.
  *
  * \return If no error occurs, the class or interface is
  *   returned. Otherwise an error handle is returned.
  */
 DART_EXPORT Dart_Handle Dart_GetClass(Dart_Handle library,
                                       Dart_Handle class_name);
-// TODO(turnidge): Consider returning Dart_Null() when the class is
-// not found to distinguish that from a true error case.
+/* TODO(turnidge): Consider returning Dart_Null() when the class is
+ * not found to distinguish that from a true error case. */
 
 /**
  * Returns the name of a library as declared in the #library directive.
  */
 DART_EXPORT Dart_Handle Dart_LibraryName(Dart_Handle library);
 
 /**
  * Returns the url from which a library was loaded.
  */
 DART_EXPORT Dart_Handle Dart_LibraryUrl(Dart_Handle library);
 
 /**
  * Returns a list of the names of all classes and interfaces declared
  * in a library.
  *
  * \return If no error occurs, a list of strings is returned.
  *   Otherwise an error handle is returned.
  */
 DART_EXPORT Dart_Handle Dart_LibraryGetClassNames(Dart_Handle library);
 
 DART_EXPORT Dart_Handle Dart_LookupLibrary(Dart_Handle url);
-// TODO(turnidge): Consider returning Dart_Null() when the library is
-// not found to distinguish that from a true error case.
+/* TODO(turnidge): Consider returning Dart_Null() when the library is
+ * not found to distinguish that from a true error case. */
 
 DART_EXPORT Dart_Handle Dart_LoadLibrary(Dart_Handle url,
                                          Dart_Handle source);
 
 /**
  * Imports a library into another library, optionally with a prefix.
  * If no prefix is required, an empty string or Dart_Null() can be
  * supplied.
  *
  * \param library The library into which to import another library.
@@ skipping 11 matching lines @@
  *
  * \param library A library
  * \param url A url identifying the origin of the source
  * \param source A string of Dart source
  *
  * \return A valid handle if no error occurs during the operation.
  */
 DART_EXPORT Dart_Handle Dart_LoadSource(Dart_Handle library,
                                         Dart_Handle url,
                                         Dart_Handle source);
-// TODO(turnidge): Rename to Dart_LibraryLoadSource?
+/* TODO(turnidge): Rename to Dart_LibraryLoadSource? */
 
 
 /**
  * Loads a patch source string into a library.
  *
  * \param library A library
  * \param url A url identifying the origin of the patch source
  * \param source A string of Dart patch source
  */
 DART_EXPORT Dart_Handle Dart_LoadPatch(Dart_Handle library,
                                        Dart_Handle url,
                                        Dart_Handle patch_source);
 
 /**
  * Sets the callback used to resolve native functions for a library.
  *
  * \param library A library.
  * \param resolver A native entry resolver.
  *
  * \return A valid handle if the native resolver was set successfully.
  */
 DART_EXPORT Dart_Handle Dart_SetNativeResolver(
     Dart_Handle library,
     Dart_NativeEntryResolver resolver);
-// TODO(turnidge): Rename to Dart_LibrarySetNativeResolver?
+/* TODO(turnidge): Rename to Dart_LibrarySetNativeResolver? */
 
-// --- Profiling support ----
+/* --- Profiling support ---- */
 
-// External pprof support for gathering and dumping symbolic
-// information that can be used for better profile reports for
-// dynamically generated code.
+/* External pprof support for gathering and dumping symbolic
+ * information that can be used for better profile reports for
+ * dynamically generated code. */
 DART_EXPORT void Dart_InitPprofSupport();
 DART_EXPORT void Dart_GetPprofSymbolInfo(void** buffer, int* buffer_size);
 
-// Support for generating symbol maps for use by the Linux perf tool.
+/* Support for generating symbol maps for use by the Linux perf tool. */
 DART_EXPORT void Dart_InitPerfEventsSupport(void* perf_events_file);
 
-// --- Heap Profiler ---
+/* --- Heap Profiler --- */
 
 /**
  * Generates a heap profile.
  *
  * \param callback A function pointer that will be repeatedly invoked
  *   with heap profile data.
  * \param stream A pointer that will be passed to the callback.  This
  *   is a convenient way to provide an open stream to the callback.
  *
  * \return Success if the heap profile is successful.
  */
 DART_EXPORT Dart_Handle Dart_HeapProfile(Dart_FileWriteCallback callback,
                                          void* stream);
 
-// --- Peers ---
+/* --- Peers --- */
 
 /**
  * The peer field is a lazily allocated field intendend for storage of
  * an uncommonly used values.  Most instances types can have a peer
  * field allocated.  The exceptions are subtypes of Null, num, and
  * bool.
  */
 
 /**
  * Returns the value of peer field of 'object' in 'peer'.
@@ skipping 12 matching lines @@
  * 'peer'.
  *
  * \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_
+/* --- Message sending/receiving from native code ---- */
+
+/**
+ * A Dart_CObject is used for representing Dart objects as native C
+ * data outside the Dart heap. These objects are totally detached from
+ * the Dart heap. Only a subset of the Dart objects have a
+ * representation as a Dart_CObject.
+ *
+ * The string encoding in the 'value.as_string' is UTF-8.
+ *
+ * All the different types from dart:typed_data are exposed as type
+ * kTypedData. The specific type from dart:typed_data is in the type
+ * field of the as_typed_data structure. The length in the
+ * as_typed_data structure is always in bytes.
+ */
+typedef enum {
+  Dart_CObject_kNull = 0,
+  Dart_CObject_kBool,
+  Dart_CObject_kInt32,
+  Dart_CObject_kInt64,
+  Dart_CObject_kBigint,
+  Dart_CObject_kDouble,
+  Dart_CObject_kString,
+  Dart_CObject_kArray,
+  Dart_CObject_kTypedData,
+  Dart_CObject_kExternalTypedData,
+  Dart_CObject_kUnsupported,
+  Dart_CObject_kNumberOfTypes
+} Dart_CObject_Type;
+
+typedef struct _Dart_CObject {
+  Dart_CObject_Type type;
+  union {
+    bool as_bool;
+    int32_t as_int32;
+    int64_t as_int64;
+    double as_double;
+    char* as_string;
+    char* as_bigint;
+    struct {
+      int length;
+      struct _Dart_CObject** values;
+    } as_array;
+    struct {
+      Dart_TypedData_Type type;
+      int length;
+      uint8_t* values;
+    } as_typed_data;
+    struct {
+      Dart_TypedData_Type type;
+      int length;
+      uint8_t* data;
+      void* peer;
+      Dart_WeakPersistentHandleFinalizer callback;
+    } as_external_typed_data;
+  } value;
+} Dart_CObject;
+
+/**
+ * Posts a message on some port. The message will contain the
+ * Dart_CObject object graph rooted in 'message'.
+ *
+ * While the message is being sent the state of the graph of
+ * Dart_CObject structures rooted in 'message' should not be accessed,
+ * as the message generation will make temporary modifications to the
+ * data. When the message has been sent the graph will be fully
+ * restored.
+ *
+ * \param port_id The destination port.
+ * \param message The message to send.
+ *
+ * \return True if the message was posted.
+ */
+DART_EXPORT bool Dart_PostCObject(Dart_Port port_id, Dart_CObject* message);
+
+/**
+ * A native message handler.
+ *
+ * This handler is associated with a native port by calling
+ * Dart_NewNativePort.
+ *
+ * The message received is decoded into the message structure. The
+ * lifetime of the message data is controlled by the caller. All the
+ * data references from the message are allocated by the caller and
+ * will be reclaimed when returning to it.
+ */
+
+typedef void (*Dart_NativeMessageHandler)(Dart_Port dest_port_id,
+Dart_Port reply_port_id,
+Dart_CObject* message);
+
+/**
+ * Creates a new native port.  When messages are received on this
+ * native port, then they will be dispatched to the provided native
+ * message handler.
+ *
+ * \param name The name of this port in debugging messages.
+ * \param handler The C handler to run when messages arrive on the port.
+ * \param handle_concurrently Is it okay to process requests on this
+ *                            native port concurrently?
+ *
+ * \return If successful, returns the port id for the native port.  In
+ *   case of error, returns ILLEGAL_PORT.
+ */
+DART_EXPORT Dart_Port Dart_NewNativePort(const char* name,
+                                         Dart_NativeMessageHandler handler,
+                                         bool handle_concurrently);
+/* TODO(turnidge): Currently handle_concurrently is ignored. */
+
+/**
+ * Closes the native port with the given id.
+ *
+ * The port must have been allocated by a call to Dart_NewNativePort.
+ *
+ * \param native_port_id The id of the native port to close.
+ *
+ * \return Returns true if the port was closed successfully.
+ */
+DART_EXPORT bool Dart_CloseNativePort(Dart_Port native_port_id);
+
+#endif  /* INCLUDE_DART_API_H_ */  /* NOLINT */