wasm_export.h

Go to the documentation of this file.

/*
 * Copyright (C) 2019 Intel Corporation.  All rights reserved.
 * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 */
 
#ifndef _WASM_EXPORT_H
#define _WASM_EXPORT_H
 
#include <stdint.h>
#include <stdbool.h>
#include "lib_export.h"
 
#ifndef WASM_RUNTIME_API_EXTERN
#if defined(_MSC_BUILD)
#if defined(COMPILING_WASM_RUNTIME_API)
#define WASM_RUNTIME_API_EXTERN __declspec(dllexport)
#else
#define WASM_RUNTIME_API_EXTERN __declspec(dllimport)
#endif
#else
#define WASM_RUNTIME_API_EXTERN
#endif
#endif
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* clang-format off */
 
#define get_module_inst(exec_env) \
    wasm_runtime_get_module_inst(exec_env)
 
#define validate_app_addr(offset, size) \
    wasm_runtime_validate_app_addr(module_inst, offset, size)
 
#define validate_app_str_addr(offset) \
    wasm_runtime_validate_app_str_addr(module_inst, offset)
 
#define addr_app_to_native(offset) \
    wasm_runtime_addr_app_to_native(module_inst, offset)
 
#define addr_native_to_app(ptr) \
    wasm_runtime_addr_native_to_app(module_inst, ptr)
 
#define module_malloc(size, p_native_addr) \
    wasm_runtime_module_malloc(module_inst, size, p_native_addr)
 
#define module_free(offset) \
    wasm_runtime_module_free(module_inst, offset)
 
#define native_raw_return_type(type, args) type *raw_ret = (type *)(args)
 
#define native_raw_get_arg(type, name, args) type name = *((type *)(args++))
 
#define native_raw_set_return(val) *raw_ret = (val)
 
#ifndef WASM_MODULE_T_DEFINED
#define WASM_MODULE_T_DEFINED
/* Uninstantiated WASM module loaded from WASM binary file
   or AoT binary file*/
struct WASMModuleCommon;
typedef struct WASMModuleCommon *wasm_module_t;
#endif
 
/* Instantiated WASM module */
struct WASMModuleInstanceCommon;
typedef struct WASMModuleInstanceCommon *wasm_module_inst_t;
 
/* Function instance */
typedef void WASMFunctionInstanceCommon;
typedef WASMFunctionInstanceCommon *wasm_function_inst_t;
 
/* WASM section */
typedef struct wasm_section_t {
    struct wasm_section_t *next;
    /* section type */
    int section_type;
    /* section body, not include type and size */
    uint8_t *section_body;
    /* section body size */
    uint32_t section_body_size;
} wasm_section_t, aot_section_t, *wasm_section_list_t, *aot_section_list_t;
 
/* Execution environment, e.g. stack info */
struct WASMExecEnv;
typedef struct WASMExecEnv *wasm_exec_env_t;
 
/* Package Type */
typedef enum {
    Wasm_Module_Bytecode = 0,
    Wasm_Module_AoT,
    Package_Type_Unknown = 0xFFFF
} package_type_t;
 
#ifndef MEM_ALLOC_OPTION_DEFINED
#define MEM_ALLOC_OPTION_DEFINED
/* Memory allocator type */
typedef enum {
    /* pool mode, allocate memory from user defined heap buffer */
    Alloc_With_Pool = 0,
    /* user allocator mode, allocate memory from user defined
       malloc function */
    Alloc_With_Allocator,
    /* system allocator mode, allocate memory from system allocator,
       or, platform's os_malloc function */
    Alloc_With_System_Allocator,
} mem_alloc_type_t;
 
/* Memory allocator option */
typedef union MemAllocOption {
    struct {
        void *heap_buf;
        uint32_t heap_size;
    } pool;
    struct {
        void *malloc_func;
        void *realloc_func;
        void *free_func;
        /* allocator user data, only used when
           WASM_MEM_ALLOC_WITH_USER_DATA is defined */
        void *user_data;
    } allocator;
} MemAllocOption;
#endif
 
/* Memory pool info  */
typedef struct mem_alloc_info_t {
    uint32_t total_size;
    uint32_t total_free_size;
    uint32_t highmark_size;
} mem_alloc_info_t;
 
