Skip to content

Commit

Permalink
Add Thread-Bound Data to the documented JS API
Browse files Browse the repository at this point in the history
As discussed in #30 and #37, add a JS API that allows arbitrary objects to be
wrapped and converted to shared externrefs with dynamic checks ensuring the
wrapped object is only ever observed on the original thread. Refer to the
existing FAQ entry for discussion on how the lifetimes of the wrapper and
wrapped object might interact.

Resolves #37.
  • Loading branch information
tlively committed Apr 15, 2024
1 parent 4f6292c commit 8708200
Showing 1 changed file with 20 additions and 0 deletions.
20 changes: 20 additions & 0 deletions proposals/shared-everything-threads/Overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -589,6 +589,26 @@ entire thread or agent.
[jspi]: https://github.com/WebAssembly/js-promise-integration
[realm]: https://tc39.es/ecma262/#realm

#### Thread-Bound Data

Just as WebAssembly produces expect to be able to call JS functions, they also expect to be able to
hold handles to JS objects. For example, a language compiled to shared WasmGC may need to hold
references to DOM nodes in some of its shared objects. Normally this would be disallowed because DOM
nodes are not shareable and shared-to-unshared references are disallowed. To bridge this gap, we
need a utility that allows shared-to-unshared objects as an exception to the general rule, assuming
that Web GCs can support such an exception (see the discussion in the FAQ below). To avoid
complicating the core language and forcing every non-Web engine to support shared-to-unshared edges,
this utility is a new JS API.

`ThreadBoundData` is a shared JS object that wraps any other arbitrary JS object. `ThreadBoundData`
provides access to the wrapped object via a `get` method that throws an exception when called on any
thread besides the thread that owns the wrapped object, ensuring that the wrapped object can be
observed only on one thread, even if the `ThreadBoundData` is shared between multiple threads. Like
other shared JS objects, it can be converted to a shared externref on the JS/Wasm boundary.

See the FAQ below for discussion on how the lifetime of the shared `ThreadBoundData` may affect the
lifetime of the wrapped object.

#### Waiter Queue API

In the same way the linear memory wait and notify operations are mirrored and interoperable with
Expand Down

0 comments on commit 8708200

Please sign in to comment.