emnapi 0.33.1 → 0.35.0

package/CMakeLists.txt

@@ -1,6 +1,6 @@
 cmake_minimum_required(VERSION 3.13)
 
-project(emnapi)
+project(emnapi LANGUAGES C ASM)
 
 option(EMNAPI_INSTALL_SRC "EMNAPI_INSTALL_SRC" OFF)
 option(EMNAPI_FIND_NODE_ADDON_API "EMNAPI_FIND_NODE_ADDON_API" OFF)
@@ -50,10 +50,13 @@ else()
 endif()
 
 set(EMNAPI_BASIC_TARGET_NAME "emnapi-basic")
+set(EMNAPI_BASIC_MT_TARGET_NAME "emnapi-basic-mt")
 set(EMNAPI_TARGET_NAME "emnapi")
 set(EMNAPI_MT_TARGET_NAME "emnapi-mt")
 set(DLMALLOC_TARGET_NAME "dlmalloc")
+set(DLMALLOC_MT_TARGET_NAME "dlmalloc-mt")
 set(EMMALLOC_TARGET_NAME "emmalloc")
+set(EMMALLOC_MT_TARGET_NAME "emmalloc-mt")
 
 if(EMNAPI_FIND_NODE_ADDON_API)
   execute_process(
@@ -82,11 +85,26 @@ if(IS_WASM32)
     "${CMAKE_CURRENT_SOURCE_DIR}/src/malloc/dlmalloc/dlmalloc.c"
   )
   target_compile_definitions(${DLMALLOC_TARGET_NAME} PRIVATE "PAGESIZE=65536")
+
+  add_library(${DLMALLOC_MT_TARGET_NAME} STATIC
+    ${MALLOC_PUBLIC_SOURCES}
+    "${CMAKE_CURRENT_SOURCE_DIR}/src/malloc/dlmalloc/dlmalloc.c"
+  )
+  target_compile_options(${DLMALLOC_MT_TARGET_NAME} PUBLIC "-matomics" "-mbulk-memory")
+  target_compile_definitions(${DLMALLOC_MT_TARGET_NAME} PRIVATE "PAGESIZE=65536" "USE_LOCKS=1")
+
   add_library(${EMMALLOC_TARGET_NAME} STATIC
     ${MALLOC_PUBLIC_SOURCES}
     "${CMAKE_CURRENT_SOURCE_DIR}/src/malloc/emmalloc/emmalloc.c"
   )
   target_compile_definitions(${EMMALLOC_TARGET_NAME} PRIVATE "PAGESIZE=65536")
+
+  add_library(${EMMALLOC_MT_TARGET_NAME} STATIC
+    ${MALLOC_PUBLIC_SOURCES}
+    "${CMAKE_CURRENT_SOURCE_DIR}/src/malloc/emmalloc/emmalloc.c"
+  )
+  target_compile_options(${EMMALLOC_MT_TARGET_NAME} PUBLIC "-matomics" "-mbulk-memory")
+  target_compile_definitions(${EMMALLOC_MT_TARGET_NAME} PRIVATE "PAGESIZE=65536" "__EMSCRIPTEN_SHARED_MEMORY__=1")
 endif()
 
 add_library(${EMNAPI_TARGET_NAME} STATIC ${EMNAPI_SRC} ${UV_SRC})
@@ -101,6 +119,22 @@ if(IS_EMSCRIPTEN)
   target_link_options(${EMNAPI_BASIC_TARGET_NAME} INTERFACE "--js-library=${EMNAPI_JS_LIB}")
 endif()
 
+if(IS_WASM32 OR (CMAKE_C_COMPILER_TARGET STREQUAL "wasm32-wasi") OR (CMAKE_C_COMPILER_TARGET STREQUAL "wasm32-wasi-threads"))
+  set(EMNAPI_BUILD_BASIC_MT ON)
+else()
+  set(EMNAPI_BUILD_BASIC_MT OFF)
+endif()
+
+if(EMNAPI_BUILD_BASIC_MT)
+  add_library(${EMNAPI_BASIC_MT_TARGET_NAME} STATIC
+    ${ENAPI_BASIC_SRC}
+    "${CMAKE_CURRENT_SOURCE_DIR}/src/thread/async_worker_create.c"
+    "${CMAKE_CURRENT_SOURCE_DIR}/src/thread/async_worker_init.S"
+  )
+  target_compile_options(${EMNAPI_BASIC_MT_TARGET_NAME} PUBLIC "-matomics" "-mbulk-memory")
+  target_include_directories(${EMNAPI_BASIC_MT_TARGET_NAME} PUBLIC ${EMNAPI_INCLUDE})
+endif()
+
 if(IS_EMSCRIPTEN OR (CMAKE_C_COMPILER_TARGET STREQUAL "wasm32-wasi-threads"))
   set(EMNAPI_BUILD_MT ON)
 else()