/* Running mode of runtime and module instance*/
typedef enum RunningMode {
    Mode_Interp = 1,
    Mode_Fast_JIT,
    Mode_LLVM_JIT,
    Mode_Multi_Tier_JIT,
} RunningMode;
 
/* WASM runtime initialize arguments */
typedef struct RuntimeInitArgs {
    mem_alloc_type_t mem_alloc_type;
    MemAllocOption mem_alloc_option;
 
    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;
 
    /* Debug settings, only used when
       WASM_ENABLE_DEBUG_INTERP != 0 */
    char ip_addr[128];
    int unused; /* was platform_port */
    int instance_port;
 
    /* Fast JIT code cache size */
    uint32_t fast_jit_code_cache_size;
 
    /* Default GC heap size */
    uint32_t gc_heap_size;
 
    /* Default running mode of the runtime */
    RunningMode running_mode;
 
    /* LLVM JIT opt and size level */
    uint32_t llvm_jit_opt_level;
    uint32_t llvm_jit_size_level;
    /* Segue optimization flags for LLVM JIT */
    uint32_t segue_flags;
    bool enable_linux_perf;
} RuntimeInitArgs;
 
#ifndef INSTANTIATION_ARGS_OPTION_DEFINED
#define INSTANTIATION_ARGS_OPTION_DEFINED
/* WASM module instantiation arguments */
typedef struct InstantiationArgs {
    uint32_t default_stack_size;
    uint32_t host_managed_heap_size;
    uint32_t max_memory_pages;
} InstantiationArgs;
#endif /* INSTANTIATION_ARGS_OPTION_DEFINED */
 
#ifndef WASM_VALKIND_T_DEFINED
#define WASM_VALKIND_T_DEFINED
typedef uint8_t wasm_valkind_t;
enum wasm_valkind_enum {
    WASM_I32,
    WASM_I64,
    WASM_F32,
    WASM_F64,
    WASM_ANYREF = 128,
    WASM_FUNCREF,
};
#endif
 
#ifndef WASM_VAL_T_DEFINED
#define WASM_VAL_T_DEFINED
struct wasm_ref_t;
 
typedef struct wasm_val_t {
    wasm_valkind_t kind;
    uint8_t __paddings[7];
    union {
        /* also represent a function index */
        int32_t i32;
        int64_t i64;
        float f32;
        double f64;
        /* represent a foreign object, aka externref in .wat */
        uintptr_t foreign;
        struct wasm_ref_t *ref;
    } of;
} wasm_val_t;
#endif
 
typedef enum {
    WASM_LOG_LEVEL_FATAL = 0,
    WASM_LOG_LEVEL_ERROR = 1,
    WASM_LOG_LEVEL_WARNING = 2,
    WASM_LOG_LEVEL_DEBUG = 3,
    WASM_LOG_LEVEL_VERBOSE = 4
} log_level_t;
 
WASM_RUNTIME_API_EXTERN bool
wasm_runtime_init(void);
 
WASM_RUNTIME_API_EXTERN bool
wasm_runtime_full_init(RuntimeInitArgs *init_args);
 
WASM_RUNTIME_API_EXTERN void
wasm_runtime_set_log_level(log_level_t level);
 
WASM_RUNTIME_API_EXTERN bool
wasm_runtime_is_running_mode_supported(RunningMode running_mode);
 
WASM_RUNTIME_API_EXTERN bool
wasm_runtime_set_default_running_mode(RunningMode running_mode);
 
WASM_RUNTIME_API_EXTERN void
wasm_runtime_destroy(void);
 
WASM_RUNTIME_API_EXTERN void *
wasm_runtime_malloc(unsigned int size);
 
WASM_RUNTIME_API_EXTERN void *
wasm_runtime_realloc(void *ptr, unsigned int size);
 
/*
 * Free memory to runtime memory environment.
 */
WASM_RUNTIME_API_EXTERN void
wasm_runtime_free(void *ptr);
 
/*
 * Get memory info, only pool mode is supported now.
 */
WASM_RUNTIME_API_EXTERN bool
wasm_runtime_get_mem_alloc_info(mem_alloc_info_t *mem_alloc_info);
 
WASM_RUNTIME_API_EXTERN package_type_t
get_package_type(const uint8_t *buf, uint32_t size);
 
