Remove Global v8::Local<V8::Context>

When we create a js.Context, we create the underlying v8.Context and store it
for the duration of the page lifetime. This works because we have a global
HandleScope - the v8.Context (which is really a v8::Local<v8::Context>) is that
to the global HandleScope, effectively making it a global.

If we want to remove our global HandleScope, then we can no longer pin the
v8.Context in our js.Context. Our js.Context now only holds a v8.Global of the
v8.Context (v8::Global<v8::Context).

This PR introduces a new type, js.Local, which takes over a lot of the
functionality previously found in either js.Caller or js.Context. The simplest
way to think about it is:

1 - For v8 -> zig calls, we create a js.Caller (as always)
2 - For zig -> v8 calls, we go through the js.Context (as always)
3 - The shared functionality, which works on a v8.Context, now belongs to js.Local

For #1 (v8 -> zig), creating a js.Local for a js.Caller is really simple and
centralized. v8 largely gives us everything we need from the
FunctionCallbackInfo or PropertyCallbackInfo.  For #2, it's messier, because we
can only create a local v8::Context if we have a HandleScope, which we may or
may not.

Unfortunately, in many cases, what to do becomes the responsibility of the caller
and much of the code has to become aware of this local-ness. What does it means
for our code? The impact is on WebAPIs that store .Global. Because the global
can't do anything. You always need to convert that .Global to a local
(e.g. js.Function.Global -> js.Function).

If you're 100% sure the WebAPI is only being invoked by a v8 callback, you can
use `page.js.local.?.toLocal(some_global).call(...)` to get the local value.

If you're 100% sure the WebAPI is only being invoked by Zig, you need to create
 `js.Local.Scope` to get access to a local:

```zig
var ls: js.Local.Scope = undefined;
page.js.localScope(&ls);
defer ls.deinit();
ls.toLocal(some_global).call(...)
// can also access `&ls.local` for APIs that require a *const js.Local
```
For functions that can be invoked by either V8 or Zig, you should generally push
the responsibility to the caller by accepting a `local: *const js.Local`. If the
caller is a v8 callback, it can pass `page.js.local.?`. If the caller is a Zig
callback, it can create a `Local.Scope`.

As an alternative, it is possible to simply pass the *Page, and check
`if page.js.local == null` and, if so, create a Local.Scope. But this should only
be done for performance reasons. We currently only do this in 1 place, and it's
because the Zig caller doesn't know whether a Local will actually be needed and
it's potentially called on every element creating from the parser.
This commit is contained in:
Karl Seguin
2026-01-15 08:52:13 +08:00
parent 798ee4a4d5
commit 62aa564df1
60 changed files with 2878 additions and 2613 deletions

View File

@@ -24,7 +24,6 @@ const Selector = @import("../../browser/webapi/selector/Selector.zig");
const dump = @import("../../browser/dump.zig");
const js = @import("../../browser/js/js.zig");
const v8 = js.v8;
const Allocator = std.mem.Allocator;
@@ -273,16 +272,32 @@ fn resolveNode(cmd: anytype) !void {
const bc = cmd.browser_context orelse return error.BrowserContextNotLoaded;
const page = bc.session.currentPage() orelse return error.PageNotLoaded;
var js_context = page.js;
if (params.executionContextId) |context_id| {
if (js_context.debugContextId() != context_id) {
for (bc.isolated_worlds.items) |*isolated_world| {
js_context = &(isolated_world.executor.context orelse return error.ContextNotFound);
if (js_context.debugContextId() == context_id) {
break;
}
} else return error.ContextNotFound;
var ls: ?js.Local.Scope = null;
defer if (ls) |*_ls| {
_ls.deinit();
};
if (params.executionContextId) |context_id| blk: {
ls = undefined;
page.js.localScope(&ls.?);
if (ls.?.local.debugContextId() == context_id) {
break :blk;
}
// not the default scope, check the other ones
for (bc.isolated_worlds.items) |*isolated_world| {
ls.?.deinit();
ls = null;
const ctx = &(isolated_world.executor.context orelse return error.ContextNotFound);
ls = undefined;
ctx.localScope(&ls.?);
if (ls.?.local.debugContextId() == context_id) {
break :blk;
}
} else return error.ContextNotFound;
} else {
ls = undefined;
page.js.localScope(&ls.?);
}
const input_node_id = params.nodeId orelse params.backendNodeId orelse return error.InvalidParam;
@@ -291,7 +306,7 @@ fn resolveNode(cmd: anytype) !void {
// node._node is a *DOMNode we need this to be able to find its most derived type e.g. Node -> Element -> HTMLElement
// So we use the Node.Union when retrieve the value from the environment
const remote_object = try bc.inspector.getRemoteObject(
js_context,
&ls.?.local,
params.objectGroup orelse "",
node.dom,
);