Split dart_api.h into multiple parts:

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 47 matching lines @@
 #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 397 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 170 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.
  *
@@ skipping 100 matching lines @@
  * \param buffer Returns a pointer to a buffer containing
  *   the snapshot. This buffer is scope allocated and is only valid
  *   until the next call to Dart_ExitScope.
  * \param size Returns the size of the buffer.
  *
  * \return A valid handle if no error occurs during the operation.
  */
 DART_EXPORT Dart_Handle Dart_CreateScriptSnapshot(uint8_t** buffer,
                                                   intptr_t* size);
 
-
 /**
  * Schedules an interrupt for the specified isolate.
  *
  * Note that the interrupt does not occur immediately. In fact, if
  * 'isolate' does not execute any further Dart code, then the
  * interrupt will not occur at all.  If and when the isolate is
  * interrupted, the isolate interrupt callback will be invoked with
  * 'isolate' as the current isolate (see
  * Dart_IsolateInterruptCallback).
  *
  * \param isolate The isolate to be interrupted.
  */
 DART_EXPORT void Dart_InterruptIsolate(Dart_Isolate isolate);
 
-
 /**
  * Make isolate runnable.
  *
  * 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 81 matching lines @@
  */
 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 ----
+
+/**
+ * Query object type.
+ *
+ * \param object Some Object.
+ *
+ * \return true if Object is of the specified type.
+ */
+DART_EXPORT bool Dart_IsInstance(Dart_Handle object);
+DART_EXPORT bool Dart_IsNumber(Dart_Handle object);
+DART_EXPORT bool Dart_IsInteger(Dart_Handle object);
+DART_EXPORT bool Dart_IsDouble(Dart_Handle object);
+DART_EXPORT bool Dart_IsBoolean(Dart_Handle object);
+DART_EXPORT bool Dart_IsString(Dart_Handle object);
+DART_EXPORT bool Dart_IsStringLatin1(Dart_Handle object);  /* (ISO-8859-1) */
+DART_EXPORT bool Dart_IsExternalString(Dart_Handle object);
+DART_EXPORT bool Dart_IsList(Dart_Handle object);
+DART_EXPORT bool Dart_IsLibrary(Dart_Handle object);
+DART_EXPORT bool Dart_IsClass(Dart_Handle handle);
+DART_EXPORT bool Dart_IsAbstractClass(Dart_Handle handle);
+DART_EXPORT bool Dart_IsFunction(Dart_Handle handle);
+DART_EXPORT bool Dart_IsVariable(Dart_Handle handle);
+DART_EXPORT bool Dart_IsTypeVariable(Dart_Handle handle);
+DART_EXPORT bool Dart_IsClosure(Dart_Handle object);
+
+
+/*
+ * =========
+ * 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 ---- */
 
-/**
- * Is this object a Number?
+/*
+ * =============================
+ * Numbers, Integers and Doubles
+ * =============================
  */
-DART_EXPORT bool Dart_IsNumber(Dart_Handle object);
-
-/* --- 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.
  * \param fits Returns true if the integer fits into a 64-bit signed integer.
  *
  * \return A valid handle if no error occurs during the operation.
  */
 DART_EXPORT Dart_Handle Dart_IntegerFitsIntoInt64(Dart_Handle integer,
@@ skipping 64 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 ---- */
+/**
+ * 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);
+
+
+/*
+ * ========
+ * 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();
 
 /**
  * Returns the False object.
  *
  * Requires there to be a current isolate.
  *
  * \return A handle to the False object.
  */
 DART_EXPORT Dart_Handle Dart_False();
 
 /**
- * Is this object a Boolean?
- */
-DART_EXPORT bool Dart_IsBoolean(Dart_Handle object);
-
-/**
  * Returns a Boolean with the provided value.
  *
  * \param value true or false.
  *
  * \return The Boolean object if no error occurs. Otherwise returns
  *   an error handle.
  */
 DART_EXPORT Dart_Handle Dart_NewBoolean(bool value);
 
 /**
  * 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 --- */
 
-/**
- * Is this object a Double?
+/*
+ * =======
+ * Strings
+ * =======
  */
-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 --- */
-
-/**
- * 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);
 
 /**
  * Gets the length of a String.
  *
  * \param str A String.
  * \param length Returns the length of the String.
  *
  * \return A valid handle if no error occurs during the operation.
  */
 DART_EXPORT Dart_Handle Dart_StringLength(Dart_Handle str, intptr_t* length);
@@ skipping 43 matching lines @@
  * \param utf32_array An array of UTF-32 encoded characters.
  * \param length The length of the codepoints array.
  *
  * \return The String object if no error occurs. Otherwise returns
  *   an error handle.
  */
 DART_EXPORT Dart_Handle Dart_NewStringFromUTF32(const int32_t* utf32_array,
                                                 intptr_t length);
 
 /**
- * Is this object an external String?
- *
- * An external String is a String which references a fixed array of
- * codepoints which is external to the Dart heap.
- */
-DART_EXPORT bool Dart_IsExternalString(Dart_Handle object);
-
-/**
  * Retrieves the peer pointer associated with an external String.
  */
 DART_EXPORT Dart_Handle Dart_ExternalStringGetPeer(Dart_Handle object,
                                                    void** peer);
 
 /**
  * Returns a String which references an external array of
  * Latin-1 (ISO-8859-1) encoded characters.
  *
  * \param latin1_array Array of Latin-1 encoded characters. This must not move.
@@ skipping 125 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 --- */
-
-/**
- * Is this object a List?
+/*
+ * =====
+ * Lists
+ * =====
  */
-DART_EXPORT bool Dart_IsList(Dart_Handle object);
 
 /**
  * Returns a List of the desired length.
  *
  * \param length The length of the list.
  *
  * \return The List object if no error occurs. Otherwise returns
  *   an error handle.
  */
 DART_EXPORT Dart_Handle Dart_NewList(intptr_t length);
@@ skipping 52 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 {
   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,
@@ skipping 78 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 --- */
-
-/**
- * Is this object a Closure?
+/*
+ * ============================================================
+ * Invoking Constructors, Methods, Closures and Field accessors
+ * ============================================================
  */
-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 --- */
-
-/**
- * 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);
-
-/**
- * Returns the class name for the provided class or interface.
- */
-DART_EXPORT Dart_Handle Dart_ClassName(Dart_Handle clazz);
-
-/**
- * Returns the library for the provided class or interface.
- */
-DART_EXPORT Dart_Handle Dart_ClassGetLibrary(Dart_Handle clazz);
-
-/**
- * Returns the number of interfaces directly implemented by some class
- * or interface.
- *
- * TODO(turnidge): Finish documentation.
- */
-DART_EXPORT Dart_Handle Dart_ClassGetInterfaceCount(Dart_Handle clazz,
-                                                    intptr_t* count);
-
-/**
- * Returns the interface at some index in the list of interfaces some
- * class or inteface.
- *
- * TODO(turnidge): Finish documentation.
- */
-DART_EXPORT Dart_Handle Dart_ClassGetInterfaceAt(Dart_Handle clazz,
-                                                 intptr_t index);
-
-/**
- * Is this class defined by a typedef?
- *
- * Typedef definitions from the main program are represented as a
- * special kind of class handle.  See Dart_ClassGetTypedefReferent.
- *
- * TODO(turnidge): Finish documentation.
- */
-DART_EXPORT bool Dart_ClassIsTypedef(Dart_Handle clazz);
-
-/**
- * Returns a handle to the type to which a typedef refers.
- *
- * It is an error to call this function on a handle for which
- * Dart_ClassIsTypedef is not true.
- *
- * TODO(turnidge): Finish documentation.
- */
-DART_EXPORT Dart_Handle Dart_ClassGetTypedefReferent(Dart_Handle clazz);
-
-/**
- * Does this class represent the type of a function?
- */
-DART_EXPORT bool Dart_ClassIsFunctionType(Dart_Handle clazz);
-
-/**
- * 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 --- */
-
-/**
- * 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.
- */
-DART_EXPORT Dart_Handle Dart_GetFunctionNames(Dart_Handle target);
-
-/**
- * Looks up a function or method declaration by name from a library or
- * class.
- *
- * \param target The library or class containing the function.
- * \param function_name The name of the function.
- *
- * \return If an error is encountered, returns an error handle.
- *   Otherwise returns a function handle if the function is found of
- *   Dart_Null() if the function is not found.
- */
-DART_EXPORT Dart_Handle Dart_LookupFunction(Dart_Handle target,
-                                            Dart_Handle function_name);
-
-/**
- * Is this a function or method declaration handle?
- */
-DART_EXPORT bool Dart_IsFunction(Dart_Handle handle);
-
-/**
- * Returns the name for the provided function or method.
- *
- * \return A valid string handle if no error occurs during the
- *   operation.
- */
-DART_EXPORT Dart_Handle Dart_FunctionName(Dart_Handle function);
-
-/**
- * Returns a handle to the owner of a function.
- *
- * The owner of an instance method or a static method is its defining
- * class. The owner of a top-level function is its defining
- * library. The owner of the function of a non-implicit closure is the
- * function of the method or closure that defines the non-implicit
- * closure.
- *
- * \return A valid handle to the owner of the function, or an error
- *   handle if the argument is not a valid handle to a function.
- */
-DART_EXPORT Dart_Handle Dart_FunctionOwner(Dart_Handle function);
-
-/**
- * Determines whether a function handle refers to an abstract method.
- *
- * \param function A handle to a function or method declaration.
- * \param is_static Returns whether the handle refers to an abstract method.
- *
- * \return A valid handle if no error occurs during the operation.
- */
-DART_EXPORT Dart_Handle Dart_FunctionIsAbstract(Dart_Handle function,
-                                                bool* is_abstract);
-
-/**
- * Determines whether a function handle referes to a static function
- * of method.
- *
- * For the purposes of the embedding API, a top-level function is
- * implicitly declared static.
- *
- * \param function A handle to a function or method declaration.
- * \param is_static Returns whether the function or method is declared static.
- *
- * \return A valid handle if no error occurs during the operation.
- */
-DART_EXPORT Dart_Handle Dart_FunctionIsStatic(Dart_Handle function,
-                                              bool* is_static);
-
-/**
- * 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. */
-
-/**
- * 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,
-                                              bool* is_getter);
-
-/**
- * Determines whether a function or method is a setter.
- *
- * \param function A handle to a function or method declaration.
- * \param is_static Returns whether the function or method is a setter.
- *
- * \return A valid handle if no error occurs during the operation.
- */
-DART_EXPORT Dart_Handle Dart_FunctionIsSetter(Dart_Handle function,
-                                              bool* is_setter);
-
-/**
- * Returns the return type of a function.
- *
- * \return A valid handle to a type or an error handle if the argument
- *   is not valid.
- */
-DART_EXPORT Dart_Handle Dart_FunctionReturnType(Dart_Handle function);
-
-/**
- * Determines the number of required and optional parameters.
- *
- * \param function A handle to a function or method declaration.
- * \param fixed_param_count Returns the number of required parameters.
- * \param opt_param_count Returns the number of optional parameters.
- *
- * \return A valid handle if no error occurs during the operation.
- */
-DART_EXPORT Dart_Handle Dart_FunctionParameterCounts(
-  Dart_Handle function,
-  int64_t* fixed_param_count,
-  int64_t* opt_param_count);
-
-/**
- * Returns a handle to the type of a function parameter.
- *
- * \return A valid handle to a type or an error handle if the argument
- *   is not valid.
- */
-DART_EXPORT Dart_Handle Dart_FunctionParameterType(Dart_Handle function,
-                                                   int parameter_index);
-
-/**
- * Returns a list of the names of all variables 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.
- */
-DART_EXPORT Dart_Handle Dart_GetVariableNames(Dart_Handle target);
-
-/**
- * Looks up a variable declaration by name from a library or class.
- *
- * \param target The library or class containing the variable.
- * \param variable_name The name of the variable.
- *
- * \return If an error is encountered, returns an error handle.
- *   Otherwise returns a variable handle if the variable is found or
- *   Dart_Null() if the variable is not found.
- */
-DART_EXPORT Dart_Handle Dart_LookupVariable(Dart_Handle target,
-                                            Dart_Handle variable_name);
-
-/**
- * Is this a variable declaration handle?
- */
-DART_EXPORT bool Dart_IsVariable(Dart_Handle handle);
-
-/**
- * Returns the name for the provided variable.
- */
-DART_EXPORT Dart_Handle Dart_VariableName(Dart_Handle variable);
-
-/**
- * Determines whether a variable is declared static.
- *
- * For the purposes of the embedding API, a top-level variable is
- * implicitly declared static.
- *
- * \param variable A handle to a variable declaration.
- * \param is_static Returns whether the variable is declared static.
- *
- * \return A valid handle if no error occurs during the operation.
- */
-DART_EXPORT Dart_Handle Dart_VariableIsStatic(Dart_Handle variable,
-                                              bool* is_static);
-
-/**
- * Determines whether a variable is declared final.
- *
- * \param variable A handle to a variable declaration.
- * \param is_final Returns whether the variable is declared final.
- *
- * \return A valid handle if no error occurs during the operation.
- */
-DART_EXPORT Dart_Handle Dart_VariableIsFinal(Dart_Handle variable,
-                                             bool* is_final);
-
-/**
- * Returns the type of a variable.
- *
- * \return A valid handle to a type of or an error handle if the
- *   argument is not valid.
- */
-DART_EXPORT Dart_Handle Dart_VariableType(Dart_Handle function);
-
-/**
- * Returns a list of the names of all type variables declared in a class.
- *
- * The type variables list preserves the original declaration order.
- *
- * \param clazz A class.
- *
- * \return If no error occurs, a list of strings is returned.
- *   Otherwise an error handle is returned.
- */
-DART_EXPORT Dart_Handle Dart_GetTypeVariableNames(Dart_Handle clazz);
-
-/**
- * Looks up a type variable declaration by name from a class.
- *
- * \param clazz The class containing the type variable.
- * \param variable_name The name of the type variable.
- *
- * \return If an error is encountered, returns an error handle.
- *   Otherwise returns a type variable handle if the type variable is
- *   found or Dart_Null() if the type variable is not found.
- */
-DART_EXPORT Dart_Handle Dart_LookupTypeVariable(Dart_Handle clazz,
-                                                Dart_Handle type_variable_name);
-
-/**
- * Is this a type variable handle?
- */
-DART_EXPORT bool Dart_IsTypeVariable(Dart_Handle handle);
-
-/**
- * Returns the name for the provided type variable.
- */
-DART_EXPORT Dart_Handle Dart_TypeVariableName(Dart_Handle type_variable);
-
-/**
- * Returns the owner of a function.
- *
- * The owner of a type variable is its defining class.
- *
- * \return A valid handle to the owner of the type variable, or an error
- *   handle if the argument is not a valid handle to a type variable.
- */
-DART_EXPORT Dart_Handle Dart_TypeVariableOwner(Dart_Handle type_variable);
-
-/**
- * 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. */
-
-/* --- 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 32 matching lines @@
  *   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. */
 
 /**
+ * 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);
+
+/**
  * 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.
  *
  * This function ignores field visibility (leading underscores in names).
  *
@@ skipping 24 matching lines @@
  * \param container An object, class, or library.
  * \param name A field name.
  * \param value The new field value.
  *
  * \return A valid handle if no error occurs.
  */
 DART_EXPORT Dart_Handle Dart_SetField(Dart_Handle container,
                                       Dart_Handle name,
                                       Dart_Handle value);
 
-/**
- * Creates a native wrapper class.
- *
- * TODO(turnidge): Document.
+
+/*
+ * ==========
+ * Exceptions
+ * ==========
  */
-DART_EXPORT Dart_Handle Dart_CreateNativeWrapperClass(Dart_Handle library,
-                                                      Dart_Handle class_name,
-                                                      int field_count);
 
-/**
- * Gets the number of native instance fields in an object.
- */
-DART_EXPORT Dart_Handle Dart_GetNativeInstanceFieldCount(Dart_Handle obj,
-                                                         int* count);
-
-/**
- * Gets the value of a native field.
- *
- * TODO(turnidge): Document.
- */
-DART_EXPORT Dart_Handle Dart_GetNativeInstanceField(Dart_Handle obj,
-                                                    int index,
-                                                    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. */
 
 /**
  * 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.
@@ skipping 14 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 fields and functions
+ * ===========================
+ */
+
+/**
+ * Creates a native wrapper class.
+ *
+ * TODO(turnidge): Document.
+ */
+DART_EXPORT Dart_Handle Dart_CreateNativeWrapperClass(Dart_Handle library,
+                                                      Dart_Handle class_name,
+                                                      int field_count);
+
+/**
+ * Gets the number of native instance fields in an object.
+ */
+DART_EXPORT Dart_Handle Dart_GetNativeInstanceFieldCount(Dart_Handle obj,
+                                                         int* count);
+
+/**
+ * Gets the value of a native field.
+ *
+ * TODO(turnidge): Document.
+ */
+DART_EXPORT Dart_Handle Dart_GetNativeInstanceField(Dart_Handle obj,
+                                                    int index,
+                                                    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);
 
 /**
  * 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;
@@ skipping 29 matching lines @@
  * 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. */
 
-
-/* --- Metadata support --- */
-
 /**
- * Get metadata associated with an object.
+ * Sets the callback used to resolve native functions for a library.
  *
- * \param obj Object for which the metadata is retrieved.
+ * \param library A library.
+ * \param resolver A native entry resolver.
  *
- * \return If no error occurs, returns an array of metadata values.
- *   Returns an empty array if there is no metadata for the object.
- *   Returns an error if the evaluation of the metadata expressions fails.
- *
+ * \return A valid handle if the native resolver was set successfully.
  */
-DART_EXPORT Dart_Handle Dart_GetMetadata(Dart_Handle obj);
+DART_EXPORT Dart_Handle Dart_SetNativeResolver(
+    Dart_Handle library,
+    Dart_NativeEntryResolver resolver);
+/* TODO(turnidge): Rename to Dart_LibrarySetNativeResolver? */
 
 
-/* --- Scripts and Libraries ---
- * TODO(turnidge): Finish documenting this section. */
+/*
+ * =====================
+ * Scripts and Libraries
+ * =====================
+ */
+/* TODO(turnidge): Finish documenting this section. */
 
 typedef enum {
   Dart_kLibraryTag = 0,
   Dart_kImportTag,
   Dart_kSourceTag,
   Dart_kCanonicalizeUrl
 } Dart_LibraryTag;
 
 /* TODO(turnidge): Document. */
 typedef Dart_Handle (*Dart_LibraryTagHandler)(Dart_LibraryTag tag,
@@ skipping 50 matching lines @@
  *
  * If the root script has not yet been set for the current isolate,
  * this function returns Dart_Null().  This function never returns an
  * error handle.
  *
  * \return Returns the root Library for the current isolate or Dart_Null().
  */
 DART_EXPORT Dart_Handle Dart_RootLibrary();
 
 /**
- * Forces all loaded classes and functions to be compiled eagerly in
- * the current isolate..
- *
- * TODO(turnidge): Document.
- */
-DART_EXPORT Dart_Handle Dart_CompileAll();
-
-/**
- * Check that all function fingerprints are OK.
- *
- */
-DART_EXPORT Dart_Handle Dart_CheckFunctionFingerprints();
-
-/**
- * Is this object a Library?
- */
-DART_EXPORT bool Dart_IsLibrary(Dart_Handle object);
-
-/**
  * 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. */
 
 /**
- * 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. */
 
 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
@@ skipping 28 matching lines @@
  * 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.
+
+/*
+ * =====
+ * Peers
+ * =====
  */
-DART_EXPORT Dart_Handle Dart_SetNativeResolver(
-    Dart_Handle library,
-    Dart_NativeEntryResolver resolver);
-/* TODO(turnidge): Rename to Dart_LibrarySetNativeResolver? */
-
-/* --- Profiling support ---- */
-
-/* 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. */
-DART_EXPORT void Dart_InitPerfEventsSupport(void* perf_events_file);
-
-/* --- 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 --- */
 
 /**
  * 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);
 
-/* --- 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 */