WASM_RUNTIME_API_EXTERN bool
wasm_runtime_is_xip_file(const uint8_t *buf, uint32_t size);
 
typedef bool (*module_reader)(package_type_t module_type,
                              const char *module_name,
                              uint8_t **p_buffer, uint32_t *p_size);
 
typedef void (*module_destroyer)(uint8_t *buffer, uint32_t size);
 
WASM_RUNTIME_API_EXTERN void
wasm_runtime_set_module_reader(const module_reader reader,
                               const module_destroyer destroyer);
WASM_RUNTIME_API_EXTERN bool
wasm_runtime_register_module(const char *module_name, wasm_module_t module,
                             char *error_buf, uint32_t error_buf_size);
 
WASM_RUNTIME_API_EXTERN wasm_module_t
wasm_runtime_find_module_registered(const char *module_name);
 
WASM_RUNTIME_API_EXTERN wasm_module_t
wasm_runtime_load(uint8_t *buf, uint32_t size,
                  char *error_buf, uint32_t error_buf_size);
 
WASM_RUNTIME_API_EXTERN wasm_module_t
wasm_runtime_load_from_sections(wasm_section_list_t section_list, bool is_aot,
                                char *error_buf, uint32_t error_buf_size);
 
WASM_RUNTIME_API_EXTERN void
wasm_runtime_unload(wasm_module_t module);
 
char *
wasm_runtime_get_module_hash(wasm_module_t module);
 
WASM_RUNTIME_API_EXTERN void
wasm_runtime_set_wasi_args_ex(wasm_module_t module,
                           const char *dir_list[], uint32_t dir_count,
                           const char *map_dir_list[], uint32_t map_dir_count,
                           const char *env[], uint32_t env_count,
                           char *argv[], int argc, int64_t stdinfd,
                           int64_t stdoutfd, int64_t stderrfd);
 
WASM_RUNTIME_API_EXTERN void
wasm_runtime_set_wasi_args(wasm_module_t module,
                           const char *dir_list[], uint32_t dir_count,
                           const char *map_dir_list[], uint32_t map_dir_count,
                           const char *env[], uint32_t env_count,
                           char *argv[], int argc);
 
WASM_RUNTIME_API_EXTERN void
wasm_runtime_set_wasi_addr_pool(wasm_module_t module, const char *addr_pool[],
                                uint32_t addr_pool_size);
 
WASM_RUNTIME_API_EXTERN void
wasm_runtime_set_wasi_ns_lookup_pool(wasm_module_t module, const char *ns_lookup_pool[],
                                     uint32_t ns_lookup_pool_size);
 
WASM_RUNTIME_API_EXTERN wasm_module_inst_t
wasm_runtime_instantiate(const wasm_module_t module,
                         uint32_t default_stack_size, uint32_t host_managed_heap_size,
                         char *error_buf, uint32_t error_buf_size);
 
WASM_RUNTIME_API_EXTERN wasm_module_inst_t
wasm_runtime_instantiate_ex(const wasm_module_t module,
                         const InstantiationArgs *args,
                         char *error_buf, uint32_t error_buf_size);
 
WASM_RUNTIME_API_EXTERN bool
wasm_runtime_set_running_mode(wasm_module_inst_t module_inst,
                              RunningMode running_mode);
 
WASM_RUNTIME_API_EXTERN RunningMode
wasm_runtime_get_running_mode(wasm_module_inst_t module_inst);
 
WASM_RUNTIME_API_EXTERN void
wasm_runtime_deinstantiate(wasm_module_inst_t module_inst);
 
WASM_RUNTIME_API_EXTERN wasm_module_t
wasm_runtime_get_module(wasm_module_inst_t module_inst);
 
WASM_RUNTIME_API_EXTERN bool
wasm_runtime_is_wasi_mode(wasm_module_inst_t module_inst);
 
WASM_RUNTIME_API_EXTERN wasm_function_inst_t
wasm_runtime_lookup_wasi_start_function(wasm_module_inst_t module_inst);
 
WASM_RUNTIME_API_EXTERN uint32_t
wasm_runtime_get_wasi_exit_code(wasm_module_inst_t module_inst);
 
WASM_RUNTIME_API_EXTERN wasm_function_inst_t
wasm_runtime_lookup_function(wasm_module_inst_t const module_inst,
                             const char *name);
 
