1// Copyright (c) 2017, the Dart project authors. Please see the AUTHORS file
2// for details. All rights reserved. Use of this source code is governed by a
3// BSD-style license that can be found in the LICENSE file.
4
5#ifndef RUNTIME_VM_DEBUGGER_API_IMPL_TEST_H_
6#define RUNTIME_VM_DEBUGGER_API_IMPL_TEST_H_
7
8#include "include/dart_api.h"
9#include "vm/debugger.h"
10
11typedef struct _Dart_Breakpoint* Dart_Breakpoint;
12
13typedef struct _Dart_StackTrace* Dart_StackTrace;
14
15typedef struct _Dart_ActivationFrame* Dart_ActivationFrame;
16
17/**
18 * An id used to uniquely represent an Isolate in the debugger wire protocol
19 * messages.
20 */
21typedef Dart_Port Dart_IsolateId;
22
23/**
24 * ILLEGAL_ISOLATE_ID is a number guaranteed never to be associated with a
25 * valid isolate.
26 */
27#define ILLEGAL_ISOLATE_ID ILLEGAL_PORT
28
29/**
30 * Null value for breakpoint id. Guaranteed never to be associated
31 * with a valid breakpoint.
32 */
33#define ILLEGAL_BREAKPOINT_ID 0
34
35typedef void Dart_ExceptionThrownHandler(Dart_IsolateId isolate_id,
36 Dart_Handle exception_object,
37 Dart_StackTrace stack_trace);
38
39typedef enum {
40 kCreated = 0,
41 kInterrupted,
42 kShutdown,
43} Dart_IsolateEvent;
44
45/**
46 * Represents a location in Dart code.
47 */
48typedef struct {
49 Dart_Handle script_url; // Url (string) of the script.
50 int32_t library_id; // Library in which the script is loaded.
51 int32_t token_pos; // Code address.
52} Dart_CodeLocation;
53
54typedef void Dart_IsolateEventHandler(Dart_IsolateId isolate_id,
55 Dart_IsolateEvent kind);
56
57typedef void Dart_PausedEventHandler(Dart_IsolateId isolate_id,
58 intptr_t bp_id,
59 const Dart_CodeLocation& location);
60
61typedef void Dart_BreakpointResolvedHandler(Dart_IsolateId isolate_id,
62 intptr_t bp_id,
63 const Dart_CodeLocation& location);
64
65/**
66 * Returns true if the debugger can step into code of the given library.
67 *
68 * Requires there to be a current isolate.
69 *
70 * \return A handle to the True object if no error occurs.
71 */
72DART_EXPORT Dart_Handle Dart_GetLibraryDebuggable(intptr_t library_id,
73 bool* is_debuggable);
74
75/**
76 * Requets that debugging be enabled for the given library.
77 *
78 * Requires there to be a current isolate.
79 *
80 * \return A handle to the True object if no error occurs.
81 */
82DART_EXPORT Dart_Handle Dart_SetLibraryDebuggable(intptr_t library_id,
83 bool is_debuggable);
84
85/**
86 * Sets a breakpoint at line \line_number in \script_url, or the closest
87 * following line (within the same function) where a breakpoint can be set.
88 *
89 * Requires there to be a current isolate.
90 *
91 * \return A handle containing the breakpoint id, which is an integer
92 * value, or an error object if a breakpoint could not be set.
93 */
94DART_EXPORT Dart_Handle Dart_SetBreakpoint(Dart_Handle script_url,
95 intptr_t line_number);
96
97/**
98 * Returns in \trace the current stack trace, or NULL if the
99 * VM is not paused.
100 *
101 * Requires there to be a current isolate.
102 *
103 * \return A valid handle if no error occurs during the operation.
104 */
105DART_EXPORT Dart_Handle Dart_GetStackTrace(Dart_StackTrace* trace);
106
107/**
108 * Returns in \trace the stack trace associated with the error given in \handle.
109 *
110 * Requires there to be a current isolate.
111 *
112 * \return A valid handle if no error occurs during the operation.
113 */
114DART_EXPORT Dart_Handle Dart_GetStackTraceFromError(Dart_Handle error,
115 Dart_StackTrace* trace);
116
117/**
118 * Returns in \length the number of activation frames in the given
119 * stack trace.
120 *
121 * Requires there to be a current isolate.
122 *
123 * \return A handle to the True object if no error occurs.
124 */
125DART_EXPORT Dart_Handle Dart_StackTraceLength(Dart_StackTrace trace,
126 intptr_t* length);
127
128/**
129 * Returns in \frame the activation frame with index \frame_index.
130 * The activation frame at the top of stack has index 0.
131 *
132 * Requires there to be a current isolate.
133 *
134 * \return A handle to the True object if no error occurs.
135 */
136DART_EXPORT Dart_Handle Dart_GetActivationFrame(Dart_StackTrace trace,
137 int frame_index,
138 Dart_ActivationFrame* frame);
139
140/**
141 * Returns information about the given activation frame.
142 * \function_name receives a string handle with the qualified
143 * function name.
144 * \script_url receives a string handle with the url of the
145 * source script that contains the frame's function.
146 * \line_number receives the line number in the script.
147 * \col_number receives the column number in the script, or -1 if column
148 * information is not available
149 *
150 * Any or all of the out parameters above may be NULL.
151 *
152 * Requires there to be a current isolate.
153 *
154 * \return A valid handle if no error occurs during the operation.
155 */
156DART_EXPORT Dart_Handle
157Dart_ActivationFrameInfo(Dart_ActivationFrame activation_frame,
158 Dart_Handle* function_name,
159 Dart_Handle* script_url,
160 intptr_t* line_number,
161 intptr_t* column_number);
162
163/**
164 * Execute the expression given in string \expr in the context
165 * of \lib_handle library, as if it were a top-level function in it.
166 *
167 * Requires there to be a current isolate.
168 *
169 * \return A handle to the computed value, or an error object if
170 * the compilation of the expression fails, or if the evaluation throws
171 * an error.
172 */
173DART_EXPORT Dart_Handle Dart_EvaluateStaticExpr(Dart_Handle lib_handle,
174 Dart_Handle expr);
175
176/**
177 * Returns in \library_id the library id of the given \library.
178 *
179 * \return A valid handle if no error occurs during the operation.
180 */
181DART_EXPORT Dart_Handle Dart_LibraryId(Dart_Handle library,
182 intptr_t* library_id);
183
184#endif // RUNTIME_VM_DEBUGGER_API_IMPL_TEST_H_
185