Deal with unhandled exceptions the same way in all Dart api functions.

runtime/include/dart_api.h

Index: runtime/include/dart_api.h
===================================================================
--- runtime/include/dart_api.h	(revision 1328)
+++ runtime/include/dart_api.h	(working copy)
@@ -64,61 +64,71 @@
  * by value (except in cases like out-parameters) and should never be
  * allocated on the heap.
  *
- * A handle may either be valid or invalid. Valid handles refer to a
- * object in the Dart VM heap. Note that a valid handle may in some
- * cases refer to null or an unhandled exception. Invalid handles are
- * returned by many Dart api functions when they encounter an error.
- * Invalid handles have an associated error message.
+ * 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.
  *
+ * 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 a special
+ * kind of error handle (See Dart_IsUnhandledException). This error
+ * handle retains information about the exception and the stack trace
+ * (See Dart_GetException, Dart_GetStacktrace, Dart_RethrowException).
+ *
  * Local handles are allocated within the current scope (see
  * Dart_EnterScope) and go away when the current scope exits. Unless
- * otherwise indicated, all functions in the Dart embedding api return
- * local handles.
+ * 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
- * need to be explicitly deallocated when they are no longer needed.
+ * 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 void* Dart_Handle;
 
 /**
- * Is this handle valid?
+ * Is this an error handle?
  *
  * Requires there to be a current isolate.
  */
-DART_EXPORT bool Dart_IsValid(const Dart_Handle& handle);
+DART_EXPORT bool Dart_IsError(const Dart_Handle& handle);
 