WASM_RUNTIME_API_EXTERN uint32_t
wasm_func_get_param_count(wasm_function_inst_t const func_inst,
                          wasm_module_inst_t const module_inst);
 
WASM_RUNTIME_API_EXTERN uint32_t
wasm_func_get_result_count(wasm_function_inst_t const func_inst,
                           wasm_module_inst_t const module_inst);
 
WASM_RUNTIME_API_EXTERN void
wasm_func_get_param_types(wasm_function_inst_t const func_inst,
                          wasm_module_inst_t const module_inst,
                          wasm_valkind_t *param_types);
 
WASM_RUNTIME_API_EXTERN void
wasm_func_get_result_types(wasm_function_inst_t const func_inst,
                           wasm_module_inst_t const module_inst,
                           wasm_valkind_t *result_types);
 
WASM_RUNTIME_API_EXTERN wasm_exec_env_t
wasm_runtime_create_exec_env(wasm_module_inst_t module_inst,
                             uint32_t stack_size);
 
WASM_RUNTIME_API_EXTERN void
wasm_runtime_destroy_exec_env(wasm_exec_env_t exec_env);
 
WASM_RUNTIME_API_EXTERN wasm_exec_env_t
wasm_runtime_get_exec_env_singleton(wasm_module_inst_t module_inst);
 
WASM_RUNTIME_API_EXTERN uint32_t
wasm_runtime_start_debug_instance_with_port(wasm_exec_env_t exec_env, int32_t port);
 
WASM_RUNTIME_API_EXTERN uint32_t
wasm_runtime_start_debug_instance(wasm_exec_env_t exec_env);
 
WASM_RUNTIME_API_EXTERN bool
wasm_runtime_init_thread_env(void);
 
WASM_RUNTIME_API_EXTERN void
wasm_runtime_destroy_thread_env(void);
 
WASM_RUNTIME_API_EXTERN bool
wasm_runtime_thread_env_inited(void);
 
WASM_RUNTIME_API_EXTERN wasm_module_inst_t
wasm_runtime_get_module_inst(wasm_exec_env_t exec_env);
 
WASM_RUNTIME_API_EXTERN void
wasm_runtime_set_module_inst(wasm_exec_env_t exec_env,
                             const wasm_module_inst_t module_inst);
 
WASM_RUNTIME_API_EXTERN bool
wasm_runtime_call_wasm(wasm_exec_env_t exec_env,
                       wasm_function_inst_t function,
                       uint32_t argc, uint32_t argv[]);
 
WASM_RUNTIME_API_EXTERN bool
wasm_runtime_call_wasm_a(wasm_exec_env_t exec_env,
                         wasm_function_inst_t function,
                         uint32_t num_results, wasm_val_t results[],
                         uint32_t num_args, wasm_val_t *args);
 
WASM_RUNTIME_API_EXTERN bool
wasm_runtime_call_wasm_v(wasm_exec_env_t exec_env,
                         wasm_function_inst_t function,
                         uint32_t num_results, wasm_val_t results[],
                         uint32_t num_args, ...);
 
WASM_RUNTIME_API_EXTERN bool
wasm_runtime_call_indirect(wasm_exec_env_t exec_env, uint32_t element_index,
                           uint32_t argc, uint32_t argv[]);
 
WASM_RUNTIME_API_EXTERN bool
wasm_application_execute_main(wasm_module_inst_t module_inst,
                              int32_t argc, char *argv[]);
 
WASM_RUNTIME_API_EXTERN bool
wasm_application_execute_func(wasm_module_inst_t module_inst,
                              const char *name, int32_t argc, char *argv[]);
 
WASM_RUNTIME_API_EXTERN const char *
wasm_runtime_get_exception(wasm_module_inst_t module_inst);
 
WASM_RUNTIME_API_EXTERN void
wasm_runtime_set_exception(wasm_module_inst_t module_inst,
                           const char *exception);
 
WASM_RUNTIME_API_EXTERN void
wasm_runtime_clear_exception(wasm_module_inst_t module_inst);
 
WASM_RUNTIME_API_EXTERN void
wasm_runtime_terminate(wasm_module_inst_t module_inst);
 
WASM_RUNTIME_API_EXTERN void
wasm_runtime_set_custom_data(wasm_module_inst_t module_inst,
                             void *custom_data);
 
