Commit 3532f55
doc: add notes on inspector breakpoints
Setting breakpoints with a same-thread inspector session should be
avoided because the program being attached and paused is exactly the
debugger itself. A worker thread inspector session or a debugger
program should be used if breakpoints are needed.
PR-URL: #51417
Fixes: #51397
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>1 parent 713afed commit 3532f55
1 file changed
Lines changed: 29 additions & 0 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -74,6 +74,9 @@ session.on('inspectorNotification', (message) => console.log(message.method)); | |||
| 74 | 74 | // Debugger.resumed | |
| 75 | 75 | ``` | |
| 76 | 76 | ||
| 77 | + > **Caveat** Breakpoints with same-thread session is not recommended, see | ||
| 78 | + > [support of breakpoints][]. | ||
| 79 | + | ||
| 77 | 80 | It is also possible to subscribe only to notifications with specific method: | |
| 78 | 81 | ||
| 79 | 82 | #### Event: `<inspector-protocol-method>`; | |
@@ -98,6 +101,9 @@ session.on('Debugger.paused', ({ params }) => { | |||
| 98 | 101 | // [ '/the/file/that/has/the/breakpoint.js:11:0' ] | |
| 99 | 102 | ``` | |
| 100 | 103 | ||
| 104 | + > **Caveat** Breakpoints with same-thread session is not recommended, see | ||
| 105 | + > [support of breakpoints][]. | ||
| 106 | + | ||
| 101 | 107 | #### `session.connect()` | |
| 102 | 108 | ||
| 103 | 109 | <!-- YAML | |
@@ -247,6 +253,9 @@ session.on('inspectorNotification', (message) => console.log(message.method)); | |||
| 247 | 253 | // Debugger.resumed | |
| 248 | 254 | ``` | |
| 249 | 255 | ||
| 256 | + > **Caveat** Breakpoints with same-thread session is not recommended, see | ||
| 257 | + > [support of breakpoints][]. | ||
| 258 | + | ||
| 250 | 259 | It is also possible to subscribe only to notifications with specific method: | |
| 251 | 260 | ||
| 252 | 261 | #### Event: `<inspector-protocol-method>`; | |
@@ -271,6 +280,9 @@ session.on('Debugger.paused', ({ params }) => { | |||
| 271 | 280 | // [ '/the/file/that/has/the/breakpoint.js:11:0' ] | |
| 272 | 281 | ``` | |
| 273 | 282 | ||
| 283 | + > **Caveat** Breakpoints with same-thread session is not recommended, see | ||
| 284 | + > [support of breakpoints][]. | ||
| 285 | + | ||
| 274 | 286 | #### `session.connect()` | |
| 275 | 287 | ||
| 276 | 288 | <!-- YAML | |
@@ -476,10 +488,27 @@ Blocks until a client (existing or connected later) has sent | |||
| 476 | 488 | ||
| 477 | 489 | An exception will be thrown if there is no active inspector. | |
| 478 | 490 | ||
| 491 | + ## Support of breakpoints | ||
| 492 | + | ||
| 493 | + The Chrome DevTools Protocol [`Debugger` domain][] allows an | ||
| 494 | + `inspector.Session` to attach to a program and set breakpoints to step through | ||
| 495 | + the codes. | ||
| 496 | + | ||
| 497 | + However, setting breakpoints with a same-thread `inspector.Session`, which is | ||
| 498 | + connected by [`session.connect()`][], should be avoided as the program being | ||
| 499 | + attached and paused is exactly the debugger itself. Instead, try connect to the | ||
| 500 | + main thread by [`session.connectToMainThread()`][] and set breakpoints in a | ||
| 501 | + worker thread, or connect with a [Debugger][] program over WebSocket | ||
| 502 | + connection. | ||
| 503 | + | ||
| 479 | 504 | [CPU Profiler]: https://chromedevtools.github.io/devtools-protocol/v8/Profiler | |
| 480 | 505 | [Chrome DevTools Protocol Viewer]: https://chromedevtools.github.io/devtools-protocol/v8/ | |
| 506 | + [Debugger]: debugger.md | ||
| 481 | 507 | [Heap Profiler]: https://chromedevtools.github.io/devtools-protocol/v8/HeapProfiler | |
| 482 | 508 | [`'Debugger.paused'`]: https://chromedevtools.github.io/devtools-protocol/v8/Debugger#event-paused | |
| 509 | + [`Debugger` domain]: https://chromedevtools.github.io/devtools-protocol/v8/Debugger | ||
| 483 | 510 | [`inspector.close()`]: #inspectorclose | |
| 484 | 511 | [`session.connect()`]: #sessionconnect | |
| 512 | + [`session.connectToMainThread()`]: #sessionconnecttomainthread | ||
| 485 | 513 | [security warning]: cli.md#warning-binding-inspector-to-a-public-ipport-combination-is-insecure | |
| 514 | + [support of breakpoints]: #support-of-breakpoints | ||
0 commit comments