wasi-sdk/CoopThreading.md

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 and this feature corresponds to the 🧵 emoji. The Wasmtime runtime supports this proposal behind the -Wcomponent-model-threading flag.

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:

$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:

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.