diff --git a/doc/api/embedding.md b/doc/api/embedding.md index cda3481923add3..3828636bbe79c6 100644 --- a/doc/api/embedding.md +++ b/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` + +> 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` + +> 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`