Add Dart_PropagateError.

runtime/include/dart_api.h

 // Copyright (c) 2011, 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 122 matching lines @@
 
 /**
  * Produces an error handle with the provided error message.
  *
  * Requires there to be a current isolate.
  *
  * \param error A C string containing an error message.
  */
 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 error handle represents an unhandled exception, this

[siva, 2012/01/31 00:52:34]

if the handle or error handle?

[turnidge, 2012/01/31 21:56:31]

Rewrote the comment a bit.

+ * function will cause the unhandled exception to be rethrown.
+ * Otherwise, this function will cause the stack to be an unwound,
+ * discarding any dart frames up to the next C frame.
+ *
+ * \return On success, this function does not return.  On failure, an
+ *   error handle is returned.
+ */
+DART_EXPORT Dart_Handle Dart_PropagateError(Dart_Handle handle);
+
 // 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.
 /**
  * Aborts the process if 'handle' is an error handle.
@@ skipping 1231 matching lines @@
 
 // --- 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);
 
 #endif  // INCLUDE_DART_API_H_