Add an API function to get a debugger stack trace from an error handle.

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 181 matching lines @@
  */
 typedef struct _Dart_Handle* Dart_Handle;
 typedef Dart_Handle Dart_PersistentHandle;
 typedef struct _Dart_WeakPersistentHandle* Dart_WeakPersistentHandle;
 
 typedef void (*Dart_WeakPersistentHandleFinalizer)(
     Dart_WeakPersistentHandle handle,
     void* peer);
 typedef void (*Dart_PeerFinalizer)(void* peer);
 
+typedef struct _Dart_ExceptionStackTrace* Dart_ExceptionStackTrace;

[rmacnak, 2013/11/07 21:31:12]

This is a bad name considering the Dart_CurrentStacktrace below.

This one should be called Dart_StackTrace, and the one in the debugger should be
renamed Dart_Stack as it is a token for querying a live stack, not a trace.

+
 /**
  * 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?
  *
@@ skipping 57 matching lines @@
  */
 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.
+ *
+ * \param handle An unhandled exception error.
+ * \param trace Receives the stack trace.
+ *
+ * \return A valid handle if no error occurs during the operation.
  */
-DART_EXPORT Dart_Handle Dart_ErrorGetStacktrace(Dart_Handle handle);
+DART_EXPORT Dart_Handle Dart_ErrorGetStacktrace(

[rmacnak, 2013/11/07 21:31:12]

Note this no longer provides access to dart:core.Stacktrace object.  (It can
still be retrieved using GetField on the exception, but it doesn't provided any
information beyond what can be gotten here.)

+    Dart_Handle handle,
+    Dart_ExceptionStackTrace *trace);
+DART_EXPORT Dart_Handle Dart_CurrentStacktrace(
+    Dart_ExceptionStackTrace *trace);
+
+/**
+ * Gets the number of frames in a stack trace.
+ *
+ * \param trace The stack trace.
+ * \param length Receives the frame count.
+ *
+ * \return A valid handle if no error occurs during the operation.
+ */
+DART_EXPORT Dart_Handle Dart_StacktraceLength(Dart_ExceptionStackTrace trace,
+                                              intptr_t* length);
+
+/**
+ * Returns information about a given frame in a stack trace
+ *
+ * \param trace The stack trace.
+ * \param frame_index The position of the frame in the stacktrace. Top-of-stack
+ *     is at position 0.
+ *
+ * \param function_name receives a string handle with the qualified function
+ *    name.
+ * \param script_url receives a string handle with the url of the source script
+ *    that contains the frame's function.
+ * \param line_number receives the line number in the script.
+ * \param column_number receives the column number in the script, or -1 if
+ *    precise source locations are not available.
+ *
+ * Any or all of the out parameters above may be NULL.
+ *
+ * Requires there to be a current isolate.
+ *
+ * \return A valid handle if no error occurs during the operation.
+ */
+DART_EXPORT Dart_Handle Dart_StacktraceFrameInfo(
+                            Dart_ExceptionStackTrace trace,
+                            intptr_t frame_index,
+                            Dart_Handle* function_name,
+                            Dart_Handle* script_url,
+                            intptr_t* line_number,
+                            intptr_t* column_number);
+
 
 /**
  * Produces an api error handle with the provided error message.
  *
  * Requires there to be a current isolate.
  *
  * \param error the error message.
  */
 DART_EXPORT Dart_Handle Dart_NewApiError(const char* error);
 
@@ skipping 2048 matching lines @@
  *
  * \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);
 
 #endif  /* INCLUDE_DART_API_H_ */  /* NOLINT */