add spawn thread API and sample (bytecodealliance#333)

core/iwasm/common/wasm_runtime_common.c

@@ -234,6 +234,10 @@ wasm_runtime_full_init(RuntimeInitArgs *init_args)
         return false;
     }
 
+#if WASM_ENABLE_THREAD_MGR != 0
+    wasm_cluster_set_max_thread_num(init_args->max_thread_num);
+#endif
+
     return true;
 }
 
@@ -2850,3 +2854,77 @@ wasm_runtime_call_indirect(WASMExecEnv *exec_env,
 #endif
     return false;
 }
+
+#if WASM_ENABLE_THREAD_MGR != 0
+typedef struct WASMThreadArg {
+    WASMExecEnv *new_exec_env;
+    wasm_thread_callback_t callback;
+    void *arg;
+} WASMThreadArg;
+
+WASMExecEnv *
+wasm_runtime_spawn_exec_env(WASMExecEnv *exec_env)
+{
+    return wasm_cluster_spawn_exec_env(exec_env);
+}
+
+void
+wasm_runtime_destroy_spawned_exec_env(WASMExecEnv *exec_env)
+{
+    wasm_cluster_destroy_spawned_exec_env(exec_env);
+}
+
+static void*
+wasm_runtime_thread_routine(void *arg)
+{
+    WASMThreadArg *thread_arg = (WASMThreadArg *)arg;
+    void *ret;
+
+    bh_assert(thread_arg->new_exec_env);
+    ret = thread_arg->callback(thread_arg->new_exec_env, thread_arg->arg);
+
+    wasm_runtime_destroy_spawned_exec_env(thread_arg->new_exec_env);
+    wasm_runtime_free(thread_arg);
+
+    os_thread_exit(ret);
+    return ret;
+}
+
+int32
+wasm_runtime_spawn_thread(WASMExecEnv *exec_env, wasm_thread_t *tid,
+                          wasm_thread_callback_t callback, void *arg)
+{
+    WASMExecEnv *new_exec_env = wasm_runtime_spawn_exec_env(exec_env);
+    WASMThreadArg *thread_arg;
+    int32 ret;
+
+    if (!new_exec_env)
+        return -1;
+
+    if (!(thread_arg = wasm_runtime_malloc(sizeof(WASMThreadArg)))) {
+        wasm_runtime_destroy_spawned_exec_env(new_exec_env);
+        return -1;
+    }
+
+    thread_arg->new_exec_env = new_exec_env;
+    thread_arg->callback = callback;
+    thread_arg->arg = arg;
+
+    ret = os_thread_create((korp_tid *)tid, wasm_runtime_thread_routine,
+                           thread_arg, APP_THREAD_STACK_SIZE_DEFAULT);
+
+    if (ret != 0) {
+        wasm_runtime_destroy_spawned_exec_env(new_exec_env);
+        wasm_runtime_free(thread_arg);
+    }
+
+    return ret;
+}
+
+int32
+wasm_runtime_join_thread(wasm_thread_t tid, void **retval)
+{
+    return os_thread_join((korp_tid)tid, retval);
+}
+
+#endif

core/iwasm/include/wasm_export.h

@@ -114,6 +114,10 @@ typedef struct RuntimeInitArgs {
     const char *native_module_name;
     NativeSymbol *native_symbols;
     uint32_t n_native_symbols;
+
+    /* maximum thread number, only used when
+        WASM_ENABLE_THREAD_MGR is defined */
+    uint32_t max_thread_num;
 } RuntimeInitArgs;
 
 /**
@@ -684,13 +688,62 @@ void *
 wasm_runtime_get_user_data(wasm_exec_env_t exec_env);
 
 #if WASM_ENABLE_THREAD_MGR != 0
+/* wasm thread callback function type */
+typedef void* (*wasm_thread_callback_t)(wasm_exec_env_t, void *);
+/* wasm thread type */
+typedef uintptr_t wasm_thread_t;
+
 /**
  * Set the max thread num per cluster.
  *
  * @param num maximum thread num
  */
 void
 wasm_runtime_set_max_thread_num(uint32_t num);
+
+/**
+ * spawn a new exec_env, the spawned exec_env
+ *   can be used in other threads
+ *
+ * @param num the original exec_env
+ *
+ * @return the spawned exec_env if success, NULL otherwise
+ */
+wasm_exec_env_t
+wasm_runtime_spawn_exec_env(wasm_exec_env_t exec_env);
+
+/**
+ * Destroy the spawned exec_env
+ *
+ * @param exec_env the spawned exec_env
+ */
+void
+wasm_runtime_destroy_spawned_exec_env(wasm_exec_env_t exec_env);
+
+/**
+ * spawn a thread from the given exec_env
+ *
+ * @param exec_env the original exec_env
+ * @param tid thread id to be returned to the caller
+ * @param callback the callback function provided by the user
+ * @param arg the arguments passed to the callback
+ *
+ * @return 0 if success, -1 otherwise
+ */
+int32_t
+wasm_runtime_spawn_thread(wasm_exec_env_t exec_env, wasm_thread_t *tid,
+                          wasm_thread_callback_t callback, void *arg);
+
+/**
+ * waits a spawned thread to terminate
+ *
+ * @param tid thread id
+ * @param retval if not NULL, output the return value of the thread
+ *
+ * @return 0 if success, error number otherwise
+ */
+int32_t
+wasm_runtime_join_thread(wasm_thread_t tid, void **retval);
 #endif
 
 #ifdef __cplusplus

