add support for linked modules

doc/api/embedding.md

@@ -214,7 +214,6 @@ The C embedder API has the four major API function groups:
   set of functions. The embedding APIs provide access to functions that
   retrieve or create `napi_env` instances related to a runtime instance.
 
-
 ## API reference
 
 The C embedder API is split up by the four major groups described above.
@@ -234,7 +233,6 @@ added: REPLACEME
 This is an opaque pointer that represents a Node.js platform instance.
 Node.js allows only a single platform instance per process.
 
-
 ##### `node_embedding_platform_flags`
 
 <!-- YAML
@@ -291,7 +289,6 @@ Node.js platform initialization.
 - `node_embedding_platform_generate_predictable_snapshot` - Initialize the
   process for predictable snapshot generation.
 
-
 #### Callback types
 
 ##### `node_embedding_error_handler`
@@ -323,7 +320,6 @@ The callback parameters:
   `exit_code` is zero, then the callback is used to output non-error messages.
 - `[in] status`: Reported Node-API status.
 
-
 ##### `node_embedding_get_args_callback`
 
 <!-- YAML
@@ -347,7 +343,6 @@ The callback parameters:
 - `[in] argc`: Number of items in the `argv` array.
 - `[in] argv`: CLI arguments as an array of zero terminating strings.
 
-
 #### Functions
 
 ##### `node_embedding_on_error`
@@ -383,7 +378,6 @@ process with the `exit_code` when it is not zero.
 The zero `exit_code` indicates reported warnings or text messages. For example,
 it can be Node.js help text returned in response to the `--help` CLI argument.
 
-
 ##### `node_embedding_create_platform`
 
 <!-- YAML
@@ -410,7 +404,6 @@ other complex work that may fail. It only checks the argument.
 
 Node.js allows only a single platform instance per process.
 
-
 ##### `node_embedding_delete_platform`
 
 <!-- YAML
@@ -433,7 +426,6 @@ Returns `napi_ok` if there were no issues.
 If the platform was initialized before the deletion, then the method
 uninitializes the platform before deletion.
 
-
 ##### `node_embedding_platform_is_initialized`
 
 <!-- YAML
@@ -459,7 +451,6 @@ The platform instance settings can be changed until the platform is initialized.
 After the `node_embedding_platform_initialize` function call any attempt to
 change platform instance settings will fail.
 
-
 ##### `node_embedding_platform_set_flags`
 
 <!-- YAML
