Second local mirrors CL.

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 54 matching lines @@
  * by value (except in cases like out-parameters) and should never be
  * allocated on the heap.
  *
  * Most functions in the Dart Embedding API return a handle. When a
  * function completes normally, this will be a valid handle to an
  * object in the Dart VM heap. This handle may represent the result of
  * the operation or it may be a special valid handle used merely to
  * indicate successful completion. Note that a valid handle may in
  * some cases refer to the null object.
  *
+ * --- Error handles ---
+ *
  * When a function encounters a problem that prevents it from
  * completing normally, it returns an error handle (See Dart_IsError).
  * An error handle has an associated error message that gives more
  * details about the problem (See Dart_GetError).
  *
- * When an unhandled exception occurs, it is returned as an error
- * handle that has additional information about the exception (See
- * Dart_ErrorHasException). This error handle retains information
- * about the exception and the stack trace (See
- * Dart_ErrorGetException, Dart_ErrorGetStacktrace,
- * Dart_RethrowException).
+ * There are four kinds of error handles that can be produced,
+ * depending on what goes wrong:
+ *
+ * - Api error handles are produced when an api function is misused.
+ *   This happens when a Dart embedding api function is called with
+ *   invalid arguments or in an invalid context.
+ *
+ * - Unhandled exception error handles are produced when, during the
+ *   execution of Dart code, an exception is thrown but not caught.
+ *   Prototypically this would occur during a call to Dart_Invoke, but
+ *   it can occur in any function which triggers the execution of Dart
+ *   code (for example, Dart_ToString).
+ *
+ *   An unhandled exception error provides access to an exception and
+ *   stacktrace via the functions Dart_ErrorGetException and
+ *   Dart_ErrorGetStacktrace.
+ *
+ * - Compilation error handles are produced when, during the execution
+ *   of Dart code, a compile-time error occurs.  As above, this can
+ *   occur in any function which triggers the execution of Dart code.
+ *
+ * - Fatal error handles are produced when the system wants to shut
+ *   down the current isolate.
+ *
+ * --- Propagating errors ---
+ *
+ * When an error handle is returned from the top level invocation of
+ * Dart code in a program, the embedder must handle the error as they
+ * see fit.  Often, the embedder will print the error message produced
+ * by Dart_Error and exit the program.
+ *
+ * When an error is returned while in the body of a native function,
+ * it can be propagated by calling Dart_PropagateError.  Errors should
+ * be propagated unless there is a specific reason not to.  If an
+ * error is not propagated then it is ignored.  For example, if an
+ * unhandled exception error is ignored, that effectively "catches"
+ * the unhandled exception.  Fatal errors must always be propagated.
+ *
+ * Note that a call to Dart_PropagateError never returns.  Instead it
+ * transfers control non-locally using a setjmp-like mechanism.  This
+ * can be inconvenient if you have resources that you need to clean up
+ * before propagating the error.  When an error is propagated, any
+ * current scopes created by Dart_EnterScope will be exited.
+ *
+ * To deal with this inconvenience, we often return error handles
+ * rather than propagating them from helper functions.  Consider the
+ * following contrived example:
+ *
+ * 1    Dart_Handle isLongStringHelper(Dart_Handle arg) {
+ * 2      intptr_t* length = 0;
+ * 3      result = Dart_StringLength(arg, &length);
+ * 4      if (Dart_IsError(result)) {
+ * 5        return result
+ * 6      }
+ * 7      return Dart_NewBoolean(length > 100);
+ * 8    }
+ * 9
+ * 10   void NativeFunction_isLongString(Dart_NativeArguments args) {
+ * 11     Dart_EnterScope();
+ * 12     AllocateMyResource();
+ * 13     Dart_Handle arg = Dart_GetNativeArgument(args, 0);
+ * 14     Dart_Handle result = isLongStringHelper(arg);
+ * 15     if (Dart_IsError(result)) {
+ * 16       FreeMyResource();
+ * 17       Dart_PropagateError(result);

[Ivan Posva, 2012/06/11 16:45:02]

You might want to make it clear in the code here that execution does not
continue after Dart_PropagateError() by adding abort() or something similar on
the next line.

[turnidge, 2012/06/12 20:51:46]

Done.

+ * 18     }
+ * 19     Dart_SetReturnValue(result);
+ * 20     FreeMyResource();
+ * 21     Dart_ExitScope();
+ * 22   }
+ *
+ * In this example, we have a native function which calls a helper
+ * function to do its work.  On line 5, the helper function could call
+ * Dart_PropagateError, but that would not give the native function a
+ * chance to call FreeMyResource(), causing a leak.  Instead, the
+ * helper function returns the error handle to the caller, giving the
+ * caller a chance to clean up before propagating the error handle.
+ *
+ * --- Local and persistent handles ---
  *
  * Local handles are allocated within the current scope (see
  * Dart_EnterScope) and go away when the current scope exits. Unless
  * otherwise indicated, callers should assume that all functions in
  * the Dart embedding api return local handles.
  *
  * Persistent handles are allocated within the current isolate. They
  * can be used to store objects across scopes. Persistent handles have
  * the lifetime of the current isolate unless they are explicitly
  * deallocated (see Dart_DeletePersistentHandle).
  */
 typedef struct _Dart_Handle* Dart_Handle;
 
 typedef void (*Dart_WeakPersistentHandleFinalizer)(Dart_Handle handle,
                                                    void* peer);
 typedef void (*Dart_PeerFinalizer)(void* peer);
 
 /**
  * Is this an error handle?
  *
  * Requires there to be a current isolate.
  */
 DART_EXPORT bool Dart_IsError(Dart_Handle handle);
 
 /**
+ * Is this an api error handle?
+ *
+ * Api error handles are produced when an api function is misused.
+ * This happens when a Dart embedding api function is called with
+ * invalid arguments or in an invalid context.
+ *
+ * Requires there to be a current isolate.
+ */
+DART_EXPORT bool Dart_IsApiError(Dart_Handle handle);
+
+/**
+ * Is this an unhandled exception error handle?
+ *
+ * Unhandled exception error handles are produced when, during the
+ * execution of Dart code, an exception is thrown but not caught.
+ * This can occur in any function which triggers the execution of Dart
+ * code.
+ *
+ * See Dart_ErrorGetException and Dart_ErrorGetStacktrace.
+ *
+ * Requires there to be a current isolate.
+ */
+DART_EXPORT bool Dart_IsUnhandledExceptionError(Dart_Handle handle);
+
+/**
+ * Is this a compilation error handle?
+ *
+ * Compilation error handles are produced when, during the execution
+ * of Dart code, a compile-time error occurs.  This can occur in any
+ * function which triggers the execution of Dart code.
+ *
+ * Requires there to be a current isolate.
+ */
+DART_EXPORT bool Dart_IsCompilationError(Dart_Handle handle);
+
+/**
+ * Is this a fatal error handle?
+ *
+ * Fatal error handles are produced when the system wants to shut down
+ * the current isolate.
+ *
+ * Requires there to be a current isolate.
+ */
+DART_EXPORT bool Dart_IsFatalError(Dart_Handle handle);
+
+/**
  * Gets the error message from an error handle.
  *
  * Requires there to be a current isolate.
  *
  * \return A C string containing an error message if the handle is
  *   error. An empty C string ("") if the handle is valid. This C
  *   String is scope allocated and is only valid until the next call
  *   to Dart_ExitScope.
 */
 DART_EXPORT const char* Dart_GetError(Dart_Handle handle);
 
 /**
  * Is this an error handle for an unhandled exception?
  */
 DART_EXPORT bool Dart_ErrorHasException(Dart_Handle handle);
 
 /**
  * Gets the exception Object from an unhandled exception error handle.
  */
 DART_EXPORT Dart_Handle Dart_ErrorGetException(Dart_Handle handle);
 
 /**
  * Gets the stack trace Object from an unhandled exception error handle.
  */
 DART_EXPORT Dart_Handle Dart_ErrorGetStacktrace(Dart_Handle handle);
 
 /**
- * Produces an error handle with the provided error message.
+ * Produces an api error handle with the provided error message.
  *
  * Requires there to be a current isolate.
  *
- * \param error A C string containing an error message.
+ * \param format A printf style format specifier used to construct the
+ *   error message.
  */