core/iwasm/libraries/thread-mgr/thread_manager.c

@@ -27,7 +27,8 @@ static uint32 cluster_max_thread_num = CLUSTER_MAX_THREAD_NUM;
 void
 wasm_cluster_set_max_thread_num(uint32 num)
 {
-    cluster_max_thread_num = num;
+    if (num > 0)
+        cluster_max_thread_num = num;
 }
 
 bool
@@ -278,6 +279,70 @@ wasm_cluster_del_exec_env(WASMCluster *cluster, WASMExecEnv *exec_env)
     return ret;
 }
 
+WASMExecEnv *
+wasm_cluster_spawn_exec_env(WASMExecEnv *exec_env)
+{
+    WASMCluster *cluster = wasm_exec_env_get_cluster(exec_env);
+    wasm_module_t module = wasm_exec_env_get_module(exec_env);
+    wasm_module_inst_t new_module_inst;
+    WASMExecEnv *new_exec_env;
+    uint32 aux_stack_start, aux_stack_size;
+
+    if (!(new_module_inst =
+        wasm_runtime_instantiate_internal(module, true, 8192,
+                                          0, NULL, 0))) {
+        return NULL;
+    }
+
+    new_exec_env = wasm_exec_env_create_internal(
+                        new_module_inst, exec_env->wasm_stack_size);
+    if (!new_exec_env)
+        goto fail1;
+
+    if (!allocate_aux_stack(cluster, &aux_stack_start, &aux_stack_size)) {
+        LOG_ERROR("thread manager error: "
+                  "failed to allocate aux stack space for new thread");
+        goto fail2;
+    }
+
+    /* Set aux stack for current thread */
+    if (!wasm_exec_env_set_aux_stack(new_exec_env, aux_stack_start,
+                                     aux_stack_size)) {
+        goto fail3;
+    }
+
+    if (!wasm_cluster_add_exec_env(cluster, new_exec_env))
+        goto fail3;
+
+    return new_exec_env;
+
+fail3:
+    /* free the allocated aux stack space */
+    free_aux_stack(cluster, aux_stack_start);
+fail2:
+    wasm_exec_env_destroy(new_exec_env);
+fail1:
+    wasm_runtime_deinstantiate_internal(new_module_inst, true);
+
+    return NULL;
+}
+
+void
+wasm_cluster_destroy_spawned_exec_env(WASMExecEnv *exec_env)
+{
+    WASMCluster *cluster = wasm_exec_env_get_cluster(exec_env);
+    wasm_module_inst_t module_inst = wasm_runtime_get_module_inst(exec_env);
+    bh_assert(cluster != NULL);
+
+    /* Free aux stack space */
+    free_aux_stack(cluster,
+                   exec_env->aux_stack_boundary + cluster->stack_size);
+    wasm_cluster_del_exec_env(cluster, exec_env);
+    wasm_exec_env_destroy_internal(exec_env);
+
+    wasm_runtime_deinstantiate_internal(module_inst, true);
+}
+
 /* start routine of thread manager */
 static void*
 thread_manager_start_routine(void *arg)

core/iwasm/libraries/thread-mgr/thread_manager.h

@@ -109,6 +109,12 @@ wasm_cluster_del_exec_env(WASMCluster *cluster, WASMExecEnv *exec_env);
 void
 wasm_cluster_spread_exception(WASMExecEnv *exec_env);
 
+WASMExecEnv *
+wasm_cluster_spawn_exec_env(WASMExecEnv *exec_env);
+
+void
+wasm_cluster_destroy_spawned_exec_env(WASMExecEnv *exec_env);
+
 #ifdef __cplusplus
 }
 #endif

doc/embed_wamr.md

@@ -22,7 +22,7 @@ Embedding WAMR guideline
   // read WASM file into a memory buffer
   buffer = read_wasm_binary_to_buffer(…, &size);
 
-  // Add it below if runtime needs to export native functions to WASM APP 
+  // Add it below if runtime needs to export native functions to WASM APP
   // wasm_runtime_register_natives(...)
 
   // parse the WASM file from buffer and create a WASM module
