wasm-micro-runtime/doc/pthread_impls.md
YAMAMOTO Takashi e7b988e6ab
Document the summary of two pthread implementations (#2104)
And add `wasi-threads` to the key feature list in README.md.
2023-04-04 17:22:54 +08:00

2.2 KiB

Pthread implementations

WAMR has two pthread implementations available as of writing this.

These implementations are not ABI-compatible. You at least need to rebuild your wasm modules when migrating from one pthread implementation to another.

For new users, we recommend to use (or at least experiment) the new wasi-threads based implementation. In future, we might remove the old implementation.

WAMR lib-pthread (old)

  • The pthread API is directly implemented as host functions in WAMR. (WAMR_BUILD_LIB_PTHREAD)

  • Only minimum API is implemented as of writing this. (eg. no pthread barriers)

  • WAMR-specific ABI

  • Known limitations

wasi-threads (new)

  • The pthread API is implemented in wasi-libc, based on wasi-threads and WASM threads proposals.

  • It requires a recent-enough version of wasi-libc. The experimental support is included in wasi-sdk 20.0 or later. To build your application, cmake users can use the cmake toolchain file provided by wasi-sdk.

  • wasi-threads is implemented as a host function in WAMR. (WAMR_BUILD_LIB_WASI_THREADS)

  • The ABI is specified in wasi-threads proposal. You can run the same wasm modules on other runtimes which implement the proposal. (wasmtime, toywasm, ...)

  • Basically more feature-rich and complete than WAMR lib-pthread.

    EXCEPTION: pthread_exit is not available as of writing this. If pthread_exit is important for your use cases, please speak up in the GitHub issue.

    EXCEPTION: For threads created by pthread_create, the AUX stack (aka C shadow stack) overflow detection mechanism is disabled as of writing this. If it's important for your use cases, please speak up in the GitHub issue.

References