-// Internal routine used for reporting invalid handles.
-DART_EXPORT void _Dart_ReportInvalidHandle(const char* file,
-                                           int line,
-                                           const char* handle_string,
-                                           const char* error);
-
 /**
- * Aborts the process if 'handle' is invalid.
+ * Gets the error message from an error handle.
  *
- * Provided for convenience.
- */
-#define DART_CHECK_VALID(handle)                                        \
-  if (!Dart_IsValid((handle))) {                                        \
-    _Dart_ReportInvalidHandle(__FILE__, __LINE__,                       \
-                              #handle, Dart_GetError(handle));          \
-  }
-
-/**
- * Gets the error message from an invalid handle.
- *
  * Requires there to be a current isolate.
  *
  * \return A C string containing an error message if the handle is
- *   invalid. An empty C string ("") if the handle is valid.  This C
+ *   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(const Dart_Handle& handle);
 
 /**
- * Produces an invalid handle with the provided error message.
+ * Is this an error handle for an unhandled exception?
+ */
+DART_EXPORT bool Dart_IsUnhandledException(Dart_Handle handle);
+
+/**
+ * Gets the exception Object from an unhandled exception error handle.
+ */
+DART_EXPORT Dart_Handle Dart_GetException(Dart_Handle handle);
+
+/**
+ * Gets the stack trace Object from an unhandled exception error handle.
+ */
+DART_EXPORT Dart_Handle Dart_GetStacktrace(Dart_Handle handle);
+
+/**
+ * Produces an error handle with the provided error message.
  *
  * Requires there to be a current isolate.
  *
@@ -126,15 +136,31 @@
  */
 DART_EXPORT Dart_Handle Dart_Error(const char* format, ...);
 
+// Internal routine used for reporting error handles.
+DART_EXPORT void _Dart_ReportErrorHandle(const char* file,
+                                           int line,

[Anton Muhin, 2011/11/09 12:34:03]

nit: you may want to fix indentation: cf. const char* file and int line.

[turnidge, 2011/11/09 19:53:41]

Done.

+                                           const char* handle_string,
+                                           const char* error);
+
 /**
+ * Aborts the process if 'handle' is an error handle.
+ *
+ * Provided for convenience.
+ */
+#define DART_CHECK_VALID(handle)                                        \
+  if (Dart_IsError((handle))) {                                         \
+    _Dart_ReportErrorHandle(__FILE__, __LINE__,                       \
+                              #handle, Dart_GetError(handle));          \
+  }
+
+/**
  * Converts an object to a string.
  *
- * If an exception occurs during the conversion, this is treated as an
- * error.
+ * May generate an unhandled exception error.
  *
- * \return A handle to the converted string if no errors occur during
- * the conversion. If an error does occur, an invalid handle is
- * returned.
+ * \return A handle to the converted string if no error occurs during
+ *   the conversion. If an error does occur, an error handle is
+ *   returned.
  */
 DART_EXPORT Dart_Handle Dart_ToString(Dart_Handle object);
 
@@ -244,7 +270,7 @@
  * isolate which is ready to execute on the current thread. The
  * current isolate may be NULL, in which case no isolate is ready to
  * execute. Most of the Dart apis require there to be a current
- * isolate in order to function without error.  The current isolate is
+ * isolate in order to function without error. The current isolate is
  * set by any call to Dart_CreateIsolate or Dart_EnterIsolate.
  */
 typedef void* Dart_Isolate;
@@ -298,7 +324,7 @@
  */
 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.
+// enter the same isolate simultaneously. Check for this in the code.
 // Describe whether isolates are allowed to migrate.
 
 /**
@@ -309,7 +335,7 @@
  */
 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.
+// "pure" dart isolate. Implement and document.
 
 /**
  * Creates a snapshot of the state of the current isolate.
@@ -386,12 +412,16 @@
 /**
  * Handles a message on the current isolate.
  *
+ * May generate an unhandled exception error.
+ *
  * Note that this function does not free the memory associated with
  * 'dart_message'.
+ *
+ * \return A valid handle if no error occurs during the operation.
  */
-DART_EXPORT void Dart_HandleMessage(Dart_Port dest_port,
-                                    Dart_Port reply_port,
-                                    Dart_Message dart_message);
+DART_EXPORT Dart_Handle Dart_HandleMessage(Dart_Port dest_port,
+                                           Dart_Port reply_port,
+                                           Dart_Message dart_message);
 // TODO(turnidge): Revisit memory management of 'dart_message'.
 
 /**
@@ -483,6 +513,8 @@
  * parameter. The return value itself is used to indicate success or
  * failure, not equality.
  *
+ * May generate an unhandled exception error.
+ *
  * \param obj1 An object to be compared.
  * \param obj2 An object to be compared.
  * \param equal Returns the result of the equality comparison.
@@ -539,8 +571,8 @@
  *
  * \param value The value of the integer.
  *
- * \return The Integer object if no errors occurs. Otherwise returns
- *   an invalid handle.
+ * \return The Integer object if no error occurs. Otherwise returns
+ *   an error handle.
  */
 DART_EXPORT Dart_Handle Dart_NewInteger(int64_t value);
 
@@ -550,8 +582,8 @@
  * \param value The value of the integer represented as a C string
  *   containing a hexadecimal number.
  *
- * \return The Integer object if no errors occurs. Otherwise returns
- *   an invalid handle.
+ * \return The Integer object if no error occurs. Otherwise returns
+ *   an error handle.
  */
 DART_EXPORT Dart_Handle Dart_NewIntegerFromHexCString(const char* value);
 
@@ -610,8 +642,8 @@
  *
  * \param value true or false.
  *
- * \return The Boolean object if no errors occurs. Otherwise returns
- *   an invalid handle.
+ * \return The Boolean object if no error occurs. Otherwise returns
+ *   an error handle.
  */
 DART_EXPORT Dart_Handle Dart_NewBoolean(bool value);
 
@@ -637,8 +669,8 @@
  *
  * \param value A double.
  *
- * \return The Double object if no errors occurs. Otherwise returns
- *   an invalid handle.
+ * \return The Double object if no error occurs. Otherwise returns
+ *   an error handle.
  */
 DART_EXPORT Dart_Handle Dart_NewDouble(double value);
 
@@ -684,8 +716,8 @@
  *
  * \param value A C String
  *
- * \return The String object if no errors occurs. Otherwise returns
- *   an invalid handle.
+ * \return The String object if no error occurs. Otherwise returns
+ *   an error handle.
  */
 DART_EXPORT Dart_Handle Dart_NewString(const char* str);
 
@@ -695,8 +727,8 @@
  * \param value An array of 8-bit codepoints.
  * \param length The length of the codepoints array.
  *
- * \return The String object if no errors occurs. Otherwise returns
- *   an invalid handle.
+ * \return The String object if no error occurs. Otherwise returns
+ *   an error handle.
  */
 DART_EXPORT Dart_Handle Dart_NewString8(const uint8_t* codepoints,
                                         intptr_t length);
@@ -707,8 +739,8 @@
  * \param value An array of 16-bit codepoints.
  * \param length The length of the codepoints array.
  *
- * \return The String object if no errors occurs. Otherwise returns
- *   an invalid handle.
+ * \return The String object if no error occurs. Otherwise returns
+ *   an error handle.
  */
 DART_EXPORT Dart_Handle Dart_NewString16(const uint16_t* codepoints,
                                          intptr_t length);
@@ -719,8 +751,8 @@
  * \param value An array of 32-bit codepoints.
  * \param length The length of the codepoints array.
  *
- * \return The String object if no errors occurs. Otherwise returns
- *   an invalid handle.
+ * \return The String object if no error occurs. Otherwise returns
+ *   an error handle.
  */
 DART_EXPORT Dart_Handle Dart_NewString32(const uint32_t* codepoints,
                                          intptr_t length);
@@ -803,14 +835,16 @@
  *
  * \param length The length of the list.
  *
- * \return The List object if no errors occurs. Otherwise returns
- *   an invalid handle.
+ * \return The List object if no error occurs. Otherwise returns
+ *   an error handle.
  */
 DART_EXPORT Dart_Handle Dart_NewList(intptr_t length);
 
 /**
  * Gets the length of a List.
  *
+ * May generate an unhandled exception error.

[Anton Muhin, 2011/11/09 12:34:03]

I am slightly concerned with tagging API functions with this info: it may be
hard to maintain.  E.g. we recently changed List API to allow it to deal w/
classes implementing List.  The change would be somewhat more difficult if we
committed to not throwing before.

I don't want to say we cannot maintain this information, but maybe we should ask
embedders to be overparanoid and assume any method may throw an exception.  That
doesn't look like a heavy burden: I would expect many people to write one
function to handle error handles anyway.

Up to you though.

[turnidge, 2011/11/09 19:53:41]

I see your point.  We don't want to have our hands tied in the future with
regards to these tags.

I was thinking back to when I was using python's C api to embed python. 
Sometimes the api would fail to say what could happen and I'd end up needing to
go read the source to figure little details out.

Let's see what Ivan's take on it is.  I'm in the middle.

[Ivan Posva, 2011/11/10 18:05:46]

Until we have a better place to stick this kind of documentation we should leave
it here.

[turnidge, 2011/11/10 20:59:13]

Okay.  Leaving as is for now.

+ *
  * \param list A List.
  * \param length Returns the length of the List.
  *
@@ -823,11 +857,13 @@
  *
  * If the index is out of bounds, an error occurs.
  *
+ * May generate an unhandled exception error.
+ *
  * \param list A List.
  * \param index A valid index into the List.
  *
  * \return The Object in the List at the specified index if no errors
- *   occurs. Otherwise returns an invalid handle.
+ *   occurs. Otherwise returns an error handle.
  */
 DART_EXPORT Dart_Handle Dart_ListGetAt(Dart_Handle list,
                                        intptr_t index);
@@ -837,6 +873,8 @@
  *
  * If the index is out of bounds, an error occurs.
  *
+ * May generate an unhandled exception error.
+ *
  * \param array A List.
  * \param index A valid index into the List.
  * \param value The Object to put in the List.
@@ -847,11 +885,17 @@
                                        intptr_t index,
                                        Dart_Handle value);
 
+/**
+ * May generate an unhandled exception error.
+ */
 DART_EXPORT Dart_Handle Dart_ListGetAsBytes(Dart_Handle list,
                                             intptr_t offset,
                                             uint8_t* native_array,
                                             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,
@@ -867,11 +911,11 @@
 /**
  * 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. Note that this may be an
- *   uncaught exception (see Dart_ExceptionOccurred) or the null
- *   Object. If an error occurred during execution, then an invalid
- *   handle is returned.
+ *   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,
@@ -888,11 +932,11 @@
 /**
  * Invokes a static method 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. Note that this may be an
- *   uncaught exception (see Dart_ExceptionOccurred) or the null
- *   Object. If an error occurred during execution, then an invalid
- *   handle is returned.
+ *   invoking the method is returned. If an error occurs during
+ *   execution, then an error handle is returned.
  */
 DART_EXPORT Dart_Handle Dart_InvokeStatic(Dart_Handle library,
                                           Dart_Handle class_name,
@@ -903,11 +947,11 @@
 /**
  * Invokes an instance method 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. Note that this may be an
- *   uncaught exception (see Dart_ExceptionOccurred) or the null
- *   Object. If an error occurred during execution, then an invalid
- *   handle is returned.
+ *   invoking the method is returned. If an error occurs during
+ *   execution, then an error handle is returned.
  */
 DART_EXPORT Dart_Handle Dart_InvokeDynamic(Dart_Handle receiver,
                                            Dart_Handle function_name,
@@ -917,30 +961,39 @@
 /**
  * Gets the value of a static field.
  *
+ * May generate an unhandled exception error.
+ *
  * \return If no error occurs, then the value of the field is
- *   returned. Otherwise an invalid handle is returned.
+ *   returned. Otherwise an error handle is returned.
  */
 DART_EXPORT Dart_Handle Dart_GetStaticField(Dart_Handle cls, Dart_Handle name);
 
 /**
  * Sets the value of a static field.
  *
+ * May generate an unhandled exception error.
+ *
  * \return A valid handle if no error occurs.
  */
 DART_EXPORT Dart_Handle Dart_SetStaticField(Dart_Handle cls,
                                             Dart_Handle name,
                                             Dart_Handle value);
+
 /**
  * Gets the value of an instance field.
  *
+ * May generate an unhandled exception error.
+ *
  * \return If no error occurs, then the value of the field is
- *   returned. Otherwise an invalid handle is returned.
+ *   returned. Otherwise an error handle is returned.
  */
 DART_EXPORT Dart_Handle Dart_GetInstanceField(Dart_Handle obj,
                                               Dart_Handle name);
 /**
  * Sets the value of an instance field.
  *
+ * May generate an unhandled exception error.
+ *
  * \return A valid handle if no error occurs.
  */
 DART_EXPORT Dart_Handle Dart_SetInstanceField(Dart_Handle obj,
@@ -976,35 +1029,14 @@
 // --- Exceptions ----
 
 /**
- * Does this handle hold information about an unhandled exception?
- */
-DART_EXPORT bool Dart_ExceptionOccurred(Dart_Handle handle);
-// TODO(turnidge): Consider exposing the name of this thing. Maybe
-// IsUnhandledException, IsUncaughtException, or IsThrownException.
-// It is like a regular exception, but plus a stack trace.
-// TODO(turnidge): Consider subsuming exception results into invalid
-// handles so that only one error check needs to be done after method
-// invocation.
-
-/**
- * Gets the exception Object from an unhandled exception.
- */
-DART_EXPORT Dart_Handle Dart_GetException(Dart_Handle result);
-
-/**
- * Gets the stack trace Object from an unhandled exception.
- */
-DART_EXPORT Dart_Handle Dart_GetStacktrace(Dart_Handle unhandled_exception);
-
-/**
  * Throws an exception.
  *
- * Throws an exception, unwinding all dart frames on the stack.  If
- * successful, this function does not return.  Note that this means
+ * 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.
+ * called. If there are no Dart frames on the stack, an error occurs.
  *
- * \return An invalid handle if the exception was not thrown.
+ * \return An error handle if the exception was not thrown.
  *   Otherwise the function does not return.
  */
 DART_EXPORT Dart_Handle Dart_ThrowException(Dart_Handle exception);
@@ -1012,12 +1044,12 @@
 /**
  * Rethrows an exception.
  *
- * Rethrows an exception, unwinding all dart frames on the stack.  If
- * successful, this function does not return.  Note that this means
+ * Rethrows 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.
+ * called. If there are no Dart frames on the stack, an error occurs.
  *
- * \return An invalid handle if the exception was not thrown.
+ * \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,
@@ -1112,8 +1144,8 @@
 /**
  * Lookup a class by name from a Library.
  *
- * \return If no errors occur, the Library is returned. Otherwise an
- *   invalid handle is returned.
+ * \return If no error occurs, the Library is returned. Otherwise an
+ *   error handle is returned.
  */
 DART_EXPORT Dart_Handle Dart_GetClass(Dart_Handle library, Dart_Handle name);