xref: /third_party/node/src/jsvm_node_api.h (revision 1cb0ef41) 
1#ifndef SRC_NODE_API_H_
2#define SRC_NODE_API_H_
3
4#ifdef BUILDING_NODE_EXTENSION
5#ifdef _WIN32
6// Building native addon against node
7#define JSVM_EXTERN __declspec(dllimport)
8#elif defined(__wasm32__)
9#define JSVM_EXTERN __attribute__((__import_module__("napi")))
10#endif
11#endif
12#include "jsvm.h"
13#include "jsvm_node_api_types.h"
14
15struct uv_loop_s;  // Forward declaration.
16
17#ifdef _WIN32
18#define JSVM_MODULE_EXPORT __declspec(dllexport)
19#else
20#define JSVM_MODULE_EXPORT __attribute__((visibility("default")))
21#endif
22
23#if defined(__GNUC__)
24#define JSVM_NO_RETURN __attribute__((noreturn))
25#elif defined(_WIN32)
26#define JSVM_NO_RETURN __declspec(noreturn)
27#else
28#define JSVM_NO_RETURN
29#endif
30
31typedef JSVM_Value(JSVM_CDECL* jsvm_addon_register_func)(JSVM_Env env,
32                                                         JSVM_Value exports);
33typedef int32_t(JSVM_CDECL* node_api_addon_get_api_version_func)();
34
35// Used by deprecated registration method jsvm_module_register.
36typedef struct jsvm_module {
37  int nm_version;
38  unsigned int nm_flags;
39  const char* nm_filename;
40  jsvm_addon_register_func nm_register_func;
41  const char* nm_modname;
42  void* nm_priv;
43  void* reserved[4];
44} jsvm_module;
45
46#define JSVM_MODULE_VERSION 1
47
48#define JSVM_MODULE_INITIALIZER_X(base, version)                               \
49  JSVM_MODULE_INITIALIZER_X_HELPER(base, version)
50#define JSVM_MODULE_INITIALIZER_X_HELPER(base, version) base##version
51
52#ifdef __wasm32__
53#define JSVM_MODULE_INITIALIZER_BASE jsvm_register_wasm_v
54#else
55#define JSVM_MODULE_INITIALIZER_BASE jsvm_register_module_v
56#endif
57
58#define NODE_API_MODULE_GET_API_VERSION_BASE node_api_module_get_api_version_v
59
60#define JSVM_MODULE_INITIALIZER                                                \
61  JSVM_MODULE_INITIALIZER_X(JSVM_MODULE_INITIALIZER_BASE, JSVM_MODULE_VERSION)
62
63#define NODE_API_MODULE_GET_API_VERSION                                        \
64  JSVM_MODULE_INITIALIZER_X(NODE_API_MODULE_GET_API_VERSION_BASE,              \
65                            JSVM_MODULE_VERSION)
66
67#define JSVM_MODULE_INIT()                                                     \
68  EXTERN_C_START                                                               \
69  JSVM_MODULE_EXPORT int32_t NODE_API_MODULE_GET_API_VERSION() {               \
70    return NAPI_VERSION;                                                       \
71  }                                                                            \
72  JSVM_MODULE_EXPORT JSVM_Value JSVM_MODULE_INITIALIZER(JSVM_Env env,          \
73                                                        JSVM_Value exports);   \
74  EXTERN_C_END                                                                 \
75  JSVM_Value JSVM_MODULE_INITIALIZER(JSVM_Env env, JSVM_Value exports)
76
77#define JSVM_MODULE(modname, regfunc)                                          \
78  JSVM_MODULE_INIT() { return regfunc(env, exports); }
79
80// Deprecated. Use JSVM_MODULE.
81#define JSVM_MODULE_X(modname, regfunc, priv, flags)                           \
82  JSVM_MODULE(modname, regfunc)
83
84EXTERN_C_START
85
86// Deprecated. Replaced by symbol-based registration defined by JSVM_MODULE
87// and JSVM_MODULE_INIT macros.
88#if defined(__cplusplus) && __cplusplus >= 201402L
89[[deprecated]]
90#endif
91JSVM_EXTERN void JSVM_CDECL
92jsvm_module_register(jsvm_module* mod);
93
94JSVM_EXTERN JSVM_NO_RETURN void JSVM_CDECL
95jsvm_fatal_error(const char* location,
96                 size_t location_len,
97                 const char* message,
98                 size_t message_len);
99
100// Methods for custom handling of async operations
101JSVM_EXTERN JSVM_Status JSVM_CDECL
102jsvm_async_init(JSVM_Env env,
103                JSVM_Value async_resource,
104                JSVM_Value async_resource_name,
105                jsvm_async_context* result);
106
107JSVM_EXTERN JSVM_Status JSVM_CDECL
108jsvm_async_destroy(JSVM_Env env, jsvm_async_context async_context);
109
110JSVM_EXTERN JSVM_Status JSVM_CDECL
111jsvm_make_callback(JSVM_Env env,
112                   jsvm_async_context async_context,
113                   JSVM_Value recv,
114                   JSVM_Value func,
115                   size_t argc,
116                   const JSVM_Value* argv,
117                   JSVM_Value* result);
118
119// Methods to provide node::Buffer functionality with napi types
120JSVM_EXTERN JSVM_Status JSVM_CDECL jsvm_create_buffer(JSVM_Env env,
121                                                      size_t length,
122                                                      void** data,
123                                                      JSVM_Value* result);
124#ifndef NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED
125JSVM_EXTERN JSVM_Status JSVM_CDECL
126OH_JSVM_CreateExternal_buffer(JSVM_Env env,
127                            size_t length,
128                            void* data,
129                            JSVM_Finalize finalizeCb,
130                            void* finalizeHint,
131                            JSVM_Value* result);
132#endif  // NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED
133JSVM_EXTERN JSVM_Status JSVM_CDECL jsvm_create_buffer_copy(JSVM_Env env,
134                                                           size_t length,
135                                                           const void* data,
136                                                           void** result_data,
137                                                           JSVM_Value* result);
138JSVM_EXTERN JSVM_Status JSVM_CDECL jsvm_is_buffer(JSVM_Env env,
139                                                  JSVM_Value value,
140                                                  bool* result);
141JSVM_EXTERN JSVM_Status JSVM_CDECL jsvm_get_buffer_info(JSVM_Env env,
142                                                        JSVM_Value value,
143                                                        void** data,
144                                                        size_t* length);
145
146#ifndef __wasm32__
147// Methods to manage simple async operations
148JSVM_EXTERN JSVM_Status JSVM_CDECL
149jsvm_create_async_work(JSVM_Env env,
150                       JSVM_Value async_resource,
151                       JSVM_Value async_resource_name,
152                       jsvm_async_execute_callback execute,
153                       jsvm_async_complete_callback complete,
154                       void* data,
155                       jsvm_async_work* result);
156JSVM_EXTERN JSVM_Status JSVM_CDECL jsvm_delete_async_work(JSVM_Env env,
157                                                          jsvm_async_work work);
158JSVM_EXTERN JSVM_Status JSVM_CDECL jsvm_queue_async_work(JSVM_Env env,
159                                                         jsvm_async_work work);
160JSVM_EXTERN JSVM_Status JSVM_CDECL jsvm_cancel_async_work(JSVM_Env env,
161                                                          jsvm_async_work work);
162#endif  // __wasm32__
163
164// version management
165JSVM_EXTERN JSVM_Status JSVM_CDECL
166jsvm_get_node_version(JSVM_Env env, const jsvm_node_version** version);
167
168#if NAPI_VERSION >= 2
169
170// Return the current libuv event loop for a given environment
171JSVM_EXTERN JSVM_Status JSVM_CDECL
172jsvm_get_uv_event_loop(JSVM_Env env, struct uv_loop_s** loop);
173
174#endif  // NAPI_VERSION >= 2
175
176#if NAPI_VERSION >= 3
177
178JSVM_EXTERN JSVM_Status JSVM_CDECL jsvm_fatal_exception(JSVM_Env env,
179                                                        JSVM_Value err);
180
181JSVM_EXTERN JSVM_Status JSVM_CDECL
182jsvm_add_env_cleanup_hook(JSVM_Env env, jsvm_cleanup_hook fun, void* arg);
183
184JSVM_EXTERN JSVM_Status JSVM_CDECL
185jsvm_remove_env_cleanup_hook(JSVM_Env env, jsvm_cleanup_hook fun, void* arg);
186
187JSVM_EXTERN JSVM_Status JSVM_CDECL
188jsvm_open_callback_scope(JSVM_Env env,
189                         JSVM_Value resource_object,
190                         jsvm_async_context context,
191                         jsvm_callback_scope* result);
192
193JSVM_EXTERN JSVM_Status JSVM_CDECL
194jsvm_close_callback_scope(JSVM_Env env, jsvm_callback_scope scope);
195
196#endif  // NAPI_VERSION >= 3
197
198#if NAPI_VERSION >= 4
199
200#ifndef __wasm32__
201// Calling into JS from other threads
202JSVM_EXTERN JSVM_Status JSVM_CDECL
203jsvm_create_threadsafe_function(JSVM_Env env,
204                                JSVM_Value func,
205                                JSVM_Value async_resource,
206                                JSVM_Value async_resource_name,
207                                size_t max_queue_size,
208                                size_t initial_thread_count,
209                                void* thread_finalize_data,
210                                JSVM_Finalize thread_finalize_cb,
211                                void* context,
212                                jsvm_threadsafe_function_call_js call_js_cb,
213                                jsvm_threadsafe_function* result);
214
215JSVM_EXTERN JSVM_Status JSVM_CDECL jsvm_get_threadsafe_function_context(
216    jsvm_threadsafe_function func, void** result);
217
218JSVM_EXTERN JSVM_Status JSVM_CDECL
219jsvm_call_threadsafe_function(jsvm_threadsafe_function func,
220                              void* data,
221                              jsvm_threadsafe_function_call_mode is_blocking);
222
223JSVM_EXTERN JSVM_Status JSVM_CDECL
224jsvm_acquire_threadsafe_function(jsvm_threadsafe_function func);
225
226JSVM_EXTERN JSVM_Status JSVM_CDECL jsvm_release_threadsafe_function(
227    jsvm_threadsafe_function func, jsvm_threadsafe_function_release_mode mode);
228
229JSVM_EXTERN JSVM_Status JSVM_CDECL
230jsvm_unref_threadsafe_function(JSVM_Env env, jsvm_threadsafe_function func);
231
232JSVM_EXTERN JSVM_Status JSVM_CDECL
233jsvm_ref_threadsafe_function(JSVM_Env env, jsvm_threadsafe_function func);
234#endif  // __wasm32__
235
236#endif  // NAPI_VERSION >= 4
237
238#if NAPI_VERSION >= 8
239
240JSVM_EXTERN JSVM_Status JSVM_CDECL
241jsvm_add_async_cleanup_hook(JSVM_Env env,
242                            jsvm_async_cleanup_hook hook,
243                            void* arg,
244                            jsvm_async_cleanup_hook_handle* remove_handle);
245
246JSVM_EXTERN JSVM_Status JSVM_CDECL
247jsvm_remove_async_cleanup_hook(jsvm_async_cleanup_hook_handle remove_handle);
248
249#endif  // NAPI_VERSION >= 8
250
251#if NAPI_VERSION >= 9
252
253JSVM_EXTERN JSVM_Status JSVM_CDECL
254node_api_get_module_file_name(JSVM_Env env, const char** result);
255
256#endif  // NAPI_VERSION >= 9
257
258EXTERN_C_END
259
260#endif  // SRC_NODE_API_H_
261