FM / api

/usr/share/doc/nodejs/api

Name	Size	Mode	Actions
assets/	-	0755	rm
addons.html	85172	0644	edit dl rm
addons.json.gz	11188	0644	edit dl rm
addons.md	41013	0644	edit dl rm
all.html	4598048	0644	edit dl rm
all.json.gz	681643	0644	edit dl rm
assert.html	110665	0644	edit dl rm
assert.json.gz	12007	0644	edit dl rm
assert.md	47147	0644	edit dl rm
async_hooks.html	83599	0644	edit dl rm
async_hooks.json.gz	14085	0644	edit dl rm
async_hooks.md	38888	0644	edit dl rm
buffer.html	245762	0644	edit dl rm
buffer.json.gz	24105	0644	edit dl rm
buffer.md	105044	0644	edit dl rm
child_process.html	136767	0644	edit dl rm
child_process.json.gz	19399	0644	edit dl rm
child_process.md	62919	0644	edit dl rm
cli.html	87936	0644	edit dl rm
cli.json.gz	16615	0644	edit dl rm
cli.md	42263	0644	edit dl rm
cluster.html	60116	0644	edit dl rm
cluster.json.gz	9557	0644	edit dl rm
cluster.md	25426	0644	edit dl rm
console.html	46093	0644	edit dl rm
console.json.gz	6056	0644	edit dl rm
console.md	16431	0644	edit dl rm
crypto.html	283043	0644	edit dl rm
crypto.json.gz	32118	0644	edit dl rm
crypto.md	125198	0644	edit dl rm
debugger.html	18089	0644	edit dl rm
debugger.json.gz	2820	0644	edit dl rm
debugger.md	6133	0644	edit dl rm
deprecations.html	138537	0644	edit dl rm
deprecations.json.gz	18470	0644	edit dl rm
deprecations.md	79120	0644	edit dl rm
dgram.html	62425	0644	edit dl rm
dgram.json.gz	9630	0644	edit dl rm
dgram.md	27746	0644	edit dl rm
dns.html	98289	0644	edit dl rm
dns.json.gz	13838	0644	edit dl rm
dns.md	40799	0644	edit dl rm
documentation.html	10978	0644	edit dl rm
documentation.json	3328	0644	edit dl rm
documentation.md	2247	0644	edit dl rm
domain.html	36301	0644	edit dl rm
domain.json.gz	6355	0644	edit dl rm
domain.md	15521	0644	edit dl rm
embedding.html	18165	0644	edit dl rm
embedding.json.gz	3625	0644	edit dl rm
embedding.md	8811	0644	edit dl rm
errors.html	182982	0644	edit dl rm
errors.json.gz	36479	0644	edit dl rm
errors.md	81734	0644	edit dl rm
esm.html	92490	0644	edit dl rm
esm.json.gz	15054	0644	edit dl rm
esm.md	48466	0644	edit dl rm
events.html	75986	0644	edit dl rm
events.json.gz	9561	0644	edit dl rm
events.md	28823	0644	edit dl rm
fs.html	437179	0644	edit dl rm
fs.json.gz	47095	0644	edit dl rm
fs.md	187735	0644	edit dl rm
globals.html	19795	0644	edit dl rm
globals.json.gz	2525	0644	edit dl rm
globals.md	5838	0644	edit dl rm
http.html	164378	0644	edit dl rm
http.json.gz	25888	0644	edit dl rm
http.md	74465	0644	edit dl rm
http2.html	256451	0644	edit dl rm
http2.json.gz	37157	0644	edit dl rm
http2.md	121722	0644	edit dl rm
https.html	38345	0644	edit dl rm
https.json.gz	4847	0644	edit dl rm
https.md	13942	0644	edit dl rm
index.html	10087	0644	edit dl rm
index.json	54	0644	edit dl rm
index.md	1825	0644	edit dl rm
inspector.html	22433	0644	edit dl rm
inspector.json.gz	3338	0644	edit dl rm
inspector.md	6825	0644	edit dl rm
intl.html	23154	0644	edit dl rm
intl.json.gz	4038	0644	edit dl rm
intl.md	11092	0644	edit dl rm
module.html	21739	0644	edit dl rm
module.json.gz	2821	0644	edit dl rm
module.md	5341	0644	edit dl rm
modules.html	61333	0644	edit dl rm
modules.json.gz	11897	0644	edit dl rm
modules.md	30610	0644	edit dl rm
n-api.html	340382	0644	edit dl rm
n-api.json.gz	48682	0644	edit dl rm
n-api.md	206268	0644	edit dl rm
net.html	95113	0644	edit dl rm
net.json.gz	14265	0644	edit dl rm
net.md	40473	0644	edit dl rm
os.html	58658	0644	edit dl rm
os.json.gz	8576	0644	edit dl rm
os.md	34632	0644	edit dl rm
packages.html	65483	0644	edit dl rm
packages.json.gz	12401	0644	edit dl rm
packages.md	36538	0644	edit dl rm
path.html	39321	0644	edit dl rm
path.json.gz	4873	0644	edit dl rm
path.md	14750	0644	edit dl rm
perf_hooks.html	56215	0644	edit dl rm
perf_hooks.json.gz	6973	0644	edit dl rm
perf_hooks.md	20116	0644	edit dl rm
policy.html	15908	0644	edit dl rm
policy.json.gz	2908	0644	edit dl rm
policy.md	6324	0644	edit dl rm
process.html	169341	0644	edit dl rm
process.json.gz	27734	0644	edit dl rm
process.md	82162	0644	edit dl rm
punycode.html	16904	0644	edit dl rm
punycode.json.gz	1939	0644	edit dl rm
punycode.md	4063	0644	edit dl rm
querystring.html	19334	0644	edit dl rm
querystring.json.gz	2519	0644	edit dl rm
querystring.md	5423	0644	edit dl rm
readline.html	58434	0644	edit dl rm
readline.json.gz	8835	0644	edit dl rm
readline.md	25133	0644	edit dl rm
repl.html	54152	0644	edit dl rm
repl.json.gz	10053	0644	edit dl rm
repl.md	23754	0644	edit dl rm
report.html	44941	0644	edit dl rm
report.json.gz	6227	0644	edit dl rm
report.md	18287	0644	edit dl rm
stream.html	200501	0644	edit dl rm
stream.json.gz	34485	0644	edit dl rm
stream.md	98619	0644	edit dl rm
string_decoder.html	14415	0644	edit dl rm
string_decoder.json.gz	1545	0644	edit dl rm
string_decoder.md	2934	0644	edit dl rm
synopsis.html	11475	0644	edit dl rm
synopsis.json	3013	0644	edit dl rm
synopsis.md	2129	0644	edit dl rm
timers.html	27467	0644	edit dl rm
timers.json.gz	3637	0644	edit dl rm
timers.md	9738	0644	edit dl rm
tls.html	148381	0644	edit dl rm
tls.json.gz	29988	0644	edit dl rm
tls.md	81388	0644	edit dl rm
tracing.html	19586	0644	edit dl rm
tracing.json.gz	2829	0644	edit dl rm
tracing.md	6756	0644	edit dl rm
tty.html	26930	0644	edit dl rm
tty.json.gz	3758	0644	edit dl rm
tty.md	8989	0644	edit dl rm
url.html	97495	0644	edit dl rm
url.json.gz	13611	0644	edit dl rm
url.md	44869	0644	edit dl rm
util.html	178081	0644	edit dl rm
util.json.gz	20542	0644	edit dl rm
util.md	71255	0644	edit dl rm
v8.html	44688	0644	edit dl rm
v8.json.gz	6082	0644	edit dl rm
v8.md	15533	0644	edit dl rm
vm.html	103392	0644	edit dl rm
vm.json.gz	14023	0644	edit dl rm
vm.md	48293	0644	edit dl rm
wasi.html	17088	0644	edit dl rm
wasi.json.gz	2814	0644	edit dl rm
wasi.md	5932	0644	edit dl rm
worker_threads.html	70808	0644	edit dl rm
worker_threads.json.gz	11326	0644	edit dl rm
worker_threads.md	33883	0644	edit dl rm
zlib.html	90124	0644	edit dl rm
zlib.json.gz	10569	0644	edit dl rm
zlib.md	35697	0644	edit dl rm