WASM_RUNTIME_API_EXTERN void *
wasm_runtime_get_custom_data(wasm_module_inst_t module_inst);
 
WASM_RUNTIME_API_EXTERN void
wasm_runtime_set_bounds_checks(wasm_module_inst_t module_inst,
                               bool enable);
 
WASM_RUNTIME_API_EXTERN bool
wasm_runtime_is_bounds_checks_enabled(
    wasm_module_inst_t module_inst);
 
WASM_RUNTIME_API_EXTERN uint64_t
wasm_runtime_module_malloc(wasm_module_inst_t module_inst, uint64_t size,
                           void **p_native_addr);
 
WASM_RUNTIME_API_EXTERN void
wasm_runtime_module_free(wasm_module_inst_t module_inst, uint64_t ptr);
 
WASM_RUNTIME_API_EXTERN uint64_t
wasm_runtime_module_dup_data(wasm_module_inst_t module_inst,
                             const char *src, uint64_t size);
 
WASM_RUNTIME_API_EXTERN bool
wasm_runtime_validate_app_addr(wasm_module_inst_t module_inst,
                               uint64_t app_offset, uint64_t size);
 
WASM_RUNTIME_API_EXTERN bool
wasm_runtime_validate_app_str_addr(wasm_module_inst_t module_inst,
                                   uint64_t app_str_offset);
 
WASM_RUNTIME_API_EXTERN bool
wasm_runtime_validate_native_addr(wasm_module_inst_t module_inst,
                                  void *native_ptr, uint64_t size);
 
WASM_RUNTIME_API_EXTERN void *
wasm_runtime_addr_app_to_native(wasm_module_inst_t module_inst,
                                uint64_t app_offset);
 
WASM_RUNTIME_API_EXTERN uint64_t
wasm_runtime_addr_native_to_app(wasm_module_inst_t module_inst,
                                void *native_ptr);
 
WASM_RUNTIME_API_EXTERN bool
wasm_runtime_get_app_addr_range(wasm_module_inst_t module_inst,
                                uint64_t app_offset,
                                uint64_t *p_app_start_offset,
                                uint64_t *p_app_end_offset);
 
WASM_RUNTIME_API_EXTERN bool
wasm_runtime_get_native_addr_range(wasm_module_inst_t module_inst,
                                   uint8_t *native_ptr,
                                   uint8_t **p_native_start_addr,
                                   uint8_t **p_native_end_addr);
 
WASM_RUNTIME_API_EXTERN bool
wasm_runtime_register_natives(const char *module_name,
                              NativeSymbol *native_symbols,
                              uint32_t n_native_symbols);
 
WASM_RUNTIME_API_EXTERN bool
wasm_runtime_register_natives_raw(const char *module_name,
                                  NativeSymbol *native_symbols,
                                  uint32_t n_native_symbols);
 
 
WASM_RUNTIME_API_EXTERN bool
wasm_runtime_unregister_natives(const char *module_name,
                                NativeSymbol *native_symbols);
 
WASM_RUNTIME_API_EXTERN void *
wasm_runtime_get_function_attachment(wasm_exec_env_t exec_env);
 
WASM_RUNTIME_API_EXTERN void
wasm_runtime_set_user_data(wasm_exec_env_t exec_env, void *user_data);
 
WASM_RUNTIME_API_EXTERN void *
wasm_runtime_get_user_data(wasm_exec_env_t exec_env);
 
WASM_RUNTIME_API_EXTERN void
wasm_runtime_dump_mem_consumption(wasm_exec_env_t exec_env);
 
WASM_RUNTIME_API_EXTERN void
wasm_runtime_dump_perf_profiling(wasm_module_inst_t module_inst);
 
WASM_RUNTIME_API_EXTERN double
wasm_runtime_sum_wasm_exec_time(wasm_module_inst_t module_inst);
 
WASM_RUNTIME_API_EXTERN double
wasm_runtime_get_wasm_func_exec_time(wasm_module_inst_t inst,
                                     const char *func_name);
 