@@ -481,7 +472,6 @@ node_embedding_platform_set_flags(node_embedding_platform platform,
 
 Returns `napi_ok` if there were no issues.
 
-
 ##### `node_embedding_platform_set_args`
 
 <!-- YAML
@@ -505,7 +495,6 @@ node_embedding_platform_set_args(node_embedding_platform platform,
 
 Returns `napi_ok` if there were no issues.
 
-
 ##### `node_embedding_platform_initialize`
 
 <!-- YAML
@@ -538,7 +527,6 @@ changed anymore. The parsed arguments can be accessed by calling the
 `node_embedding_platform_get_args` and `node_embedding_platform_get_exec_args`
 functions.
 
-
 ##### `node_embedding_platform_get_args`
 
 <!-- YAML
@@ -563,7 +551,6 @@ node_embedding_platform_get_args(node_embedding_platform platform,
 
 Returns `napi_ok` if there were no issues.
 
-
 ##### `node_embedding_platform_get_exec_args`
 
 <!-- YAML
@@ -589,7 +576,6 @@ node_embedding_platform_get_exec_args(
 
 Returns `napi_ok` if there were no issues.
 
-
 ### Runtime instance APIs
 
 #### Data types
@@ -681,7 +667,6 @@ Node.js runtime initialization.
   during the runtime creation. It's used to call `node::Stop(env)` on a Worker
   thread that is waiting for the events.
 
-
 ##### `node_embedding_snapshot_flags`
 
 <!-- YAML
@@ -708,7 +693,6 @@ Node.js runtime snapshot creation.
   compiling functions included in the snapshot at the expense of a bigger
   snapshot size and potentially breaking portability of the snapshot.
 
-
 #### Callback types
 
 ##### `node_embedding_runtime_preload_callback`
@@ -737,7 +721,6 @@ The callback parameters:
 - `[in] process`: The Node.js `process` object.
 - `[in] require`: The internal `require` function.
 
-
 ##### `node_embedding_store_blob_callback`
 
 <!-- YAML
@@ -762,6 +745,35 @@ The callback parameters:
 - `[in] blob`: Start of the blob memory span.
 - `[in] size`: Size of the blob memory span.
 
+##### `node_embedding_initialize_module_callback`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+```c
+typedef napi_value(NAPI_CDECL* node_embedding_initialize_module_callback)(
+    void* cb_data,
+    napi_env env,
+    const char* module_name,
+    napi_value exports);
+```
+
+Function pointer type for initializing linked native module that can be defined
+in the embedder executable.
+
+The callback parameters:
+
+- `[in] cb_data`: The user data associated with this callback.
+- `[in] env`: Node API environment.
+- `[in] module_name`: Name of the module.
+- `[in] exports`: The `exports` module object.
+
+All module exports must be added as properties to the `exports` object.
+As an alternative a new object or another value can be created in the callback
+and returned.
 
 #### Functions
 
@@ -800,7 +812,6 @@ If it is planned to create more than one runtime instance or a non-default
 platform configuration is required, then it is recommended to create the
 Node.js platform instance explicitly.
 
-
 ##### `node_embedding_delete_runtime`
 
 <!-- YAML
@@ -827,7 +838,6 @@ As a part of the un-initialization it can store created snapshot blob if the
 `node_embedding_runtime_on_create_snapshot` set the callback to save the
 snapshot blob.
 
-
 ##### `node_embedding_runtime_is_initialized`
 
 <!-- YAML
@@ -853,7 +863,6 @@ The runtime settings can be changed until the runtime is initialized.
 After the `node_embedding_runtime_initialize` function is called any attempt to change
 runtime settings will fail.
 
-
 ##### `node_embedding_runtime_set_flags`
 
 <!-- YAML
@@ -875,7 +884,6 @@ node_embedding_runtime_set_flags(node_embedding_runtime runtime,
 
 Returns `napi_ok` if there were no issues.
 
-
 ##### `node_embedding_runtime_set_args`
 
 Sets the non-Node.js arguments for the Node.js runtime instance.
@@ -893,7 +901,6 @@ node_embedding_runtime_set_args(node_embedding_runtime runtime,
 
 Returns `napi_ok` if there were no issues.
 
-
 ##### `node_embedding_runtime_set_exec_args`
 
 Sets the Node.js arguments for the Node.js runtime instance.
@@ -911,7 +918,6 @@ node_embedding_runtime_set_exec_args(node_embedding_runtime runtime,
 
 Returns `napi_ok` if there were no issues.
 
-
 ##### `node_embedding_runtime_on_preload`
 
 <!-- YAML
@@ -939,7 +945,6 @@ node_embedding_runtime_on_preload(
 
 Returns `napi_ok` if there were no issues.
 
-
 ##### `node_embedding_runtime_use_snapshot`
 
 <!-- YAML
@@ -963,7 +968,6 @@ node_embedding_runtime_use_snapshot(node_embedding_runtime runtime,
 
 Returns `napi_ok` if there were no issues.
 
-
 ##### `node_embedding_runtime_on_create_snapshot`
 
 <!-- YAML
@@ -994,6 +998,38 @@ node_embedding_runtime_on_create_snapshot(
 
 Returns `napi_ok` if there were no issues.
 
+##### `node_embedding_runtime_add_module`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+Adds a linked module for the Node.js runtime instance.
+
+```c
+napi_status NAPI_CDECL
+node_embedding_runtime_add_module(
+    node_embedding_runtime runtime,
+    const char* module_name,
+    node_embedding_initialize_module_callback init_module_cb,
+    void* init_module_cb_data,
+    int32_t module_node_api_version);
+```
+
+- `[in] runtime`: The Node.js runtime instance.
+- `[in] module_name`: The name of the module.
+- `[in] init_module_cb`: Module initialization callback. It is called for the
+  main and worker threads. The caller must take care about the thread safety.
+- `[in] init_module_cb_data`: The user data for the init_module_cb.
+- `[in] module_node_api_version`: The Node API version used by the module.
+
+Returns `napi_ok` if there were no issues.
+
+The registered module can be accessed in JavaScript as
+`process._linkedBinding(module_name)` in the main JS and in the related
+worker threads.
 
 ##### `node_embedding_runtime_initialize`
 
@@ -1022,7 +1058,6 @@ with a V8 `Isolate` and V8 `Context`.
 After the initialization is completed the Node.js runtime settings cannot be
 changed anymore.
 
-
 ### Event loop APIs
 
 #### Data types
@@ -1052,7 +1087,6 @@ beahvior.
 - `node_embedding_event_loop_run_nowait` - Run the event loop once and do not
   wait if there are no items. It matches the `UV_RUN_NOWAIT` behavior.
 
-
 #### Callback types
 
 ##### `node_embedding_event_loop_predicate`
@@ -1079,7 +1113,6 @@ The callback parameters:
 
 Returns `true` if the runtime loop must continue to run.
 
-
 #### Functions
 
 ##### `node_embedding_runtime_run_event_loop`
@@ -1103,7 +1136,6 @@ Returns `napi_ok` if there were no issues.
 
 The function exits when there are no more tasks to process in the loop.
 
-
 ##### `node_embedding_runtime_run_event_loop_while`
 
 <!-- YAML
@@ -1129,7 +1161,7 @@ node_embedding_runtime_run_event_loop_while(
 - `[in] predicate`: The predicate to check before each runtime event loop
   task invocation.
 - `[in] predicate_data`: Optional. The predicate data that will be
-  passed to the `predicate` callback. It can be removed right after this 
+  passed to the `predicate` callback. It can be removed right after this
   function call.
 - `[in] run_mode`: Specifies behavior in case if the event loop does not have
   items to process. The `node_embedding_event_loop_run_once` will block the
@@ -1140,7 +1172,6 @@ node_embedding_runtime_run_event_loop_while(
 
 Returns `napi_ok` if there were no issues.
 
-
 ##### `node_embedding_runtime_await_promise`
 
 <!-- YAML
@@ -1169,7 +1200,6 @@ node_embedding_runtime_await_promise(node_embedding_runtime runtime,
 
 Returns `napi_ok` if there were no issues.
 
-
 ### JavaScript/Native interop APIs
 
 #### Functions
@@ -1197,7 +1227,6 @@ Returns `napi_ok` if there were no issues.
 
 By default it is using the Node-API version 8.
 
-
 ##### `node_embedding_runtime_get_node_api_env`
 
 <!-- YAML
@@ -1219,7 +1248,6 @@ node_embedding_runtime_get_node_api_env(node_runtime embedding_runtime,
 
 Returns `napi_ok` if there were no issues.
 
-
 ##### `node_embedding_runtime_open_scope`
 
 <!-- YAML
@@ -1247,7 +1275,6 @@ Then, it opens the V8 Handle scope and the V8 Context scope.
 It enables use of V8 API and the Node APIs which is a C API on top of
 the V8 API.
 
-
 ##### `node_runtime_close_scope`
 
 <!-- YAML
@@ -1274,7 +1301,6 @@ current thread. Each opened runtime scoped must be closed in the end.
 This function closes V8 Context scope, V8 Handle scope, V8 Isolate scope, and
 then makes the V8 Isolate leave the current thread.
 
-
 ## Examples
 
 The examples listed here are part of the Node.js

src/node_api.cc

@@ -164,9 +164,11 @@ void ThrowNodeApiVersionError(node::Environment* node_env,
   node_env->ThrowError(error_message.c_str());
 }
 
-inline napi_env NewEnv(v8::Local<v8::Context> context,
-                       const std::string& module_filename,
-                       int32_t module_api_version) {
+}  // namespace
+
+napi_env NewEnv(v8::Local<v8::Context> context,
+                const std::string& module_filename,
+                int32_t module_api_version) {
   node_napi_env result;
 
   // Validate module_api_version.
@@ -196,6 +198,8 @@ inline napi_env NewEnv(v8::Local<v8::Context> context,
   return result;
 }
 
+namespace {
+
 class ThreadSafeFunction : public node::AsyncResource {
  public:
   ThreadSafeFunction(v8::Local<v8::Function> func,