Edit: /usr/share/doc/nodejs/api/embedding.md (8811B)

# C++ Embedder API

Node.js provides a number of C++ APIs that can be used to execute JavaScript
in a Node.js environment from other C++ software.

The documentation for these APIs can be found in [src/node.h][] in the Node.js
source tree. In addition to the APIs exposed by Node.js, some required concepts
are provided by the V8 embedder API.

Because using Node.js as an embedded library is different from writing code
that is executed by Node.js, breaking changes do not follow typical Node.js
[deprecation policy][] and may occur on each semver-major release without prior
warning.

## Example embedding application

The following sections will provide an overview over how to use these APIs
to create an application from scratch that will perform the equivalent of
`node -e <code>`, i.e. that will take a piece of JavaScript and run it in
a Node.js-specific environment.

The full code can be found [in the Node.js source tree][embedtest.cc].

### Setting up per-process state

Node.js requires some per-process state management in order to run:

* Arguments parsing for Node.js [CLI options][],
* V8 per-process requirements, such as a `v8::Platform` instance.

The following example shows how these can be set up. Some class names are from
the `node` and `v8` C++ namespaces, respectively.

```cpp
int main(int argc, char** argv) {
  argv = uv_setup_args(argc, argv);
  std::vector<std::string> args(argv, argv + argc);
  std::vector<std::string> exec_args;
  std::vector<std::string> errors;
  // Parse Node.js CLI options, and print any errors that have occurred while
  // trying to parse them.
  int exit_code = node::InitializeNodeWithArgs(&args, &exec_args, &errors);
  for (const std::string& error : errors)
    fprintf(stderr, "%s: %s\n", args[0].c_str(), error.c_str());
  if (exit_code != 0) {
    return exit_code;
  }

// Create a v8::Platform instance. `MultiIsolatePlatform::Create()` is a way
  // to create a v8::Platform instance that Node.js can use when creating
  // Worker threads. When no `MultiIsolatePlatform` instance is present,
  // Worker threads are disabled.
  std::unique_ptr<MultiIsolatePlatform> platform =
      MultiIsolatePlatform::Create(4);
  V8::InitializePlatform(platform.get());
  V8::Initialize();

// See below for the contents of this function.
  int ret = RunNodeInstance(platform.get(), args, exec_args);

V8::Dispose();
  V8::ShutdownPlatform();
  return ret;
}
```

