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::*;
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    // We would like to give this a better name with `js_name`, but `js_name`
94    #[wasm_bindgen(js_name = "web_thread$Client")]
95    type Client;
96    #[wasm_bindgen(constructor, js_class = "web_thread$Client")]
97    fn new(module: JsValue, memory: JsValue) -> Client;
98
99    #[wasm_bindgen(js_class = "web_thread$Client", method)]
100    fn run(
101        this: &Client,
102        code: JsValue,
103        context: JsValue,
104        transfer: js_sys::Array,
105    ) -> js_sys::Promise;
106
107    #[wasm_bindgen(js_class = "web_thread$Client", method)]
108    fn destroy(this: &Client);
109}
110
111/// A representation of a JavaScript thread (Web worker with shared memory).
112pub struct Thread(Client);
113
114pin_project_lite::pin_project! {
115    /// A task that's been spawned on a [`Thread`].
116    ///
117    /// Dropping the thread before the task is complete will result in the
118    /// task erroring.
119    pub struct Task<T> {
120        result: future::Either<
121            future::MapErr<JsFuture, fn(JsValue) -> Error>,
122            future::Ready<Result<JsValue>>,
123        >,
124        _phantom: std::marker::PhantomData<T>,
125    }
126}
127
128impl<T: Post> Future for Task<T> {
129    type Output = Result<T>;
130
131    fn poll(mut self: Pin<&mut Self>, context: &mut Context<'_>) -> Poll<Self::Output> {
132        Poll::Ready(Ok(T::from_js(ready!(self.result.poll_unpin(context))?)?))
133    }
134}
135
136pin_project_lite::pin_project! {
137    /// A [`Task`] with a `Send` output.
138    /// See [`Task::run_send`] for usage.
139    pub struct SendTask<T> {
140        task: Task<()>,
141        receiver: oneshot::Receiver<T>,
142    }
143}
144
145impl<T: Send> Future for SendTask<T> {
146    type Output = Result<T>;
147
148    fn poll(mut self: Pin<&mut Self>, context: &mut Context<'_>) -> Poll<Self::Output> {
149        ready!(self.task.poll_unpin(context))?;
150        Poll::Ready(Ok(
151            ready!(self.receiver.poll_unpin(context)).expect("task already completed successfully")
152        ))
153    }
154}
155
156impl Thread {
157    /// Spawn a new thread.
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: Default::default(),
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 Drop for Thread {
226    fn drop(&mut self) {
227        self.0.destroy();
228    }
229}
230
231/// The type of errors that can be thrown in the course of executing a thread.
232pub type Error = error::Error;
233
234type JsTask = std::pin::Pin<Box<dyn Future<Output = Result<Postable, JsValue>>>>;
235type RemoteTask = Box<dyn FnOnce(JsValue) -> JsTask + Send>;
236
237struct Code {
238    // The second box allows us to represent this as a thin pointer
239    // (Wasm: u32) which, unlike fat pointers (Wasm: u64) is within
240    // the [JavaScript safe integer
241    // range](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isSafeInteger).
242    code: Option<Box<RemoteTask>>,
243}
244
245impl Code {
246    fn new<F: Future<Output: Post> + 'static, Context: Post>(
247        code: impl FnOnce(Context) -> F + Send + 'static,
248    ) -> Self {
249        Self {
250            code: Some(Box::new(Box::new(|context| {
251                Box::pin(async move { Ok(Postable::new(code(Context::from_js(context)?).await)?) })
252            }))),
253        }
254    }
255
256    async fn call_once(mut self, context: JsValue) -> Result<Postable, JsValue> {
257        (*self.code.take().expect("code called more than once"))(context).await
258    }
259
260    /// # Safety
261    ///
262    /// Must only be called on `JsValue`s created with the
263    /// `Into<JsValue>` implementation.
264    unsafe fn from_js_value(js_value: &JsValue) -> Self {
265        // We know this doesn't truncate or lose sign as the `f64` is
266        // a representation of a 32-bit pointer.
267        #![allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
268
269        Self {
270            code: Some(unsafe { Box::from_raw(js_value.as_f64().unwrap() as u32 as _) }),
271        }
272    }
273}
274
275impl From<Code> for JsValue {
276    fn from(code: Code) -> Self {
277        (Box::into_raw(code.code.expect("serializing consumed code")) as u32).into()
278    }
279}
280
281#[doc(hidden)]
282#[wasm_bindgen]
283pub async unsafe fn __web_thread_worker_entry_point(
284    code: JsValue,
285    context: JsValue,
286) -> Result<JsValue, JsValue> {
287    let code = unsafe { Code::from_js_value(&code) };
288    serde_wasm_bindgen::to_value(&code.call_once(context).await?).map_err(Into::into)
289}
290
291#[wasm_bindgen(module = "/src/worker.js")]
292extern "C" {
293    // This is here just to ensure `/src/worker.js` makes it into the
294    // bundle produced by `wasm-bindgen`.
295    fn _non_existent_function();
296}
web_thread/lib.rs

web_thread/
lib.rs
