Dart_SetReturnValue now accepts and propagates error handles.

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 126 matching lines @@
  *   normal fatal error.
  *
  * --- 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.
+ * it can be propagated up the call stack by calling
+ * Dart_PropagateError, Dart_SetReturnValue, or Dart_ThrowException.
+ * 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.
+ * 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
+ * Dart_PropagateError and Dart_ThrowException do not return.  Instead
+ * they transfer 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 relying on Dart_PropagateError, 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);
@@ skipping 14 matching lines @@
  * 22     Dart_ExitScope();
  * 23   }
  *
  * 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.
  *
+ * When an error is propagated by calling Dart_SetReturnValue, the
+ * native function will be allowed to complete normally and then the
+ * exception will be propagated only once the native call
+ * returns. This can be convenient, as it allows the C code to clean
+ * up normally.
+ *
+ * The example can be written more simply using Dart_SetReturnValue to
+ * propagate the error.
+ *
+ * 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_SetReturnValue(isLongStringHelper(arg));
+ * 15     FreeMyResource();
+ * 16     Dart_ExitScope();
+ * 17   }
+ *
+ * In this example, the call to Dart_SetReturnValue on line 14 will
+ * either return the normal return value or propagate the error result

[siva, 2016/02/03 16:50:00]

The wording 'propagate the error' seems to imply that the error will be
propagated in the style of Dart_PropagateError.

How about :
set the return value to the normal value or the error (potentially generated on
line 3)

[turnidge, 2016/02/03 19:13:46]

Done.

+ * (potentially generated on line 3).  The call to FreeMyResource on
+ * line 15 will execute in either case.
+ *
  * --- 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
@@ skipping 1932 matching lines @@
  * uses with Dart_NewUnhandledExceptionError. */
 
 /**
  * Throws an exception.
  *
  * This function causes a Dart language exception to be thrown. This
  * will proceed in the standard way, walking up Dart frames until an
  * appropriate 'catch' block is found, executing 'finally' blocks,
  * etc.
  *
+ * If an error handle is passed into this function, the error is
+ * propagated immediately.  See Dart_PropagateError for a discussion
+ * of error propagation.
+ *
  * 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.
  *   Otherwise the function does not return.
  */
 DART_EXPORT Dart_Handle Dart_ThrowException(Dart_Handle exception);
 
 /**
@@ skipping 217 matching lines @@
  * \param arg_index Index of the desired argument in the structure above.
  * \param value Returns the double value if the argument is a double.
  * \return Success if no error occurs. Otherwise returns an error handle.
  */
 DART_EXPORT Dart_Handle Dart_GetNativeDoubleArgument(Dart_NativeArguments args,
                                                      int index,
                                                      double* value);
 
 /**
  * Sets the return value for a native function.
+ *
+ * If retval is an Error handle, then error will be propagated once
+ * the native functions exits. See Dart_PropagateError for a
+ * discussion of how different types of errors are propagated.

[siva, 2016/02/03 16:50:00]

I think the obvious question that comes up is when do I use Dart_PropagateError
and when Dart_SetReturnValue.

[turnidge, 2016/02/03 19:13:46]

Yes.  I've added this paragraph to the discussion at the top of the file...

 * Using Dart_SetReturnValue to propagate an exception is somewhat              

 * more convenient than using Dart_PropagateError, and should be                

 * preferred for reasons discussed below.                                       

  */
 DART_EXPORT void Dart_SetReturnValue(Dart_NativeArguments args,
                                      Dart_Handle retval);
 
 DART_EXPORT void Dart_SetWeakHandleReturnValue(Dart_NativeArguments args,
                                                Dart_WeakPersistentHandle rval);
 
 DART_EXPORT void Dart_SetBooleanReturnValue(Dart_NativeArguments args,
                                             bool retval);
 
@@ skipping 412 matching lines @@
     intptr_t* vm_isolate_snapshot_size,
     uint8_t** isolate_snapshot_buffer,
     intptr_t* isolate_snapshot_size,
     uint8_t** instructions_snapshot_buffer,
     intptr_t* instructions_snapshot_size);
 
 
 DART_EXPORT bool Dart_IsRunningPrecompiledCode();
 
 #endif  /* INCLUDE_DART_API_H_ */  /* NOLINT */