/* 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;
 
WASM_RUNTIME_API_EXTERN void
wasm_runtime_set_max_thread_num(uint32_t num);
 
WASM_RUNTIME_API_EXTERN wasm_exec_env_t
wasm_runtime_spawn_exec_env(wasm_exec_env_t exec_env);
 
WASM_RUNTIME_API_EXTERN void
wasm_runtime_destroy_spawned_exec_env(wasm_exec_env_t exec_env);
 
WASM_RUNTIME_API_EXTERN int32_t
wasm_runtime_spawn_thread(wasm_exec_env_t exec_env, wasm_thread_t *tid,
                          wasm_thread_callback_t callback, void *arg);
 
WASM_RUNTIME_API_EXTERN int32_t
wasm_runtime_join_thread(wasm_thread_t tid, void **retval);
 
WASM_RUNTIME_API_EXTERN bool
wasm_externref_obj2ref(wasm_module_inst_t module_inst,
                       void *extern_obj, uint32_t *p_externref_idx);
 
WASM_RUNTIME_API_EXTERN bool
wasm_externref_objdel(wasm_module_inst_t module_inst, void *extern_obj);
 
WASM_RUNTIME_API_EXTERN bool
wasm_externref_set_cleanup(wasm_module_inst_t module_inst, void *extern_obj,
                           void (*extern_obj_cleanup)(void *));
 
WASM_RUNTIME_API_EXTERN bool
wasm_externref_ref2obj(uint32_t externref_idx, void **p_extern_obj);
 
WASM_RUNTIME_API_EXTERN bool
wasm_externref_retain(uint32_t externref_idx);
 
WASM_RUNTIME_API_EXTERN void
wasm_runtime_dump_call_stack(wasm_exec_env_t exec_env);
 
WASM_RUNTIME_API_EXTERN uint32_t
wasm_runtime_get_call_stack_buf_size(wasm_exec_env_t exec_env);
 
WASM_RUNTIME_API_EXTERN uint32_t
wasm_runtime_dump_call_stack_to_buf(wasm_exec_env_t exec_env, char *buf,
                                    uint32_t len);
 
WASM_RUNTIME_API_EXTERN uint32_t
wasm_runtime_get_pgo_prof_data_size(wasm_module_inst_t module_inst);
 
WASM_RUNTIME_API_EXTERN uint32_t
wasm_runtime_dump_pgo_prof_data_to_buf(wasm_module_inst_t module_inst,
                                       char *buf, uint32_t len);
 
WASM_RUNTIME_API_EXTERN const uint8_t *
wasm_runtime_get_custom_section(wasm_module_t const module_comm,
                                const char *name, uint32_t *len);
 
 
WASM_RUNTIME_API_EXTERN void
wasm_runtime_get_version(uint32_t *major, uint32_t *minor, uint32_t *patch);
 
WASM_RUNTIME_API_EXTERN bool
wasm_runtime_is_import_func_linked(const char *module_name,
                                   const char *func_name);
 
WASM_RUNTIME_API_EXTERN bool
wasm_runtime_is_import_global_linked(const char *module_name,
                                     const char *global_name);
 
typedef enum {
    INTERNAL_ERROR,
    MAX_SIZE_REACHED,
} enlarge_memory_error_reason_t;
 
typedef void (*enlarge_memory_error_callback_t)(
    uint32_t inc_page_count, uint64_t current_memory_size,
    uint32_t memory_index, enlarge_memory_error_reason_t failure_reason,
    wasm_module_inst_t instance, wasm_exec_env_t exec_env,
    void* user_data);
 
WASM_RUNTIME_API_EXTERN void
wasm_runtime_set_enlarge_mem_error_callback(
    const enlarge_memory_error_callback_t callback, void *user_data);
 
/*
 * module instance context APIs
 *   wasm_runtime_create_context_key
 *   wasm_runtime_destroy_context_key
 *   wasm_runtime_set_context
 *   wasm_runtime_set_context_spread
 *   wasm_runtime_get_context
 *
 * This set of APIs is intended to be used by an embedder which provides
 * extra sets of native functions, which need per module instance state
 * and are maintained outside of the WAMR tree.
 *
 * It's modelled after the pthread specific API.
 *
 * wasm_runtime_set_context_spread is similar to
 * wasm_runtime_set_context, except that
 * wasm_runtime_set_context_spread applies the change
 * to all threads in the cluster.
 * It's an undefined behavior if multiple threads in a cluster call
 * wasm_runtime_set_context_spread on the same key
 * simultaneously. It's a caller's resposibility to perform necessary
 * serialization if necessary. For example:
 *
 * if (wasm_runtime_get_context(inst, key) == NULL) {
 *     newctx = alloc_and_init(...);
 *     lock(some_lock);
 *     if (wasm_runtime_get_context(inst, key) == NULL) {
 *         // this thread won the race
 *         wasm_runtime_set_context_spread(inst, key, newctx);
 *         newctx = NULL;
 *     }
 *     unlock(some_lock);
 *     if (newctx != NULL) {
 *         // this thread lost the race, free it
 *         cleanup_and_free(newctx);
 *     }
 * }
 *
 * Note: dynamic key create/destroy while instances are live is not
 * implemented as of writing this.
 * it's caller's resposibility to ensure destorying all module instances
 * before calling wasm_runtime_create_context_key or
 * wasm_runtime_destroy_context_key.
 * otherwise, it's an undefined behavior.
 *
 * Note about threads:
 * - When spawning a thread, the contexts (the pointers given to
 *   wasm_runtime_set_context) are copied from the parent
 *   instance.
 * - The destructor is called only on the main instance.
 */
 
