web_thread/
lib.rs

1/*!
2# `web-thread`
3
4A crate for long-running, shared-memory threads in a browser context
5for use with
6[`wasm-bindgen`](https://github.com/wasm-bindgen/wasm-bindgen).
7Supports sending non-`Send` data across the boundary using
8`postMessage` and
9[transfer](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Transferable_objects).
10
11## Requirements
12
13Like all Web threading solutions, this crate requires Wasm atomics,
14bulk memory, and mutable globals:
15
16`.cargo/config.toml`
17
18```toml
19[target.wasm32-unknown-unknown]
20rustflags = [
21    "-C", "target-feature=+atomics,+bulk-memory,+mutable-globals",
22]
23```
24
25as well as cross-origin isolation on the serving Web page in order to
26[enable the use of
27`SharedArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer#security_requirements),
28i.e. the HTTP headers
29
30```text
31Cross-Origin-Opener-Policy: same-origin
32Cross-Origin-Embedder-Policy: require-corp
33```
34
35The `credentialless` value for `Cross-Origin-Embedder-Policy` should
36also work, but at the time of writing is not supported in Safari.
37
38## Linking the binary
39
40Since this crate can't know the location of your shim script and Wasm
41binary ahead of time, you must make the module identifier
42`web-thread:wasm-shim` resolve to the path of your `wasm-bindgen` shim
43script.  This can be done with a bundler such as
44[Vite](https://vite.dev/) or [Webpack](https://webpack.js.org/), or by
45using a source-transformation tool such as
46[`tsc-alias`](https://www.npmjs.com/package/tsc-alias?activeTab=readme):
47
48`tsconfig.json`
49
50```json
51{
52    "compilerOptions": {
53        "baseUrl": "./",
54        "paths": {
55            "web-thread:wasm-shim": ["./src/wasm/my-library.js"]
56        }
57    },
58    "tsc-alias": {
59        "resolveFullPaths": true
60    }
61}
62```
63
64Turbopack is currently not supported due to an open issue when
65processing cyclic dependencies.  See the following discussions for
66more information:
67
68* [Turbopack: dynamic cyclical import causes infinite loop (#85119)](https://github.com/vercel/next.js/issues/85119)
69* [Next.js v15.2.2 Turbopack Dev server stuck in compiling + extreme CPU/memory usage (#77102)](https://github.com/vercel/next.js/discussions/77102)
70* [Eliminate the circular dependency between the main loader and the worker (#20580)](https://github.com/emscripten-core/emscripten/issues/20580)
71
72*/
73
74mod error;
75
76mod post;
77use std::{
78    pin::Pin,
79    task::{Context, Poll, ready},
80};
81
82use futures::{FutureExt as _, TryFutureExt as _, channel::oneshot, future};
83use post::Postable;
84pub use post::{AsJs, Post, PostExt};
85use wasm_bindgen::prelude::{JsValue, wasm_bindgen};
86use wasm_bindgen_futures::JsFuture;
87use web_sys::{js_sys, wasm_bindgen};
88
89pub type Result<T, E = Error> = std::result::Result<T, E>;
90
91#[wasm_bindgen(module = "/src/Client.js")]
92extern "C" {
93    #[wasm_bindgen(js_name = "web_thread$Client")]
94    type Client;
95    #[wasm_bindgen(constructor, js_class = "web_thread$Client")]
96    fn new(module: JsValue, memory: JsValue) -> Client;
97
98    #[wasm_bindgen(js_class = "web_thread$Client", method)]
99    fn run(
100        this: &Client,
101        code: JsValue,
102        context: JsValue,
103        transfer: js_sys::Array,
104    ) -> js_sys::Promise;
105
106    #[wasm_bindgen(js_class = "web_thread$Client", method)]
107    fn destroy(this: &Client);
108}
109
110/// A representation of a JavaScript thread (Web worker with shared memory).
111pub struct Thread(Client);
112
113pin_project_lite::pin_project! {
114    /// A task that's been spawned on a [`Thread`].
115    ///
116    /// Dropping the thread before the task is complete will result in the
117    /// task erroring.
118    pub struct Task<T> {
119        result: future::Either<
120            future::MapErr<JsFuture, fn(JsValue) -> Error>,
121            future::Ready<Result<JsValue>>,
122        >,
123        _phantom: std::marker::PhantomData<T>,
124    }
125}
126
127impl<T: Post> Future for Task<T> {
128    type Output = Result<T>;
129
130    fn poll(mut self: Pin<&mut Self>, context: &mut Context<'_>) -> Poll<Self::Output> {
131        Poll::Ready(Ok(T::from_js(ready!(self.result.poll_unpin(context))?)?))
132    }
133}
134
135pin_project_lite::pin_project! {
136    /// A [`Task`] with a `Send` output.
137    /// See [`Thread::run_send`] for usage.
138    pub struct SendTask<T> {
139        task: Task<()>,
140        receiver: oneshot::Receiver<T>,
141    }
142}
143
144impl<T: Send> Future for SendTask<T> {
145    type Output = Result<T>;
146
147    fn poll(mut self: Pin<&mut Self>, context: &mut Context<'_>) -> Poll<Self::Output> {
148        ready!(self.task.poll_unpin(context))?;
149        Poll::Ready(Ok(
150            ready!(self.receiver.poll_unpin(context)).expect("task already completed successfully")
151        ))
152    }
153}
154
155impl Thread {
156    /// Spawn a new thread.
157    #[must_use]
158    pub fn new() -> Self {
159        Self(Client::new(wasm_bindgen::module(), wasm_bindgen::memory()))
160    }
161
162    /// Execute a function on a thread.
163    ///
164    /// The function will begin executing immediately.  The resulting
165    /// [`Task`] can be awaited to retrieve the result.
166    ///
167    /// # Arguments
168    ///
169    /// ## `context`
170    ///
171    /// A [`Post`]able context that will be sent across the thread
172    /// boundary using `postMessage` and passed to the function on the
173    /// other side.
174    ///
175    /// ## `code`
176    ///
177    /// A `FnOnce` implementation containing the code in question.
178    /// The function is async, but will run on a `Worker` so may block
179    /// (though doing so will block the thread!).  The function itself
180    /// must be `Send`, and `Send` values can be sent through in its
181    /// closure, but once executed the resulting [`Future`] will not
182    /// be moved, so needn't be `Send`.
183    pub fn run<Context: Post, F: Future<Output: Post> + 'static>(
184        &self,
185        context: Context,
186        code: impl FnOnce(Context) -> F + Send + 'static,
187    ) -> Task<F::Output> {
188        // While not syntactically consumed, the use of `postMessage`
189        // here may leave `Context` in an invalid state (setting
190        // transferred JavaScript values to `undefined`).
191        #![allow(clippy::needless_pass_by_value)]
192
193        let transfer = context.transferables();
194        Task {
195            _phantom: std::marker::PhantomData,
196            result: match context.to_js() {
197                Ok(context) => future::Either::Left(
198                    JsFuture::from(self.0.run(Code::new(code).into(), context, transfer))
199                        .map_err(Into::into),
200                ),
201                Err(error) => future::Either::Right(future::ready(Err(error.into()))),
202            },
203        }
204    }
205
206    /// Like [`Thread::run`], but the output can be sent through Rust
207    /// memory without `Post`ing.
208    pub fn run_send<Context: Post, F: Future<Output: Send> + 'static>(
209        &self,
210        context: Context,
211        code: impl FnOnce(Context) -> F + Send + 'static,
212    ) -> SendTask<F::Output> {
213        let (sender, receiver) = oneshot::channel();
214        SendTask {
215            task: self.run(context, |context| {
216                code(context).map(|outcome| {
217                    let _ = sender.send(outcome);
218                })
219            }),
220            receiver,
221        }
222    }
223}
224
225impl Default for Thread {
226    fn default() -> Self {
227        Self::new()
228    }
229}
230
231impl Drop for Thread {
232    fn drop(&mut self) {
233        self.0.destroy();
234    }
235}
236
237/// The type of errors that can be thrown in the course of executing a thread.
238pub type Error = error::Error;
239
240type JsTask = std::pin::Pin<Box<dyn Future<Output = Result<Postable, JsValue>>>>;
241type RemoteTask = Box<dyn FnOnce(JsValue) -> JsTask + Send>;
242
243struct Code {
244    // The second box allows us to represent this as a thin pointer
245    // (Wasm: u32) which, unlike fat pointers (Wasm: u64) is within
246    // the [JavaScript safe integer
247    // range](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isSafeInteger).
248    code: Option<Box<RemoteTask>>,
249}
250
251impl Code {
252    fn new<F: Future<Output: Post> + 'static, Context: Post>(
253        code: impl FnOnce(Context) -> F + Send + 'static,
254    ) -> Self {
255        Self {
256            code: Some(Box::new(Box::new(|context| {
257                Box::pin(async move { Postable::new(code(Context::from_js(context)?).await) })
258            }))),
259        }
260    }
261
262    async fn call_once(mut self, context: JsValue) -> Result<Postable, JsValue> {
263        (*self.code.take().expect("code called more than once"))(context).await
264    }
265
266    /// # Safety
267    ///
268    /// Must only be called on `JsValue`s created with the
269    /// `Into<JsValue>` implementation.
270    unsafe fn from_js_value(js_value: &JsValue) -> Self {
271        // We know this doesn't truncate or lose sign as the `f64` is
272        // a representation of a 32-bit pointer.
273        #![allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
274
275        Self {
276            code: Some(unsafe { Box::from_raw(js_value.as_f64().unwrap() as u32 as _) }),
277        }
278    }
279}
280
281impl From<Code> for JsValue {
282    fn from(code: Code) -> Self {
283        (Box::into_raw(code.code.expect("serializing consumed code")) as u32).into()
284    }
285}
286
287#[doc(hidden)]
288#[wasm_bindgen]
289pub async unsafe fn __web_thread_worker_entry_point(
290    code: JsValue,
291    context: JsValue,
292) -> Result<JsValue, JsValue> {
293    let code = unsafe { Code::from_js_value(&code) };
294    serde_wasm_bindgen::to_value(&code.call_once(context).await?).map_err(Into::into)
295}
296
297#[wasm_bindgen(module = "/src/worker.js")]
298extern "C" {
299    // This is here just to ensure `/src/worker.js` makes it into the
300    // bundle produced by `wasm-bindgen`.
301    fn _non_existent_function();
302}
web_thread/lib.rs

web_thread/
lib.rs