@@ -81,7 +81,7 @@ After a module is instantiated, the runtime native can lookup WASM functions by
 ```c
   unit32 argv[2];
 
-  // lookup a WASM function by its name. 
+  // lookup a WASM function by its name.
   // The function signature can NULL here
   func = wasm_runtime_lookup_function(module_inst, "fib", NULL);
 
@@ -128,7 +128,7 @@ The parameters are transferred in an array of 32 bits elements. For parameters t
   //            arg3 and arg4 each takes 2 elements
   //
   wasm_runtime_call_wasm(exec_env, func, 6, argv);
-  
+
   // if the return value is type of 8 bytes, it takes
   // the first two array elements
   memcpy(&ret, &argv[0], sizeof(ret));
@@ -193,7 +193,7 @@ if(buffer_for_wasm != 0)
     argv[0] = buffer_for_wasm;  	// pass the buffer address for WASM space.
     argv[1] = 100;					// the size of buffer
     wasm_runtime_call_wasm(exec_env, func, 2, argv);
-    
+
     // it is runtime responsibility to release the memory,
     // unless the WASM app will free the passed pointer in its code
     wasm_runtime_module_free(module_inst, buffer_for_wasm);
@@ -209,6 +209,73 @@ We can't pass structure data or class objects through the pointer since the memo
 
 
 
+## Execute wasm functions in multiple threads
+
+The `exec_env` is not thread safety, it will cause unexpected behavior if the same `exec_env` is used in multiple threads. However, we've provided two ways to execute wasm functions concurrently:
+
+- You can use `pthread` APIs in your wasm application, see [pthread library](./pthread_library.md) for more details.
+
+- The `spawn exec_env` and `spawn thread` APIs are available, you can use these APIs to manage the threads in native:
+
+  *spawn exec_env:*
+
+  `spawn exec_env` API spawn a `new_exec_env` base on the original `exec_env`, use can use it in other threads:
+
+  ```C
+  new_exec_env = wasm_runtime_spawn_exec_env(exec_env);
+
+    /* Then you can use new_exec_env in your new thread */
+    module_inst = wasm_runtime_get_module_inst(new_exec_env);
+    func_inst = wasm_runtime_lookup_function(module_inst, ...);
+    wasm_runtime_call_wasm(new_exec_env, func_inst, ...);
+
+  /* you need to use this API to manually destroy the spawned exec_env */
+  wasm_runtime_destroy_spawned_exec_env(new_exec_env);
+  ```
+
+  *spawn thread:*
+
+  You can also use `spawn thread` API to avoid manually manage the spawned exec_env:
+
+  ```C
+  wasm_thread_t wasm_tid;
+  void *wamr_thread_cb(wasm_exec_env_t exec_env, void *arg)
+  {
+    module_inst = wasm_runtime_get_module_inst(exec_env);
+    func_inst = wasm_runtime_lookup_function(module_inst, ...);
+    wasm_runtime_call_wasm(exec_env, func_inst, ...);
+  }
+  wasm_runtime_spawn_thread(exec_env, &wasm_tid, wamr_thread_cb, NULL);
+  /* Use wasm_runtime_join_thread to join the spawned thread */
+  wasm_runtime_join_thread(wasm_tid, NULL);
+  ```
+
+**Note1: You can manage the maximum number of threads can be created:**
+
+```C
+init_args.max_thread_num = THREAD_NUM;
+/* If this init argument is not set, the default maximum thread number is 4 */
+```
+
+  **Note2: The wasm application should be built with `--shared-memory` and `-pthread` enabled:**
+
+```bash
+  /opt/wasi-sdk/bin/clang -o test.wasm test.c -nostdlib -pthread    \
+    -Wl,--shared-memory,--max-memory=131072                         \
+    -Wl,--no-entry,--export=__heap_base,--export=__data_end         \
+    -Wl,--export=__wasm_call_ctors,--export=${your_func_name}
+```
+
+  **Note3: The pthread library feature should be enabled while building the runtime:**
+
+  ```bash
+  cmake .. -DWAMR_BUILD_LIB_PTHREAD=1
+  ```
+
+[Here](../samples/spawn-thread) is a sample to show how to use these APIs.
+
+
+
 ## The deinitialization procedure
 
 ```

doc/pthread_library.md

@@ -116,7 +116,7 @@ The default value of N is 4, which means you can create 4 threads at most. This
 ``` bash
 ./iwasm --max-threads=n test.wasm
 ```
-If you are going to develop your own runtime product, you can use the API `wasm_runtime_set_max_thread_num` to set the value, or you can change the macro `CLUSTER_MAX_THREAD_NUM` in [config.h](../core/config.h),
+If you are going to develop your own runtime product, you can use the API `wasm_runtime_set_max_thread_num` or init arg `init_args.max_thread_num` to set the value, or you can change the macro `CLUSTER_MAX_THREAD_NUM` in [config.h](../core/config.h).
 
 > Note: the total size of aux stack reserved by compiler can be set with `-z stack-size` option during compilation. If you need to create more threads, please set a larger value, otherwise it is easy to cause aux stack overflow.
 

samples/multi-thread/CMakeLists.txt

@@ -14,7 +14,7 @@ set(CMAKE_SHARED_LIBRARY_LINK_CXX_FLAGS "")
 # WAMR features switch
 set(WAMR_BUILD_TARGET "X86_64")
 set(WAMR_BUILD_INTERP 1)
-set(WAMR_BUILD_AOT 0)
+set(WAMR_BUILD_AOT 1)
 set(WAMR_BUILD_JIT 0)
 set(WAMR_BUILD_LIBC_BUILTIN 1)
 set(WAMR_BUILD_FAST_INTERP 1)