Quick Example

#include<emscripten/wasm_worker.h>#include<stdio.h>voidrun_in_worker(){printf("Hello from Wasm Worker!\n");}intmain(){emscripten_wasm_worker_tworker=emscripten_malloc_wasm_worker(/*stackSize: */1024);emscripten_wasm_worker_post_function_v(worker,run_in_worker);}

Build the code by passing the Emscripten flag-sWASM_WORKERS at both compileand link steps. The example code creates a new Worker on the main browser thread,which shares the same WebAssembly.Module and WebAssembly.Memory object. Then apostMessage() is passed to the Worker to ask it to execute the functionrun_in_worker() to print a string.

To explicitly control the memory allocation placement when creating a worker,use theemscripten_create_wasm_worker() function. This function takes aregion of memory that must be large enough to hold both the stack and the TLSdata for the worker. You can use__builtin_wasm_tls_size() to find out atruntime how much space is required for the program’s TLS data.

Introduction

In WebAssembly programs, the Memory object that contains the application state can beshared across multiple Workers. This enables direct, high performance (and if explicitcare is not taken, racy!) access to synchronously share data state between multipleWorkers (shared state multithreading).

Emscripten supports two multithreading APIs to leverage this web feature:

• POSIX Threads (Pthreads) API, and

• Wasm Workers API.

The Pthreads API has a long history with native C programming and the POSIX standard,while Wasm Workers API is unique to Emscripten compiler only.

These two APIs provide largely the same feature set, but have important differences,which this documentation seeks to explain to help decide which API one should target.

Pthreads vs Wasm Workers: Which One to Use?

The intended audience and use cases of these two multithreading APIs are slightlydifferent.

The focus on Pthreads API is on portability and cross-platform compatibility. This APIis best used in scenarios where portability is most important, e.g. when a codebase iscross-compiled to multiple platforms, like building both a native Linux x64 executable and anEmscripten WebAssembly based web site.

Pthreads API in Emscripten seeks to carefully emulate compatibility and the features thatthe native Pthreads platforms already provide. This helps porting large C/C++ codebasesover to WebAssembly.

Wasm Workers API on the other hand seeks to provide a “direct mapping” to the webmultithreading primitives as they exist on the web, and call it a day. If an applicationis only developed to target WebAssembly, and portability is not a concern, then using WasmWorkers can provide great benefits in the form of simpler compiled output, less complexity,smaller code size and possibly better performance.

However this benefit might not be an obvious win. The Pthreads API was designed to be usefulfrom the synchronous C/C++ language, whereas Web Workers are designed to be useful fromasynchronous JavaScript. WebAssembly C/C++ programs can find themselves somewhere inthe middle.

Pthreads and Wasm Workers share several similarities:

• Both can use emscripten_atomic_* Atomics API,

• Both can use GCC __sync_* Atomics API,

• Both can use C11 and C++11 Atomics APIs,

• Both types of threads have a local stack.

• Both types of threads have thread-local storage (TLS) support viathread_local (C++11),_Thread_local (C11) and__thread (GNU11) keywords.

• Both types of threads support TLS via explicitly linked in Wasm globals (seetest/wasm_worker/wasm_worker_tls_wasm_assembly.c/.S for example code)

• Both types of threads have a concept of a thread ID (pthread_self() for pthreads,emscripten_wasm_worker_self_id() for Wasm Workers)

• Both types of threads can perform an event-based and an infinite loop programming model.

• Both can useEM_ASM andEM_JS API to execute JS code on the calling thread.

• Both can call out to JS library functions (linked in with--js-library directive) toexecute JS code on the calling thread.

• Neither pthreads nor Wasm Workers can be used in conjunction with-sSINGLE_FILE linker flag.

However, the differences are more notable.

pthread_exit(status)

pthread_kill(code)

emscripten_terminate_wasm_worker(worker)

emscripten_create_wasm_worker_*_tls()

emscripten_malloc_wasm_worker()

emscripten_create_wasm_worker_*_tls()

emscripten_malloc_wasm_worker()

pthread_self()

emscripten_wasm_worker_self_id()

emscripten_futex_wait

emscripten_futex_wake

