v8
4.5.103 (node 4.8.7)
V8 is Google's open source JavaScript engine
v8-debug.h
Go to the documentation of this file.
1
// Copyright 2008 the V8 project authors. All rights reserved.
2
// Use of this source code is governed by a BSD-style license that can be
3
// found in the LICENSE file.
4
5
#
ifndef
V8_V8_DEBUG_H_
6
#
define
V8_V8_DEBUG_H_
7
8
#
include
"v8.h"
9
10
/**
11
* Debugger support for the V8 JavaScript engine.
12
*/
13
namespace
v8
{
14
15
// Debug events which can occur in the V8 JavaScript engine.
16
enum
DebugEvent
{
17
Break
= 1,
18
Exception
= 2,
19
NewFunction
= 3,
20
BeforeCompile
= 4,
21
AfterCompile
= 5,
22
CompileError
= 6,
23
PromiseEvent
= 7,
24
AsyncTaskEvent
= 8,
25
};
26
27
28
class
V8_EXPORT
Debug
{
29
public
:
30
/**
31
* A client object passed to the v8 debugger whose ownership will be taken by
32
* it. v8 is always responsible for deleting the object.
33
*/
34
class
ClientData
{
35
public
:
36
virtual
~
ClientData
() {}
37
};
38
39
40
/**
41
* A message object passed to the debug message handler.
42
*/
43
class
Message
{
44
public
:
45
/**
46
* Check type of message.
47
*/
48
virtual
bool
IsEvent
()
const
= 0;
49
virtual
bool
IsResponse
()
const
= 0;
50
virtual
DebugEvent
GetEvent
()
const
= 0;
51
52
/**
53
* Indicate whether this is a response to a continue command which will
54
* start the VM running after this is processed.
55
*/
56
virtual
bool
WillStartRunning
()
const
= 0;
57
58
/**
59
* Access to execution state and event data. Don't store these cross
60
* callbacks as their content becomes invalid. These objects are from the
61
* debugger event that started the debug message loop.
62
*/
63
virtual
Local
<
Object
>
GetExecutionState
()
const
= 0;
64
virtual
Local
<
Object
>
GetEventData
()
const
= 0;
65
66
/**
67
* Get the debugger protocol JSON.
68
*/
69
virtual
Local
<
String
>
GetJSON
()
const
= 0;
70
71
/**
72
* Get the context active when the debug event happened. Note this is not
73
* the current active context as the JavaScript part of the debugger is
74
* running in its own context which is entered at this point.
75
*/
76
virtual
Local
<
Context
>
GetEventContext
()
const
= 0;
77
78
/**
79
* Client data passed with the corresponding request if any. This is the
80
* client_data data value passed into Debug::SendCommand along with the
81
* request that led to the message or NULL if the message is an event. The
82
* debugger takes ownership of the data and will delete it even if there is
83
* no message handler.
84
*/
85
virtual
ClientData
*
GetClientData
()
const
= 0;
86
87
virtual
Isolate
*
GetIsolate
()
const
= 0;
88
89
virtual
~
Message
() {}
90
};
91
92
93
/**
94
* An event details object passed to the debug event listener.
95
*/
96
class
EventDetails
{
97
public
:
98
/**
99
* Event type.
100
*/
101
virtual
DebugEvent
GetEvent
()
const
= 0;
102
103
/**
104
* Access to execution state and event data of the debug event. Don't store
105
* these cross callbacks as their content becomes invalid.
106
*/
107
virtual
Local
<
Object
>
GetExecutionState
()
const
= 0;
108
virtual
Local
<
Object
>
GetEventData
()
const
= 0;
109
110
/**
111
* Get the context active when the debug event happened. Note this is not
112
* the current active context as the JavaScript part of the debugger is
113
* running in its own context which is entered at this point.
114
*/
115
virtual
Local
<
Context
>
GetEventContext
()
const
= 0;
116
117
/**
118
* Client data passed with the corresponding callback when it was
119
* registered.
120
*/
121
virtual
Local
<
Value
>
GetCallbackData
()
const
= 0;
122
123
/**
124
* Client data passed to DebugBreakForCommand function. The
125
* debugger takes ownership of the data and will delete it even if
126
* there is no message handler.
127
*/
128
virtual
ClientData
*
GetClientData
()
const
= 0;
129
130
virtual
~
EventDetails
() {}
131
};
132
133
/**
134
* Debug event callback function.
135
*
136
* \param event_details object providing information about the debug event
137
*
138
* A EventCallback2 does not take possession of the event data,
139
* and must not rely on the data persisting after the handler returns.
140
*/
141
typedef
void
(*
EventCallback
)(
const
EventDetails
& event_details);
142
143
/**
144
* Debug message callback function.
145
*
146
* \param message the debug message handler message object
147
*
148
* A MessageHandler2 does not take possession of the message data,
149
* and must not rely on the data persisting after the handler returns.
150
*/
151
typedef
void
(*
MessageHandler
)(
const
Message
& message);
152
153
/**
154
* Callback function for the host to ensure debug messages are processed.
155
*/
156
typedef
void
(*
DebugMessageDispatchHandler
)();
157
158
static
bool
SetDebugEventListener
(
EventCallback
that,
159
Local
<
Value
> data =
Local
<
Value
>
(
)
);
160
161
// Schedule a debugger break to happen when JavaScript code is run
162
// in the given isolate.
163
static
void
DebugBreak
(
Isolate
* isolate);
164
165
// Remove scheduled debugger break in given isolate if it has not
166
// happened yet.
167
static
void
CancelDebugBreak
(
Isolate
* isolate);
168
169
// Check if a debugger break is scheduled in the given isolate.
170
static
bool
CheckDebugBreak
(
Isolate
* isolate);
171
172
// Message based interface. The message protocol is JSON.
173
static
void
SetMessageHandler
(
MessageHandler
handler);
174
175
static
void
SendCommand
(
Isolate
* isolate,
176
const
uint16_t* command,
int
length,
177
ClientData
* client_data = NULL);
178
179
/**
180
* Run a JavaScript function in the debugger.
181
* \param fun the function to call
182
* \param data passed as second argument to the function
183
* With this call the debugger is entered and the function specified is called
184
* with the execution state as the first argument. This makes it possible to
185
* get access to information otherwise not available during normal JavaScript
186
* execution e.g. details on stack frames. Receiver of the function call will
187
* be the debugger context global object, however this is a subject to change.
188
* The following example shows a JavaScript function which when passed to
189
* v8::Debug::Call will return the current line of JavaScript execution.
190
*
191
* \code
192
* function frame_source_line(exec_state) {
193
* return exec_state.frame(0).sourceLine();
194
* }
195
* \endcode
196
*/
197
static
V8_DEPRECATE_SOON
(
198
"Use maybe version"
,
199
Local
<
Value
> Call(
v8
::
Local
<
v8
::
Function
> fun,
200
Local
<
Value
> data =
Local
<
Value
>
(
)
));
201
// TODO(dcarney): data arg should be a MaybeLocal
202
static
MaybeLocal
<
Value
>
Call
(
Local
<
Context
> context,
203
v8
::
Local
<
v8
::
Function
> fun,
204
Local
<
Value
> data =
Local
<
Value
>
(
)
);
205
206
/**
207
* Returns a mirror object for the given object.
208
*/
209
static
V8_DEPRECATE_SOON
(
"Use maybe version"
,
210
Local
<
Value
> GetMirror(
v8
::
Local
<
v8
::
Value
> obj));
211
static
MaybeLocal
<
Value
>
GetMirror
(
Local
<
Context
> context,
212
v8
::
Local
<
v8
::
Value
> obj);
213
214
/**
215
* Makes V8 process all pending debug messages.
216
*
217
* From V8 point of view all debug messages come asynchronously (e.g. from
218
* remote debugger) but they all must be handled synchronously: V8 cannot
219
* do 2 things at one time so normal script execution must be interrupted
220
* for a while.
221
*
222
* Generally when message arrives V8 may be in one of 3 states:
223
* 1. V8 is running script; V8 will automatically interrupt and process all
224
* pending messages;
225
* 2. V8 is suspended on debug breakpoint; in this state V8 is dedicated
226
* to reading and processing debug messages;
227
* 3. V8 is not running at all or has called some long-working C++ function;
228
* by default it means that processing of all debug messages will be deferred
229
* until V8 gets control again; however, embedding application may improve
230
* this by manually calling this method.
231
*
232
* Technically this method in many senses is equivalent to executing empty
233
* script:
234
* 1. It does nothing except for processing all pending debug messages.
235
* 2. It should be invoked with the same precautions and from the same context
236
* as V8 script would be invoked from, because:
237
* a. with "evaluate" command it can do whatever normal script can do,
238
* including all native calls;
239
* b. no other thread should call V8 while this method is running
240
* (v8::Locker may be used here).
241
*
242
* "Evaluate" debug command behavior currently is not specified in scope
243
* of this method.
244
*/
245
static
void
ProcessDebugMessages
();
246
247
/**
248
* Debugger is running in its own context which is entered while debugger
249
* messages are being dispatched. This is an explicit getter for this
250
* debugger context. Note that the content of the debugger context is subject
251
* to change. The Context exists only when the debugger is active, i.e. at
252
* least one DebugEventListener or MessageHandler is set.
253
*/
254
static
Local
<
Context
>
GetDebugContext
();
255
256
257
/**
258
* Enable/disable LiveEdit functionality for the given Isolate
259
* (default Isolate if not provided). V8 will abort if LiveEdit is
260
* unexpectedly used. LiveEdit is enabled by default.
261
*/
262
static
void
SetLiveEditEnabled
(
Isolate
* isolate,
bool
enable);
263
264
/**
265
* Returns array of internal properties specific to the value type. Result has
266
* the following format: [<name>, <value>,...,<name>, <value>]. Result array
267
* will be allocated in the current context.
268
*/
269
static
MaybeLocal
<
Array
>
GetInternalProperties
(
Isolate
* isolate,
270
Local
<
Value
> value);
271
};
272
273
274
}
// namespace v8
275
276
277
#
undef
EXPORT
278
279
280
#
endif
// V8_V8_DEBUG_H_
include
v8-debug.h
Generated on Fri Oct 29 2021 20:05:18 for v8 by
1.9.1