### Per-instance state

Node.js has a concept of a “Node.js instance”, that is commonly being referred
to as `node::Environment`. Each `node::Environment` is associated with:

* Exactly one `v8::Isolate`, i.e. one JS Engine instance,
* Exactly one `uv_loop_t`, i.e. one event loop, and
* A number of `v8::Context`s, but exactly one main `v8::Context`.
* One `node::IsolateData` instance that contains information that could be
  shared by multiple `node::Environment`s that use the same `v8::Isolate`.
  Currently, no testing if performed for this scenario.

In order to set up a `v8::Isolate`, an `v8::ArrayBuffer::Allocator` needs
to be provided. One possible choice is the default Node.js allocator, which
can be created through `node::ArrayBufferAllocator::Create()`. Using the Node.js
allocator allows minor performance optimizations when addons use the Node.js
C++ `Buffer` API, and is required in order to track `ArrayBuffer` memory in
[`process.memoryUsage()`][].

Additionally, each `v8::Isolate` that is used for a Node.js instance needs to
be registered and unregistered with the `MultiIsolatePlatform` instance, if one
is being used, in order for the platform to know which event loop to use
for tasks scheduled by the `v8::Isolate`.

The `node::NewIsolate()` helper function creates a `v8::Isolate`,
sets it up with some Node.js-specific hooks (e.g. the Node.js error handler),
and registers it with the platform automatically.

