OLD | NEW |
1 # Design of V8 bindings | 1 # Design of V8 bindings |
2 | 2 |
3 This document explains key concepts in the V8 binding architecture | 3 This document explains key concepts in the V8 binding architecture |
4 except the lifetime management of DOM wrappers. | 4 except the lifetime management of DOM wrappers. |
5 See [V8GCController.md](V8GCController.md) to learn the lifetime management. | 5 See [V8GCController.md](V8GCController.md) to learn the lifetime management. |
6 | 6 |
7 [TOC] | 7 [TOC] |
8 | 8 |
9 ## Isolate | 9 ## Isolate |
10 | 10 |
11 An isolate is a concept of a thread in V8. | 11 An isolate is a concept of an instance in V8. |
12 Isolates and threads are in 1:1 relationship. | 12 In Blink, isolates and threads are in 1:1 relationship. |
13 One isolate is associated with the main thread. | 13 One isolate is associated with the main thread. |
14 One isolate is associated with one worker thread. | 14 One isolate is associated with one worker thread. |
| 15 An exception is a compositor worker where one isolate is shared by multiple |
| 16 compositor workers. |
15 | 17 |
16 ## Context | 18 ## Context |
17 | 19 |
18 A context is a concept of a global variable scope in V8. | 20 A context is a concept of a global variable scope in V8. |
19 Roughly speaking, one window object corresponds to one context. | 21 Roughly speaking, one window object corresponds to one context. |
20 For example, `<iframe>` has a window object different from a window object | 22 For example, `<iframe>` has a window object different from a window object |
21 of its parent frame. So the context of the `<iframe>` is different from | 23 of its parent frame. So the context of the `<iframe>` is different from |
22 the context of the parent frame. Since these contexts create their own | 24 the context of the parent frame. Since these contexts create their own |
23 global variable scopes, global variables and prototype chains of the `<iframe>` | 25 global variable scopes, global variables and prototype chains of the `<iframe>` |
24 are isolated from the ones of the parent frame. | 26 are isolated from the ones of the parent frame. |
(...skipping 74 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
99 | 101 |
100 There is a second stack that operates on a much coarser granularity. | 102 There is a second stack that operates on a much coarser granularity. |
101 This stack is managed by V8 binding (not by V8). | 103 This stack is managed by V8 binding (not by V8). |
102 When V8 binding invokes JavaScript, V8 binding enters a context | 104 When V8 binding invokes JavaScript, V8 binding enters a context |
103 and pushes the context onto the stack. | 105 and pushes the context onto the stack. |
104 The JavaScript starts running on the context. When the JavaScript finishes | 106 The JavaScript starts running on the context. When the JavaScript finishes |
105 and the control returns back to V8 binding, V8 binding pops the context | 107 and the control returns back to V8 binding, V8 binding pops the context |
106 from the stack. Given that the control between V8 binding and V8 can be nested | 108 from the stack. Given that the control between V8 binding and V8 can be nested |
107 (i.e., V8 binding invokes JavaScript, which calls into V8 binding, | 109 (i.e., V8 binding invokes JavaScript, which calls into V8 binding, |
108 which invokes another JavaScript etc), these contexts form a stack. | 110 which invokes another JavaScript etc), these contexts form a stack. |
109 The pushing and popping are done by calling v8::Context::Enter() and | 111 The pushing and popping are done by any V8 API that takes a context argument |
110 v8::Context::Exit() (or v8::Context::Scope). We call the most recently entered | 112 or by explicitly calling v8::Context::Enter() and v8::Context::Exit(). |
111 context an entered context. | 113 We call the most recently entered context an entered context. |
112 | 114 |
113 In the above example, at the point when func() is running, | 115 In the above example, at the point when func() is running, |
114 the entered context is the context of the main frame | 116 the entered context is the context of the main frame |
115 (not the context of `<iframe>`). | 117 (not the context of `<iframe>`). |
116 | 118 |
117 The entered context is a concept to implement the | 119 The entered context is a concept to implement the |
118 [entry settings object](https://html.spec.whatwg.org/multipage/webappapis.html#e
ntry-settings-object) | 120 [entry settings object](https://html.spec.whatwg.org/multipage/webappapis.html#e
ntry-settings-object) |
119 of the HTML spec. The current context is a concept to implement the | 121 of the HTML spec. The current context is a concept to implement the |
120 [incumbent settings object](https://html.spec.whatwg.org/multipage/webappapis.ht
ml#incumbent-settings-object) | 122 [incumbent settings object](https://html.spec.whatwg.org/multipage/webappapis.ht
ml#incumbent-settings-object) |
121 of the HTML spec. | 123 of the HTML spec. |
122 | 124 |
123 In summary, the entered context is a context from which the current JavaScript | 125 In summary, the entered context is a context from which the current JavaScript |
124 execution was started. The current context is a context of | 126 execution was started. The current context is a context of |
125 the JavaScript function that is currently running. | 127 the JavaScript function that is currently running. |
126 | 128 |
| 129 There is another special context called a debugger context. |
| 130 If a debugger is active, the debugger context may be inserted to |
| 131 the context stack. |
| 132 |
127 ## World | 133 ## World |
128 | 134 |
129 A world is a concept to sandbox DOM wrappers among content scripts of | 135 A world is a concept to sandbox DOM wrappers among content scripts of |
130 Chrome extensions. There are three kinds of worlds: a main world, | 136 Chrome extensions. There are three kinds of worlds: a main world, |
131 an isolated world and a worker world. | 137 an isolated world and a worker world. |
132 A main world is a world where a normal JavaScript downloaded from the web | 138 A main world is a world where a normal JavaScript downloaded from the web |
133 is executed. | 139 is executed. |
134 An isolated world is a world where a content script of a Chrome extension. | 140 An isolated world is a world where a content script of a Chrome extension. |
135 An isolate of the main thread has 1 main world and N isolated worlds. | 141 An isolate of the main thread has 1 main world and N isolated worlds. |
136 An isolate of a worker thread has 1 worker world and 0 isolated world. | 142 An isolate of a worker thread has 1 worker world and 0 isolated world. |
(...skipping 49 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
186 For example, when the main thread is operating on a frame X using a JavaScript | 192 For example, when the main thread is operating on a frame X using a JavaScript |
187 in a world Y, the current context is set to a context for the pair of (X, Y). | 193 in a world Y, the current context is set to a context for the pair of (X, Y). |
188 The current context of the main thread changes over its lifetime. | 194 The current context of the main thread changes over its lifetime. |
189 | 195 |
190 On the other hand, a worker thread has 0 frame and 1 world. | 196 On the other hand, a worker thread has 0 frame and 1 world. |
191 Thus a worker thread has only 1 context. | 197 Thus a worker thread has only 1 context. |
192 The current context of the worker thread never changes. | 198 The current context of the worker thread never changes. |
193 | 199 |
194 ## DOM wrappers and worlds | 200 ## DOM wrappers and worlds |
195 | 201 |
196 For compatibility reasons (although this is not speced), | 202 For compatibility reasons, we need to make sure that the same DOM wrapper |
197 we need to make sure that the same DOM wrapper is returned to JavaScript | 203 is returned to JavaScript as long as the underlying C++ DOM object is alive. |
198 as long as the underlying C++ DOM object is alive. | |
199 We should not return different DOM wrappers for the same C++ DOM object. | 204 We should not return different DOM wrappers for the same C++ DOM object. |
200 | 205 |
201 Here is an example: | 206 Here is an example: |
202 | 207 |
203 ```html | 208 ```html |
204 var div = document.createElement("div"); | 209 var div = document.createElement("div"); |
205 div.foo = 1234; // expando | 210 div.foo = 1234; // expando |
206 var p = document.createElement("p"); | 211 var p = document.createElement("p"); |
207 p.appendChild(div); | 212 p.appendChild(div); |
208 div = null; | 213 div = null; |
(...skipping 41 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
250 // iframe.html | 255 // iframe.html |
251 <script> | 256 <script> |
252 </script> | 257 </script> |
253 ``` | 258 ``` |
254 | 259 |
255 To make sure that a DOM wrapper is created in a correct context, you need to | 260 To make sure that a DOM wrapper is created in a correct context, you need to |
256 make sure that the current context must be set to the correct context | 261 make sure that the current context must be set to the correct context |
257 whenever you call toV8(). If you're not sure what context to use, | 262 whenever you call toV8(). If you're not sure what context to use, |
258 ask haraken@chromium.org. | 263 ask haraken@chromium.org. |
259 | 264 |
OLD | NEW |