@@ -141,9 +175,14 @@ if(LIB_ARCH)
   if(EMNAPI_BUILD_MT)
     install(TARGETS ${EMNAPI_MT_TARGET_NAME} DESTINATION "lib/${LIB_ARCH}")
   endif()
+  if(EMNAPI_BUILD_BASIC_MT)
+    install(TARGETS ${EMNAPI_BASIC_MT_TARGET_NAME} DESTINATION "lib/${LIB_ARCH}")
+  endif()
   if(IS_WASM32)
     install(TARGETS ${DLMALLOC_TARGET_NAME} DESTINATION "lib/${LIB_ARCH}")
+    install(TARGETS ${DLMALLOC_MT_TARGET_NAME} DESTINATION "lib/${LIB_ARCH}")
     install(TARGETS ${EMMALLOC_TARGET_NAME} DESTINATION "lib/${LIB_ARCH}")
+    install(TARGETS ${EMMALLOC_MT_TARGET_NAME} DESTINATION "lib/${LIB_ARCH}")
   endif()
 endif()
 
@@ -178,4 +217,7 @@ if(EMNAPI_INSTALL_SRC)
   install(DIRECTORY
     ${CMAKE_CURRENT_SOURCE_DIR}/src/malloc
     DESTINATION "src/${PROJECT_NAME}")
+  install(DIRECTORY
+    ${CMAKE_CURRENT_SOURCE_DIR}/src/thread
+    DESTINATION "src/${PROJECT_NAME}")
 endif()

package/README.md