```cpp
int RunNodeInstance(MultiIsolatePlatform* platform,
                    const std::vector<std::string>& args,
                    const std::vector<std::string>& exec_args) {
  int exit_code = 0;
  // Set up a libuv event loop.
  uv_loop_t loop;
  int ret = uv_loop_init(&loop);
  if (ret != 0) {
    fprintf(stderr, "%s: Failed to initialize loop: %s\n",
            args[0].c_str(),
            uv_err_name(ret));
    return 1;
  }

std::shared_ptr<ArrayBufferAllocator> allocator =
      ArrayBufferAllocator::Create();

Isolate* isolate = NewIsolate(allocator, &loop, platform);
  if (isolate == nullptr) {
    fprintf(stderr, "%s: Failed to initialize V8 Isolate\n", args[0].c_str());
    return 1;
  }

{
    Locker locker(isolate);
    Isolate::Scope isolate_scope(isolate);

// Create a node::IsolateData instance that will later be released using
    // node::FreeIsolateData().
    std::unique_ptr<IsolateData, decltype(&node::FreeIsolateData)> isolate_data(
        node::CreateIsolateData(isolate, &loop, platform, allocator.get()),
        node::FreeIsolateData);

// Set up a new v8::Context.
    HandleScope handle_scope(isolate);
    Local<Context> context = node::NewContext(isolate);
    if (context.IsEmpty()) {
      fprintf(stderr, "%s: Failed to initialize V8 Context\n", args[0].c_str());
      return 1;
    }

// The v8::Context needs to be entered when node::CreateEnvironment() and
    // node::LoadEnvironment() are being called.
    Context::Scope context_scope(context);

// Create a node::Environment instance that will later be released using
    // node::FreeEnvironment().
    std::unique_ptr<Environment, decltype(&node::FreeEnvironment)> env(
        node::CreateEnvironment(isolate_data.get(), context, args, exec_args),
        node::FreeEnvironment);

// Set up the Node.js instance for execution, and run code inside of it.
    // There is also a variant that takes a callback and provides it with
    // the `require` and `process` objects, so that it can manually compile
    // and run scripts as needed.
    // The `require` function inside this script does *not* access the file
    // system, and can only load built-in Node.js modules.
    // `module.createRequire()` is being used to create one that is able to
    // load files from the disk, and uses the standard CommonJS file loader
    // instead of the internal-only `require` function.
    MaybeLocal<Value> loadenv_ret = node::LoadEnvironment(
        env.get(),
        "const publicRequire ="
        "  require('module').createRequire(process.cwd() + '/');"
        "globalThis.require = publicRequire;"
        "require('vm').runInThisContext(process.argv[1]);");

if (loadenv_ret.IsEmpty())  // There has been a JS exception.
      return 1;

{
      // SealHandleScope protects against handle leaks from callbacks.
      SealHandleScope seal(isolate);
      bool more;
      do {
        uv_run(&loop, UV_RUN_DEFAULT);

// V8 tasks on background threads may end up scheduling new tasks in the
        // foreground, which in turn can keep the event loop going. For example,
        // WebAssembly.compile() may do so.
        platform->DrainTasks(isolate);

// If there are new tasks, continue.
        more = uv_loop_alive(&loop);
        if (more) continue;

// node::EmitBeforeExit() is used to emit the 'beforeExit' event on
        // the `process` object.
        node::EmitBeforeExit(env.get());

// 'beforeExit' can also schedule new work that keeps the event loop
        // running.
        more = uv_loop_alive(&loop);
      } while (more == true);
    }

// node::EmitExit() returns the current exit code.
    exit_code = node::EmitExit(env.get());

// node::Stop() can be used to explicitly stop the event loop and keep
    // further JavaScript from running. It can be called from any thread,
    // and will act like worker.terminate() if called from another thread.
    node::Stop(env.get());
  }

// Unregister the Isolate with the platform and add a listener that is called
  // when the Platform is done cleaning up any state it had associated with
  // the Isolate.
  bool platform_finished = false;
  platform->AddIsolateFinishedCallback(isolate, [](void* data) {
    *static_cast<bool*>(data) = true;
  }, &platform_finished);
  platform->UnregisterIsolate(isolate);
  isolate->Dispose();

// Wait until the platform has cleaned up all relevant resources.
  while (!platform_finished)
    uv_run(&loop, UV_RUN_ONCE);
  int err = uv_loop_close(&loop);
  assert(err == 0);

return exit_code;
}
```

[`process.memoryUsage()`]: process.html#process_process_memoryusage
[CLI options]: cli.html
[deprecation policy]: deprecations.html
[embedtest.cc]: https://github.com/nodejs/node/blob/master/test/embedding/embedtest.cc
[src/node.h]: https://github.com/nodejs/node/blob/master/src/node.h

cmd: