wasmtime_wasi_threads/
lib.rs

1//! Implement [`wasi-threads`].
2//!
3//! [`wasi-threads`]: https://github.com/WebAssembly/wasi-threads
4
5use anyhow::{anyhow, Result};
6use std::panic::{catch_unwind, AssertUnwindSafe};
7use std::sync::atomic::{AtomicI32, Ordering};
8use std::sync::Arc;
9use std::thread;
10use wasmtime::{Caller, ExternType, InstancePre, Linker, Module, SharedMemory, Store};
11
12// This name is a function export designated by the wasi-threads specification:
13// https://github.com/WebAssembly/wasi-threads/#detailed-design-discussion
14const WASI_ENTRY_POINT: &str = "wasi_thread_start";
15
16pub struct WasiThreadsCtx<T> {
17    instance_pre: Arc<InstancePre<T>>,
18    tid: AtomicI32,
19}
20
21impl<T: Clone + Send + 'static> WasiThreadsCtx<T> {
22    pub fn new(module: Module, linker: Arc<Linker<T>>) -> Result<Self> {
23        let instance_pre = Arc::new(linker.instantiate_pre(&module)?);
24        let tid = AtomicI32::new(0);
25        Ok(Self { instance_pre, tid })
26    }
27
28    pub fn spawn(&self, host: T, thread_start_arg: i32) -> Result<i32> {
29        let instance_pre = self.instance_pre.clone();
30
31        // Check that the thread entry point is present. Why here? If we check
32        // for this too early, then we cannot accept modules that do not have an
33        // entry point but never spawn a thread. As pointed out in
34        // https://github.com/bytecodealliance/wasmtime/issues/6153, checking
35        // the entry point here allows wasi-threads to be compatible with more
36        // modules.
37        //
38        // As defined in the wasi-threads specification, returning a negative
39        // result here indicates to the guest module that the spawn failed.
40        if !has_entry_point(instance_pre.module()) {
41            log::error!("failed to find a wasi-threads entry point function; expected an export with name: {WASI_ENTRY_POINT}");
42            return Ok(-1);
43        }
44        if !has_correct_signature(instance_pre.module()) {
45            log::error!("the exported entry point function has an incorrect signature: expected `(i32, i32) -> ()`");
46            return Ok(-1);
47        }
48
49        let wasi_thread_id = self.next_thread_id();
50        if wasi_thread_id.is_none() {
51            log::error!("ran out of valid thread IDs");
52            return Ok(-1);
53        }
54        let wasi_thread_id = wasi_thread_id.unwrap();
55
56        // Start a Rust thread running a new instance of the current module.
57        let builder = thread::Builder::new().name(format!("wasi-thread-{wasi_thread_id}"));
58        builder.spawn(move || {
59            // Catch any panic failures in host code; e.g., if a WASI module
60            // were to crash, we want all threads to exit, not just this one.
61            let result = catch_unwind(AssertUnwindSafe(|| {
62                // Each new instance is created in its own store.
63                let mut store = Store::new(&instance_pre.module().engine(), host);
64
65                let instance = if instance_pre.module().engine().is_async() {
66                    wasmtime_wasi::runtime::in_tokio(instance_pre.instantiate_async(&mut store))
67                } else {
68                    instance_pre.instantiate(&mut store)
69                }
70                .unwrap();
71
72                let thread_entry_point = instance
73                    .get_typed_func::<(i32, i32), ()>(&mut store, WASI_ENTRY_POINT)
74                    .unwrap();
75
76                // Start the thread's entry point. Any traps or calls to
77                // `proc_exit`, by specification, should end execution for all
78                // threads. This code uses `process::exit` to do so, which is
79                // what the user expects from the CLI but probably not in a
80                // Wasmtime embedding.
81                log::trace!(
82                    "spawned thread id = {}; calling start function `{}` with: {}",
83                    wasi_thread_id,
84                    WASI_ENTRY_POINT,
85                    thread_start_arg
86                );
87                let res = if instance_pre.module().engine().is_async() {
88                    wasmtime_wasi::runtime::in_tokio(
89                        thread_entry_point
90                            .call_async(&mut store, (wasi_thread_id, thread_start_arg)),
91                    )
92                } else {
93                    thread_entry_point.call(&mut store, (wasi_thread_id, thread_start_arg))
94                };
95                match res {
96                    Ok(_) => log::trace!("exiting thread id = {} normally", wasi_thread_id),
97                    Err(e) => {
98                        log::trace!("exiting thread id = {} due to error", wasi_thread_id);
99                        let e = wasi_common::maybe_exit_on_error(e);
100                        eprintln!("Error: {e:?}");
101                        std::process::exit(1);
102                    }
103                }
104            }));
105
106            if let Err(e) = result {
107                eprintln!("wasi-thread-{wasi_thread_id} panicked: {e:?}");
108                std::process::exit(1);
109            }
110        })?;
111
112        Ok(wasi_thread_id)
113    }
114
115    /// Helper for generating valid WASI thread IDs (TID).
116    ///
117    /// Callers of `wasi_thread_spawn` expect a TID in range of 0 < TID <= 0x1FFFFFFF
118    /// to indicate a successful spawning of the thread whereas a negative
119    /// return value indicates an failure to spawn.
120    fn next_thread_id(&self) -> Option<i32> {
121        match self
122            .tid
123            .fetch_update(Ordering::Relaxed, Ordering::Relaxed, |v| match v {
124                ..=0x1ffffffe => Some(v + 1),
125                _ => None,
126            }) {
127            Ok(v) => Some(v + 1),
128            Err(_) => None,
129        }
130    }
131}
132
133/// Manually add the WASI `thread_spawn` function to the linker.
134///
135/// It is unclear what namespace the `wasi-threads` proposal should live under:
136/// it is not clear if it should be included in any of the `preview*` releases
137/// so for the time being its module namespace is simply `"wasi"` (TODO).
138pub fn add_to_linker<T: Clone + Send + 'static>(
139    linker: &mut wasmtime::Linker<T>,
140    store: &wasmtime::Store<T>,
141    module: &Module,
142    get_cx: impl Fn(&mut T) -> &WasiThreadsCtx<T> + Send + Sync + Copy + 'static,
143) -> anyhow::Result<()> {
144    linker.func_wrap(
145        "wasi",
146        "thread-spawn",
147        move |mut caller: Caller<'_, T>, start_arg: i32| -> i32 {
148            log::trace!("new thread requested via `wasi::thread_spawn` call");
149            let host = caller.data().clone();
150            let ctx = get_cx(caller.data_mut());
151            match ctx.spawn(host, start_arg) {
152                Ok(thread_id) => {
153                    assert!(thread_id >= 0, "thread_id = {thread_id}");
154                    thread_id
155                }
156                Err(e) => {
157                    log::error!("failed to spawn thread: {}", e);
158                    -1
159                }
160            }
161        },
162    )?;
163
164    // Find the shared memory import and satisfy it with a newly-created shared
165    // memory import.
166    for import in module.imports() {
167        if let Some(m) = import.ty().memory() {
168            if m.is_shared() {
169                let mem = SharedMemory::new(module.engine(), m.clone())?;
170                linker.define(store, import.module(), import.name(), mem.clone())?;
171            } else {
172                return Err(anyhow!(
173                    "memory was not shared; a `wasi-threads` must import \
174                     a shared memory as \"memory\""
175                ));
176            }
177        }
178    }
179    Ok(())
180}
181
182/// Check if wasi-threads' `wasi_thread_start` export is present.
183fn has_entry_point(module: &Module) -> bool {
184    module.get_export(WASI_ENTRY_POINT).is_some()
185}
186
187/// Check if the entry function has the correct signature `(i32, i32) -> ()`.
188fn has_correct_signature(module: &Module) -> bool {
189    match module.get_export(WASI_ENTRY_POINT) {
190        Some(ExternType::Func(ty)) => {
191            ty.params().len() == 2
192                && ty.params().nth(0).unwrap().is_i32()
193                && ty.params().nth(1).unwrap().is_i32()
194                && ty.results().len() == 0
195        }
196        _ => false,
197    }
198}
wasmtime_wasi_threads/lib.rs

wasmtime_wasi_threads/
lib.rs