emscripten_atomic_wait_u32

emscripten_atomic_wait_u64

emscripten_atomic_notify

emscripten_atomic_wait_async()

emscripten_*_async_acquire()

pthread_mutex_*

emscripten_lock_*

pthread_mutex_*

emscripten_semaphore_*

pthread_cond_*

emscripten_condvar_*

pthread_rwlock_*

pthread_spin_*

emscripten_lock_busyspin*

Supported with -sOFFSCREEN_FRAMEBUFFER

Not supported.

Wasm Workers stack size considerations

When instantiating a Wasm Worker, one has to create a memory array for the LLVMdata stack for the created Worker. This data stack will generally consist onlyof local variables that have been “spilled” by LLVM into memory, e.g. to containlarge arrays, structs, or other variables that are referenced by a memoryaddress. This stack will not contain control flow information.

Since WebAssembly does not support virtual memory, the size of the LLVM datastack that is defined both for Wasm Workers but also the main thread will not bepossible to grow at runtime. So if the Worker (or the main thread) runs out ofstack space, the program behavior will be undefined. Use the Emscripten linkerflag -sSTACK_OVERFLOW_CHECK=2 to emit runtime stack overflow checks into theprogram code to detect these situations during development.

Note that to avoid the need to perform two separate allocations, the TLS memoryfor the Wasm Worker will be located at the bottom end (low memory address) ofthe Wasm Worker stack space.

Wasm Workers vs the earlier Emscripten Worker API

Emscripten provides a second Worker API as part of the emscripten.h header. This Worker API predates the advent of SharedArrayBuffer, and is quite distinct from Wasm Workers API, just the naming of these two APIs is similar due to historical reasons.

Both APIs allow one to spawn Web Workers from the main thread, though the semantics are different.

With the Worker API, the user will be able to spawn a Web Worker from a custom URL. This URL can point to a completely separate JS file that was not compiled with Emscripten, to load up Workers from arbitrary URLs. With Wasm Workers, a custom URL is not specified: Wasm Workers will always spawn a Web Worker that computes in the same WebAssembly+JavaScript context as the main program.

The Worker API does not integrate with SharedArrayBuffer, so interaction with the loaded Worker will always be asynchronous. Wasm Workers howerer is built on top of SharedArrayBuffer, and each Wasm Worker shares and computes in the same WebAssembly Memory address space of the main thread.

Both the Worker API and Wasm Workers API provide the user with ability to postMessage() function calls to the Worker. In Worker API, this message posting is restricted to need to originate/initiate from the main thread towards the Worker (using the APIemscripten_call_worker() andemscripten_worker_respond() in<emscripten.h>). With Wasm Workers however one can also postMessage() function calls to their parent (owning) thread.

If posting function calls with the Emscripten Worker API, it is required that the target Worker URL points to an Emscripten compiled program (so it has theModule structure to locate function names). Only functions that have been exported to theModule object are callable. With Wasm Workers, any C/C++ function may be posted, and does not need to be exported.

Use the Emscripten Worker API when:

• you want to easily spawn a Worker from a JS file that was not built using Emscripten

• you want to spawn as Worker a single separate compiled program than the main thread program represents, and the main thread and Worker programs do not share common code

• you do not want to require the use of SharedArrayBuffer, or setting up COOP+COEP headers

• you only need to communicate with the Worker asynchronously using postMessage() function calls

Use the Wasm Workers API when:

• you want to create one or more new threads that synchronously compute in the same Wasm Module context

• you want to spawn multiple Workers from the same codebase and save memory by sharing the WebAssembly Module (object code) and Memory (address space) across the Workers

• you want to synchronously coordinate communication between threads by using atomic primitives and locks

• your web server has been configured with the needed COOP+COEP headers to enable SharedArrayBuffer capabilities on the site

Limitations

The following build options are not supported at the moment with Wasm Workers:

• -sSINGLE_FILE

• Dynamic linking (-sLINKABLE, -sMAIN_MODULE, -sSIDE_MODULE)

• -sPROXY_TO_PTHREAD

Example Code

See the directorytest/wasm_worker/ for code examples on different Wasm Workers API functionality.