v8
3.11.10 (node 0.8.28)
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
// Redistribution and use in source and binary forms, with or without
3
// modification, are permitted provided that the following conditions are
4
// met:
5
//
6
// * Redistributions of source code must retain the above copyright
7
// notice, this list of conditions and the following disclaimer.
8
// * Redistributions in binary form must reproduce the above
9
// copyright notice, this list of conditions and the following
10
// disclaimer in the documentation and/or other materials provided
11
// with the distribution.
12
// * Neither the name of Google Inc. nor the names of its
13
// contributors may be used to endorse or promote products derived
14
// from this software without specific prior written permission.
15
//
16
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
17
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
18
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
19
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
20
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
21
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
22
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
26
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27
28
#
ifndef
V8_V8_DEBUG_H_
29
#
define
V8_V8_DEBUG_H_
30
31
#
include
"v8.h"
32
33
#
ifdef
_WIN32
34
typedef
int
int32_t;
35
typedef
unsigned
int
uint32_t;
36
typedef
unsigned
short
uint16_t;
// NOLINT
37
typedef
long
long
int64_t;
// NOLINT
38
39
// Setup for Windows DLL export/import. See v8.h in this directory for
40
// information on how to build/use V8 as a DLL.
41
#
if
defined
(
BUILDING_V8_SHARED
)
&&
defined
(
USING_V8_SHARED
)
42
#
error
both
BUILDING_V8_SHARED
and
USING_V8_SHARED
are
set
-
please
check
the
43
build
configuration
to
ensure
that
at
most
one
of
these
is
set
44
#
endif
45
46
#
ifdef
BUILDING_V8_SHARED
47
#
define
EXPORT
__declspec
(
dllexport
)
48
#
elif
USING_V8_SHARED
49
#
define
EXPORT
__declspec
(
dllimport
)
50
#
else
51
#
define
EXPORT
52
#
endif
53
54
#
else
// _WIN32
55
56
// Setup for Linux shared library export. See v8.h in this directory for
57
// information on how to build/use V8 as shared library.
58
#
if
defined
(
__GNUC__
)
&&
(
__GNUC__
>=
4
)
&&
defined
(
V8_SHARED
)
59
#
define
EXPORT
__attribute__
(
(
visibility
(
"default"
)
)
)
60
#
else
// defined(__GNUC__) && (__GNUC__ >= 4)
61
#
define
EXPORT
62
#
endif
// defined(__GNUC__) && (__GNUC__ >= 4)
63
64
#
endif
// _WIN32
65
66
67
/**
68
* Debugger support for the V8 JavaScript engine.
69
*/
70
namespace
v8
{
71
72
// Debug events which can occur in the V8 JavaScript engine.
73
enum
DebugEvent
{
74
Break
= 1,
75
Exception
= 2,
76
NewFunction
= 3,
77
BeforeCompile
= 4,
78
AfterCompile
= 5,
79
ScriptCollected
= 6,
80
BreakForCommand
= 7
81
};
82
83
84
class
EXPORT
Debug
{
85
public
:
86
/**
87
* A client object passed to the v8 debugger whose ownership will be taken by
88
* it. v8 is always responsible for deleting the object.
89
*/
90
class
ClientData
{
91
public
:
92
virtual
~
ClientData
() {}
93
};
94
95
96
/**
97
* A message object passed to the debug message handler.
98
*/
99
class
Message
{
100
public
:
101
/**
102
* Check type of message.
103
*/
104
virtual
bool
IsEvent
()
const
= 0;
105
virtual
bool
IsResponse
()
const
= 0;
106
virtual
DebugEvent
GetEvent
()
const
= 0;
107
108
/**
109
* Indicate whether this is a response to a continue command which will
110
* start the VM running after this is processed.
111
*/
112
virtual
bool
WillStartRunning
()
const
= 0;
113
114
/**
115
* Access to execution state and event data. Don't store these cross
116
* callbacks as their content becomes invalid. These objects are from the
117
* debugger event that started the debug message loop.
118
*/
119
virtual
Handle
<
Object
>
GetExecutionState
()
const
= 0;
120
virtual
Handle
<
Object
>
GetEventData
()
const
= 0;
121
122
/**
123
* Get the debugger protocol JSON.
124
*/
125
virtual
Handle
<
String
>
GetJSON
()
const
= 0;
126
127
/**
128
* Get the context active when the debug event happened. Note this is not
129
* the current active context as the JavaScript part of the debugger is
130
* running in its own context which is entered at this point.
131
*/
132
virtual
Handle
<
Context
>
GetEventContext
()
const
= 0;
133
134
/**
135
* Client data passed with the corresponding request if any. This is the
136
* client_data data value passed into Debug::SendCommand along with the
137
* request that led to the message or NULL if the message is an event. The
138
* debugger takes ownership of the data and will delete it even if there is
139
* no message handler.
140
*/
141
virtual
ClientData
*
GetClientData
()
const
= 0;
142
143
virtual
~
Message
() {}
144
};
145
146
147
/**
148
* An event details object passed to the debug event listener.
149
*/
150
class
EventDetails
{
151
public
:
152
/**
153
* Event type.
154
*/
155
virtual
DebugEvent
GetEvent
()
const
= 0;
156
157
/**
158
* Access to execution state and event data of the debug event. Don't store
159
* these cross callbacks as their content becomes invalid.
160
*/
161
virtual
Handle
<
Object
>
GetExecutionState
()
const
= 0;
162
virtual
Handle
<
Object
>
GetEventData
()
const
= 0;
163
164
/**
165
* Get the context active when the debug event happened. Note this is not
166
* the current active context as the JavaScript part of the debugger is
167
* running in its own context which is entered at this point.
168
*/
169
virtual
Handle
<
Context
>
GetEventContext
()
const
= 0;
170
171
/**
172
* Client data passed with the corresponding callback when it was
173
* registered.
174
*/
175
virtual
Handle
<
Value
>
GetCallbackData
()
const
= 0;
176
177
/**
178
* Client data passed to DebugBreakForCommand function. The
179
* debugger takes ownership of the data and will delete it even if
180
* there is no message handler.
181
*/
182
virtual
ClientData
*
GetClientData
()
const
= 0;
183
184
virtual
~
EventDetails
() {}
185
};
186
187
188
/**
189
* Debug event callback function.
190
*
191
* \param event the type of the debug event that triggered the callback
192
* (enum DebugEvent)
193
* \param exec_state execution state (JavaScript object)
194
* \param event_data event specific data (JavaScript object)
195
* \param data value passed by the user to SetDebugEventListener
196
*/
197
typedef
void
(*
EventCallback
)(
DebugEvent
event,
198
Handle
<
Object
> exec_state,
199
Handle
<
Object
> event_data,
200
Handle
<
Value
> data);
201
202
/**
203
* Debug event callback function.
204
*
205
* \param event_details object providing information about the debug event
206
*
207
* A EventCallback2 does not take possession of the event data,
208
* and must not rely on the data persisting after the handler returns.
209
*/
210
typedef
void
(*
EventCallback2
)(
const
EventDetails
& event_details);
211
212
/**
213
* Debug message callback function.
214
*
215
* \param message the debug message handler message object
216
* \param length length of the message
217
* \param client_data the data value passed when registering the message handler
218
219
* A MessageHandler does not take possession of the message string,
220
* and must not rely on the data persisting after the handler returns.
221
*
222
* This message handler is deprecated. Use MessageHandler2 instead.
223
*/
224
typedef
void
(*
MessageHandler
)(
const
uint16_t* message,
int
length,
225
ClientData
* client_data);
226
227
/**
228
* Debug message callback function.
229
*
230
* \param message the debug message handler message object
231
*
232
* A MessageHandler does not take possession of the message data,
233
* and must not rely on the data persisting after the handler returns.
234
*/
235
typedef
void
(*
MessageHandler2
)(
const
Message
& message);
236
237
/**
238
* Debug host dispatch callback function.
239
*/
240
typedef
void
(*
HostDispatchHandler
)();
241
242
/**
243
* Callback function for the host to ensure debug messages are processed.
244
*/
245
typedef
void
(*
DebugMessageDispatchHandler
)();
246
247
// Set a C debug event listener.
248
static
bool
SetDebugEventListener
(
EventCallback
that,
249
Handle
<
Value
> data =
Handle
<
Value
>
(
)
);
250
static
bool
SetDebugEventListener2
(
EventCallback2
that,
251
Handle
<
Value
> data =
Handle
<
Value
>
(
)
);
252
253
// Set a JavaScript debug event listener.
254
static
bool
SetDebugEventListener
(
v8
::
Handle
<
v8
::
Object
> that,
255
Handle
<
Value
> data =
Handle
<
Value
>
(
)
);
256
257
// Schedule a debugger break to happen when JavaScript code is run
258
// in the given isolate. If no isolate is provided the default
259
// isolate is used.
260
static
void
DebugBreak
(
Isolate
* isolate = NULL);
261
262
// Remove scheduled debugger break in given isolate if it has not
263
// happened yet. If no isolate is provided the default isolate is
264
// used.
265
static
void
CancelDebugBreak
(
Isolate
* isolate = NULL);
266
267
// Break execution of JavaScript in the given isolate (this method
268
// can be invoked from a non-VM thread) for further client command
269
// execution on a VM thread. Client data is then passed in
270
// EventDetails to EventCallback at the moment when the VM actually
271
// stops. If no isolate is provided the default isolate is used.
272
static
void
DebugBreakForCommand
(
ClientData
* data = NULL,
273
Isolate
* isolate = NULL);
274
275
// Message based interface. The message protocol is JSON. NOTE the message
276
// handler thread is not supported any more parameter must be false.
277
static
void
SetMessageHandler
(
MessageHandler
handler,
278
bool
message_handler_thread =
false
);
279
static
void
SetMessageHandler2
(
MessageHandler2
handler);
280
281
// If no isolate is provided the default isolate is
282
// used.
283
static
void
SendCommand
(
const
uint16_t* command,
int
length,
284
ClientData
* client_data = NULL,
285
Isolate
* isolate = NULL);
286
287
// Dispatch interface.
288
static
void
SetHostDispatchHandler
(
HostDispatchHandler
handler,
289
int
period = 100);
290
291
/**
292
* Register a callback function to be called when a debug message has been
293
* received and is ready to be processed. For the debug messages to be
294
* processed V8 needs to be entered, and in certain embedding scenarios this
295
* callback can be used to make sure V8 is entered for the debug message to
296
* be processed. Note that debug messages will only be processed if there is
297
* a V8 break. This can happen automatically by using the option
298
* --debugger-auto-break.
299
* \param provide_locker requires that V8 acquires v8::Locker for you before
300
* calling handler
301
*/
302
static
void
SetDebugMessageDispatchHandler
(
303
DebugMessageDispatchHandler
handler,
bool
provide_locker =
false
);
304
305
/**
306
* Run a JavaScript function in the debugger.
307
* \param fun the function to call
308
* \param data passed as second argument to the function
309
* With this call the debugger is entered and the function specified is called
310
* with the execution state as the first argument. This makes it possible to
311
* get access to information otherwise not available during normal JavaScript
312
* execution e.g. details on stack frames. Receiver of the function call will
313
* be the debugger context global object, however this is a subject to change.
314
* The following example shows a JavaScript function which when passed to
315
* v8::Debug::Call will return the current line of JavaScript execution.
316
*
317
* \code
318
* function frame_source_line(exec_state) {
319
* return exec_state.frame(0).sourceLine();
320
* }
321
* \endcode
322
*/
323
static
Local
<
Value
>
Call
(
v8
::
Handle
<
v8
::
Function
> fun,
324
Handle
<
Value
> data =
Handle
<
Value
>
(
)
);
325
326
/**
327
* Returns a mirror object for the given object.
328
*/
329
static
Local
<
Value
>
GetMirror
(
v8
::
Handle
<
v8
::
Value
> obj);
330
331
/**
332
* Enable the V8 builtin debug agent. The debugger agent will listen on the
333
* supplied TCP/IP port for remote debugger connection.
334
* \param name the name of the embedding application
335
* \param port the TCP/IP port to listen on
336
* \param wait_for_connection whether V8 should pause on a first statement
337
* allowing remote debugger to connect before anything interesting happened
338
*/
339
static
bool
EnableAgent
(
const
char
* name,
int
port,
340
bool
wait_for_connection =
false
);
341
342
/**
343
* Disable the V8 builtin debug agent. The TCP/IP connection will be closed.
344
*/
345
static
void
DisableAgent
();
346
347
/**
348
* Makes V8 process all pending debug messages.
349
*
350
* From V8 point of view all debug messages come asynchronously (e.g. from
351
* remote debugger) but they all must be handled synchronously: V8 cannot
352
* do 2 things at one time so normal script execution must be interrupted
353
* for a while.
354
*
355
* Generally when message arrives V8 may be in one of 3 states:
356
* 1. V8 is running script; V8 will automatically interrupt and process all
357
* pending messages (however auto_break flag should be enabled);
358
* 2. V8 is suspended on debug breakpoint; in this state V8 is dedicated
359
* to reading and processing debug messages;
360
* 3. V8 is not running at all or has called some long-working C++ function;
361
* by default it means that processing of all debug messages will be deferred
362
* until V8 gets control again; however, embedding application may improve
363
* this by manually calling this method.
364
*
365
* It makes sense to call this method whenever a new debug message arrived and
366
* V8 is not already running. Method v8::Debug::SetDebugMessageDispatchHandler
367
* should help with the former condition.
368
*
369
* Technically this method in many senses is equivalent to executing empty
370
* script:
371
* 1. It does nothing except for processing all pending debug messages.
372
* 2. It should be invoked with the same precautions and from the same context
373
* as V8 script would be invoked from, because:
374
* a. with "evaluate" command it can do whatever normal script can do,
375
* including all native calls;
376
* b. no other thread should call V8 while this method is running
377
* (v8::Locker may be used here).
378
*
379
* "Evaluate" debug command behavior currently is not specified in scope
380
* of this method.
381
*/
382
static
void
ProcessDebugMessages
();
383
384
/**
385
* Debugger is running in its own context which is entered while debugger
386
* messages are being dispatched. This is an explicit getter for this
387
* debugger context. Note that the content of the debugger context is subject
388
* to change.
389
*/
390
static
Local
<
Context
>
GetDebugContext
();
391
};
392
393
394
}
// namespace v8
395
396
397
#
undef
EXPORT
398
399
400
#
endif
// V8_V8_DEBUG_H_
include
v8-debug.h
Generated on Fri Oct 29 2021 20:05:12 for v8 by
1.9.1