@@ -6,7 +6,7 @@
 
 [![Build](https://github.com/toyobayashi/emnapi/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/toyobayashi/emnapi/actions/workflows/main.yml)
 
-[Node-API](https://nodejs.org/docs/latest/api/n-api.html) implementation for [Emscripten](https://emscripten.org/index.html), [wasi-sdk](https://github.com/WebAssembly/wasi-sdk) and clang with wasm support. [napi-rs support is comming soon](https://github.com/napi-rs/napi-rs/tree/emnapi).
+[Node-API](https://nodejs.org/docs/latest/api/n-api.html) implementation for [Emscripten](https://emscripten.org/index.html), [wasi-sdk](https://github.com/WebAssembly/wasi-sdk) and clang with wasm support. napi-rs support is comming soon.
 
 This project aims to
 
@@ -25,16 +25,6 @@ See documentation for more details:
 
 [How to build Node-API official examples](https://github.com/toyobayashi/node-addon-examples)
 
-Emscripten is the first class support target. If your target is running addon on browser,
-we strongly recommend you to use Emscripten instead of wasi-sdk. Async works and threadsafe
-functions related APIs are only available on Emscripten or `wasm32-wasi-threads` target since
-they are relying on pthread. Though today we have [WASI browser polyfill](https://github.com/toyobayashi/wasm-util),
-`wasm32-wasi-threads` is in very early stage and WASI itself is not designed for browser.
-There are some limitations on browser about wasi-libc's pthread implementation, for example
-`pthread_mutex_lock` may call `__builtin_wasm_memory_atomic_wait32`(`memory.atomic.wait32`)
-which is disallowed in browser JS main thread. While Emscripten's pthread implementation
-has considered usage in browser.
-
 ## Prerequests
 
 You will need to install:
@@ -275,6 +265,9 @@ declare namespace Module {
      * napi_create_async_work and napi_create_threadsafe_function
      */
     nodeBinding?: typeof import('@emnapi/node-binding')
+
+    /** See Multithread part */
+    asyncWorkPoolSize?: number
   }
   export function emnapiInit (options: EmnapiInitOptions): any
 }
@@ -732,20 +725,60 @@ pub unsafe extern "C" fn napi_register_wasm_v1(env: napi_env, exports: napi_valu
 
 ### Multithread
 
-If you want to use async work or thread safe functions,
-there are additional C source file need to be compiled and linking.
-Recommend use CMake directly.
+Related API:
+
+- [napi_*_async_work](https://nodejs.org/dist/latest/docs/api/n-api.html#napi_create_async_work)
+- [napi_*_threadsafe_function](https://nodejs.org/dist/latest/docs/api/n-api.html#asynchronous-thread-safe-function-calls)
+
+They are available in emnapi, but you need to know more details before you start to use them.
+Now emnapi has 3 implementations of async work and 2 implementations of TSFN:
+
+- Async work
+    - A. Libuv threadpool and pthread based implementation in C
+    - B. Single thread mock in JavaScript
+    - C. Web worker based implementation in C (stack allocation) and JavaScript
+- TSFN
+    - D. Libuv and pthread based implementation in C
+    - E. Web worker based implementation in JavaScript
+
+|   | Library to Link        | `wasm32-emscripten` | `wasm32` | `wasm32-wasi` | `wasm32-wasi-threads` |
+|---|------------------------|---------------------|----------|---------------|-----------------------|
+| A | libemnapi-mt.a         | ✅                   | ❌        | ❌             | ✅                     |
+| B | libemnapi-basic(-mt).a | ✅                   | ✅        | ✅             | ✅                     |
+| C | libemnapi-basic-mt.a   | ❌                   | ✅        | ❌             | ✅                     |
+| D | libemnapi-mt.a         | ✅                   | ❌        | ❌             | ✅                     |
+| E | libemnapi-basic-mt.a   | ✅                   | ✅        | ✅             | ✅                     |
 
-**This is EXPERIMENTAL on non-emscripten.**
+There are some limitations on browser about wasi-libc's pthread implementation, for example
+`pthread_mutex_lock` may call `__builtin_wasm_memory_atomic_wait32`(`memory.atomic.wait32`)
+which is disallowed in browser JS main thread. While Emscripten's pthread implementation
+has considered usage in browser. If you need to run your addon with multithreaded features on browser,
+we recommend you use Emscripten A & D, or bare wasm32 C & E.
+
+#### About Prebuilt Libraries
+
+Prebuilt libraries can be found in the `lib` directory in `emnapi` npm package.
+
+| Library              | Description                                                                                                                                                                                                                                                   | `wasm32-emscripten` | `wasm32` | `wasm32-wasi` | `wasm32-wasi-threads`                   |
+|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------|----------|---------------|-----------------------------------------|
+| libemnapi.a          | no atomics feature.<br/><br/> no libuv port.<br/><br/> `napi_*_async_work` and `napi_*_threadsafe_function` always return `napi_generic_failure`.                                                                                                                         | ✅                   | ✅        | ✅             | waiting wasi-sdk release thread support |
+| libemnapi-mt.a       | atomics feature enabled.<br/><br/> `napi_*_async_work` and `napi_*_threadsafe_function` are based on pthread and libuv port.                                                                                                                                        | ✅                   | ❌        | ❌             | waiting wasi-sdk release thread support |
+| libemnapi-basic.a    | no atomics feature.<br/><br/> no libuv port.<br/><br/> `napi_*_async_work` and `napi_*_threadsafe_function` are imported from JavaScript land.                                                                                                                            | ✅                   | ✅        | ✅             | waiting wasi-sdk release thread support |
+| libemnapi-basic-mt.a | atomics feature enabled.<br/><br/> no libuv port.<br/><br/> `napi_*_async_work` and `napi_*_threadsafe_function` are imported from JavaScript land.<br/><br/> include `emnapi_async_worker_create` and `emnapi_async_worker_init` for WebWorker based async work implementation. | ❌                   | ✅        | ✅             | waiting wasi-sdk release thread support |
+| libdlmalloc.a        | no atomics feature, no thread safe garanteed.                                                                                                                                                                                                                 | ❌                   | ✅        | ❌             | ❌                                       |
+| libdlmalloc-mt.a     | atomics feature enabled, thread safe.                                                                                                                                                                                                                         | ❌                   | ✅        | ❌             | ❌                                       |
+| libemmalloc.a        | no atomics feature, no thread safe garanteed.                                                                                                                                                                                                                 | ❌                   | ✅        | ❌             | ❌                                       |
+| libemmalloc-mt.a     | atomics feature enabled, thread safe.                                                                                                                                                                                                                         | ❌                   | ✅        | ❌             | ❌                                       |
+
+#### Usage
 
 ```cmake
 add_subdirectory("${CMAKE_CURRENT_SOURCE_DIR}/node_modules/emnapi")
 
 add_executable(hello hello.c)
 
-target_link_libraries(hello emnapi-mt)
-
 if(CMAKE_SYSTEM_NAME STREQUAL "Emscripten")
+  target_link_libraries(hello emnapi-mt)
   target_compile_options(hello PRIVATE "-pthread")
   target_link_options(hello PRIVATE
     "-sALLOW_MEMORY_GROWTH=1"
@@ -758,6 +791,7 @@ if(CMAKE_SYSTEM_NAME STREQUAL "Emscripten")
   )
 elseif(CMAKE_C_COMPILER_TARGET STREQUAL "wasm32-wasi-threads")
   # Experimental
+  target_link_libraries(hello emnapi-mt)
   set_target_properties(hello PROPERTIES SUFFIX ".wasm")
   target_compile_options(hello PRIVATE "-fno-exceptions" "-pthread")
   target_link_options(hello PRIVATE
@@ -771,6 +805,19 @@ elseif(CMAKE_C_COMPILER_TARGET STREQUAL "wasm32-wasi-threads")
     "-Wl,--import-undefined"
     "-Wl,--export-table"
   )
+elseif((CMAKE_C_COMPILER_TARGET STREQUAL "wasm32") OR (CMAKE_C_COMPILER_TARGET STREQUAL "wasm32-unknown-unknown"))
+  target_link_libraries(hello emnapi-basic-mt)
+  set_target_properties(hello PROPERTIES SUFFIX ".wasm")
+  target_compile_options(hello PRIVATE "-fno-exceptions" "-matomics" "-mbulk-memory")
+  target_link_options(hello PRIVATE
+    "-nostdlib"
+    "-Wl,--no-entry"
+    "-Wl,--export=napi_register_wasm_v1"
+    "-Wl,--export=emnapi_async_worker_create"
+    "-Wl,--export=emnapi_async_worker_init"
+    "-Wl,--import-memory,--shared-memory,--max-memory=2147483648,--import-undefined"
+    "-Wl,--export-dynamic,--export=malloc,--export=free,--export-table"
+  )
 endif()
 ```
 
@@ -784,6 +831,11 @@ cmake -DCMAKE_TOOLCHAIN_FILE=$WASI_SDK_PATH/share/cmake/wasi-sdk-pthread.cmake \
       -DCMAKE_BUILD_TYPE=Release \
       -G Ninja -H. -Bbuild
 
+cmake -DCMAKE_TOOLCHAIN_FILE=node_modules/emnapi/cmake/wasm32.cmake \
+      -DWASI_SDK_PREFIX=$WASI_SDK_PATH \
+      -DCMAKE_BUILD_TYPE=Release \
+      -G Ninja -H. -Bbuild
+
 cmake --build build
 ```
 
@@ -793,6 +845,15 @@ And additional work is required during instantiating wasm compiled with non-emsc
 // emnapi main thread (could be in a Worker)
 instantiateNapiModule(input, {
   context: getDefaultContext(),
+  /**
+   * emscripten
+   *   0: no effect
+   *   > 0: the same effect to UV_THREADPOOL_SIZE
+   * non-emscripten
+   *   0: single thread mock
+   *   > 0 schedule async work in web worker
+   */
+  asyncWorkPoolSize: 4, // 0: single thread mock, > 0: schedule async work in web worker
   wasi: new WASI(/* ... */),
   // reuseWorker: true,
   onCreateWorker () {
@@ -890,17 +951,30 @@ instantiateNapiModule(input, {
 
 ### `-DEMNAPI_WORKER_POOL_SIZE=4`
 
-This is [`UV_THREADPOOL_SIZE`](http://docs.libuv.org/en/v1.x/threadpool.html?highlight=UV_THREADPOOL_SIZE) equivalent at compile time, if not predefined, emnapi will read `UV_THREADPOOL_SIZE` from Emscripten [environment variable](https://emscripten.org/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.html#interacting-with-code-environment-variables) at runtime, you can set `UV_THREADPOOL_SIZE` like this:
+This is [`UV_THREADPOOL_SIZE`](http://docs.libuv.org/en/v1.x/threadpool.html?highlight=UV_THREADPOOL_SIZE) equivalent at compile time, if not predefined, emnapi will read `asyncWorkPoolSize` option or `UV_THREADPOOL_SIZE` from Emscripten [environment variable](https://emscripten.org/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.html#interacting-with-code-environment-variables) at runtime:
 
 ```js
+Module.init({
+  // ...
+  asyncWorkPoolSize: 2
+})
+
+// if asyncWorkPoolSize is not specified
 Module.preRun = Module.preRun || [];
 Module.preRun.push(function () {
   if (typeof ENV !== 'undefined') {
     ENV.UV_THREADPOOL_SIZE = '2';
   }
 });
+```
 
+```js
 // wasi
+instantiateNapiModule({
+  // ...
+  asyncWorkPoolSize: 2
+})
+// if asyncWorkPoolSize is not specified
 new WASI({
   env: {
     UV_THREADPOOL_SIZE: '2'
@@ -908,7 +982,7 @@ new WASI({
 })
 ```
 
-It represent max of `EMNAPI_WORKER_POOL_SIZE` async work (`napi_queue_async_work`) can be executed in parallel. Default is not defined, read `UV_THREADPOOL_SIZE` at runtime.
+It represent max of `EMNAPI_WORKER_POOL_SIZE` async work (`napi_queue_async_work`) can be executed in parallel. Default is not defined.
 
 You can set both `PTHREAD_POOL_SIZE` and `EMNAPI_WORKER_POOL_SIZE` to `number of CPU cores` in general.
 If you use another library function which may create `N` child threads in async work,