mirror of https://github.com/WebAssembly/wasi-sdk
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
47 lines
2.3 KiB
47 lines
2.3 KiB
# Support for Cooperative Threading
|
|
|
|
The component model specification is in the process of adding and defining
|
|
intrinsics for guests to use to implement cooperative multithreading. The goal
|
|
of this effort is to enable compiling applications using `pthread_*` style
|
|
threading APIs, for example, to work with components. These intrinsics are
|
|
described in the [component model explainer][explain] and this feature
|
|
corresponds to the 🧵 emoji. The Wasmtime runtime supports this proposal behind
|
|
the `-Wcomponent-model-threading` flag.
|
|
|
|
[explain]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/Explainer.md
|
|
|
|
Due to this feature being experimental and not officially included in any
|
|
published WASI version yet it is off-by-default in wasi-sdk. By default
|
|
`pthread_*`-style APIs either return an error (such as when spawning a thread)
|
|
or trap (such as when blocking on a condition variable). Note that for
|
|
compatibility, though, all `pthread_*` APIs are always available. The wasi-sdk
|
|
distribution, however, does enable effectively swapping out these
|
|
implementations in an opt-in basis to test out cooperative multithreading.
|
|
|
|
Assuming that you've downloaded wasi-sdk and unpacked it within `$WASI_SDK_PATH`
|
|
there is a sysroot located at `$WASI_SDK_PATH/share/wasi-sysroot/experimental-coop-threads`
|
|
which can be used to experiment with cooperative multithreading. You can use
|
|
this in your project like so:
|
|
|
|
```console
|
|
$WASI_SDK_PATH/bin/wasm32-wasip3-clang foo.c -o foo.wasm --sysroot \
|
|
$WASI_SDK_PATH/share/wasi-sysroot/experimental-coop-threads -pthread
|
|
```
|
|
|
|
Note the `--sysroot` and `-pthread` flags to indicate that threading is being
|
|
used. When combined these flags should produce a binary which can then be run in
|
|
Wasmtime, for example, like so:
|
|
|
|
```console
|
|
wasmtime -W component-model-threading ./foo.wasm
|
|
```
|
|
|
|
The alternative sysroot has support for `pthread_*` symbols in wasi-libc which
|
|
additionally means support in C++ through the `<thread>` header, for example.
|
|
|
|
It is intended in the near-ish future (before the end of 2026) that this
|
|
experimental sysroot will become the default and wasi-libc/wasi-sdk will support
|
|
cooperative multithreading by default. This decision will require the WASI
|
|
subgroup to vote on including the cooperative multithreading feature in a future
|
|
WASI release, and then wasi-libc/wasi-sdk will update to this release.
|