From 7aebf56a21df79b18e3100b9a5974681e309c829 Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Tue, 1 Sep 2026 18:52:40 -0500 Subject: [PATCH] Document how to use coop threads (#654) This is all off-by-default right now but the distribution supports this through a separate sysroot. Document what's going on for others to discover. --- CoopThreading.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 CoopThreading.md diff --git a/CoopThreading.md b/CoopThreading.md new file mode 100644 index 0000000..9de7244 --- /dev/null +++ b/CoopThreading.md @@ -0,0 +1,46 @@ +# 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 `` 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.