+DART_EXPORT Dart_Handle Dart_NewApiError(const char* format, ...);
+
+/**
+ * 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.
 DART_EXPORT Dart_Handle Dart_Error(const char* format, ...);
 
 /**
  * Propagates an error.
  *
- * It only makes sense to call this function when there are dart
- * frames on the stack.  That is, this function should only be called
- * in the C implementation of a native function which has been called
- * from Dart code.  If this function is called in the top-level
- * embedder code, it will return an error, as there is no way to
- * further propagate the error.
+ * If the provided handle is an unhandled exception error, this
+ * function will cause the unhandled exception to be rethrown.
  *
- * The provided handle must be an error handle.  (See Dart_IsError.)
+ * If the error is not an unhandled exception error, we will unwind
+ * the stack to the next C frame.  Any intervening Dart frames will
+ * be discarded.
  *
- * If the provided handle is an unhandled exception, this function
- * will cause the unhandled exception to be rethrown.  Otherwise, the
- * error will be propagated to the caller, discarding any active dart
- * frames up to the next C frame.
+ * In either case, when an error is propagated any current scopes
+ * created by Dart_EnterScope will be exited.
  *
- * \param An error handle.
+ * 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.
 
 // 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.
 /**
@@ skipping 718 matching lines @@
  *
  * \return A valid handle if no error occurs during the comparison.
  */
 DART_EXPORT Dart_Handle Dart_ObjectEquals(Dart_Handle obj1,
                                           Dart_Handle obj2,
                                           bool* equal);
 
 /**
  * Is this object an instance of some type?
  *
- * The result of the test is returned through the 'instanceif' parameter.
+ * The result of the test is returned through the 'instanceof' parameter.
  * The return value itself is used to indicate success or failure.
  *
  * \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.
+
+/**
+ * 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?
  */
 DART_EXPORT bool Dart_IsNumber(Dart_Handle object);
 
 // --- Integers ----
 
 /**
@@ skipping 810 matching lines @@
 DART_EXPORT Dart_Handle Dart_InvokeClosure(Dart_Handle closure,
                                            int number_of_arguments,
                                            Dart_Handle* arguments);
 
 // DEPRECATED: The API below is a temporary hack.
 DART_EXPORT int64_t Dart_ClosureSmrck(Dart_Handle object);
 
 // DEPRECATED: The API below is a temporary hack.
 DART_EXPORT void Dart_ClosureSetSmrck(Dart_Handle object, int64_t value);
 
+// --- Classes and Interfaces ---
+
+/**
+ * Is this a class handle?
+ *
+ * Most parts of the dart embedding api do not distinguish between
+ * classes and interfaces.  For example, Dart_GetClass can return a
+ * class or an interface and Dart_New can instantiate a class or an
+ * interface.  The exceptions are Dart_IsClass and Dart_IsInterface,
+ * which can be used to distinguish whether a handle refers to a class
+ * or an interface.
+ */
+DART_EXPORT bool Dart_IsClass(Dart_Handle handle);
+
+/**
+ * Is this an interface handle?
+ *
+ * Most parts of the dart embedding api do not distinguish between
+ * classes and interfaces.  For example, Dart_GetClass can return a
+ * class or an interface and Dart_New can instantiate a class or an
+ * interface.  The exceptions are Dart_IsClass and Dart_IsInterface,
+ * which can be used to distinguish whether a handle refers to a class
+ * or an interface.
+ */
+DART_EXPORT bool Dart_IsInterface(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 default factory class for the provided class or
+ * interface.
+ *
+ * Only interfaces may have default fadctory classes.  If the class or
+ * interface has no default factory class, this function returns
+ * Dart_Null().
+ */
+DART_EXPORT Dart_Handle Dart_ClassGetDefault(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);
+
 // --- 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
@@ skipping 110 matching lines @@
 /**
  * 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.
  *
  * Throws an exception, unwinding all dart frames on the stack. If
  * 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.
@@ skipping 181 matching lines @@
 /**
  * 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 erorr 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);
 
 
 DART_EXPORT Dart_Handle Dart_LibraryImportLibrary(Dart_Handle library,
                                                   Dart_Handle import);
@@ skipping 22 matching lines @@
 // 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 flow graph compiler debugging output into a file.
 typedef void (*FileWriterFunction)(const char* buffer, int64_t num_bytes);
 DART_EXPORT void Dart_InitFlowGraphPrinting(FileWriterFunction function);
 
 #endif  // INCLUDE_DART_API_H_