First debugger API unit test

runtime/include/dart_debugger_api.h

Index: runtime/include/dart_debugger_api.h
===================================================================
--- runtime/include/dart_debugger_api.h	(revision 2291)
+++ runtime/include/dart_debugger_api.h	(working copy)
@@ -9,7 +9,14 @@
 
 typedef struct _Dart_Breakpoint* Dart_Breakpoint;
 
+typedef struct _Dart_StackTrace* Dart_StackTrace;
 
+typedef struct _Dart_ActivationFrame* Dart_ActivationFrame;
+
+typedef void Dart_BreakpointHandler(
+                 Dart_Breakpoint breakpoint,
+                 Dart_StackTrace stack_trace);

[siva, 2011/12/09 02:20:04]

Why do we need to always create a stack trace and pass it as a param to the
handler function. Why not have a Dart_GetStackTrace function which will return
the current stack trace.
See comment below regarding events...
For some events I may not be interested in a stack trace at all just the current
location (i.e top frame).

[hausner, 2011/12/13 00:14:59]

As we discussed in person, I strive for an interface that allows clients to make
as few API calls as possible, since remote debuggers and cross-isolate debugging
may ultimately make API calls expensive. 

+
 /**
  * Sets a breakpoint at the entry of the given function. If class_name
  * is the empty string, looks for a library function with the given
@@ -28,4 +35,62 @@
                             Dart_Handle function_name,
                             Dart_Breakpoint* breakpoint);
 
+/**
+ * Installs a handler callback function that gets called by the VM
+ * when a breakpoint has been reached.
+ *
+ * Requires there to be a current isolate.
+ */
+DART_EXPORT void Dart_SetBreakpointHandler(
+                            Dart_BreakpointHandler bp_handler);

[siva, 2011/12/09 02:20:04]

I am wondering if long term we would need an event handler here not just a
breakpoint handler. The events could be breakpoints, exception thrown, exception
caught, isolate death, new isolate start, single step ...

[hausner, 2011/12/13 00:14:59]

I like the DebugEvent idea as a generalization. I am building things bottom-up
right now and when I know enough about debugging APIs, I'll definitely
generalize along this idea.

+
+
+/**
+ * Returns in \length the number of activation frames in the given
+ * stack trace.
+ *
+ * Requires there to be a current isolate.
+ *
+ * \return A handle to the True object if no error occurs.
+ */
+DART_EXPORT Dart_Handle Dart_StackTraceLength(
+                            Dart_StackTrace trace,
+                            intptr_t* length);
+
+
+/**
+ * Returns in \frame the activation frame with index \frame_index.
+ * The activation frame at the top of stack has index 0.
+ *
+ * Requires there to be a current isolate.
+ *
+ * \return A handle to the True object if no error occurs.
+ */
+DART_EXPORT Dart_Handle Dart_GetActivationFrame(
+                            Dart_StackTrace trace,
+                            int frame_index,
+                            Dart_ActivationFrame* frame);
+
+
+/**
+ * Returns information about the given activation frame.
+ * \function_name receives a string handle with the qualified
+ *    function name.
+ * \script_url receives a string handle with the url of the
+ *    source script that contains the frame's function.
+ * \line_number receives the line number in the script.
+ *
+ * Any or all of the out parameters above may be NULL.
+ *
+ * Requires there to be a current isolate.
+ *
+ * \return A handle to the True object if no error occurs.
+ */
+DART_EXPORT Dart_Handle Dart_ActivationFrameInfo(
+                            Dart_ActivationFrame activation_frame,
+                            Dart_Handle* function_name,
+                            Dart_Handle* script_url,
+                            intptr_t* line_number);
+
+
 #endif  // INCLUDE_DART_DEBUGGER_API_H_