WASM_RUNTIME_API_EXTERN void *
wasm_runtime_create_context_key(
    void (*dtor)(wasm_module_inst_t inst, void *ctx));
 
WASM_RUNTIME_API_EXTERN void
wasm_runtime_destroy_context_key(void *key);
 
WASM_RUNTIME_API_EXTERN void
wasm_runtime_set_context(wasm_module_inst_t inst, void *key, void *ctx);
 
WASM_RUNTIME_API_EXTERN void
wasm_runtime_set_context_spread(wasm_module_inst_t inst, void *key, void *ctx);
 
WASM_RUNTIME_API_EXTERN void *
wasm_runtime_get_context(wasm_module_inst_t inst, void *key);
 
/*
 * wasm_runtime_begin_blocking_op/wasm_runtime_end_blocking_op
 *
 * These APIs are intended to be used by the implementations of
 * host functions. It wraps an operation which possibly blocks for long
 * to prepare for async termination.
 *
 * For simplicity, we recommend to wrap only the very minimum piece of
 * the code with this. Ideally, just a single system call.
 *
 * eg.
 *
 *   if (!wasm_runtime_begin_blocking_op(exec_env)) {
 *       return EINTR;
 *   }
 *   ret = possibly_blocking_op();
 *   wasm_runtime_end_blocking_op(exec_env);
 *   return ret;
 *
 * If threading support (WASM_ENABLE_THREAD_MGR) is not enabled,
 * these functions are no-op.
 *
 * If the underlying platform support (OS_ENABLE_WAKEUP_BLOCKING_OP) is
 * not available, these functions are no-op. In that case, the runtime
 * might not terminate a blocking thread in a timely manner.
 *
 * If the underlying platform support is available, it's used to wake up
 * the thread for async termination. The expectation here is that a
 * `os_wakeup_blocking_op` call makes the blocking operation
 * (`possibly_blocking_op` in the above example) return in a timely manner.
 *
 * The actual wake up mechanism used by `os_wakeup_blocking_op` is
 * platform-dependent. It might impose some platform-dependent restrictions
 * on the implementation of the blocking opearation.
 *
 * For example, on POSIX-like platforms, a signal (by default SIGUSR1) is
 * used. The signal delivery configurations (eg. signal handler, signal mask,
 * etc) for the signal are set up by the runtime. You can change the signal
 * to use for this purpose by calling os_set_signal_number_for_blocking_op
 * before the runtime initialization.
 */
WASM_RUNTIME_API_EXTERN bool
wasm_runtime_begin_blocking_op(wasm_exec_env_t exec_env);
 
WASM_RUNTIME_API_EXTERN void
wasm_runtime_end_blocking_op(wasm_exec_env_t exec_env);
 
 
WASM_RUNTIME_API_EXTERN bool
wasm_runtime_set_module_name(wasm_module_t module, const char *name,
                             char *error_buf, uint32_t error_buf_size);
 
/* return the most recently set module name or "" if never set before */
WASM_RUNTIME_API_EXTERN const char*
wasm_runtime_get_module_name(wasm_module_t module);
 
/* clang-format on */
 
#ifdef __cplusplus
}
#endif
 
#endif /* end of _WASM_EXPORT_H */