{
  "type": "module",
  "source": "doc/api/embedding.md",
  "modules": [
    {
      "textRaw": "C++ embedder API",
      "name": "c++_embedder_api",
      "introduced_in": "v12.19.0",
      "desc": "<p>Node.js provides a number of C++ APIs that can be used to execute JavaScript\nin a Node.js environment from other C++ software.</p>\n<p>The documentation for these APIs can be found in <a href=\"https://github.com/nodejs/node/blob/HEAD/src/node.h\">src/node.h</a> in the Node.js\nsource tree. In addition to the APIs exposed by Node.js, some required concepts\nare provided by the V8 embedder API.</p>\n<p>Because using Node.js as an embedded library is different from writing code\nthat is executed by Node.js, breaking changes do not follow typical Node.js\n<a href=\"deprecations.html\">deprecation policy</a> and may occur on each semver-major release without prior\nwarning.</p>\n<h2>Example embedding application</h2>\n<p>The following sections will provide an overview over how to use these APIs\nto create an application from scratch that will perform the equivalent of\n<code>node -e &#x3C;code></code>, i.e. that will take a piece of JavaScript and run it in\na Node.js-specific environment.</p>\n<p>The full code can be found <a href=\"https://github.com/nodejs/node/blob/HEAD/test/embedding/embedtest.cc\">in the Node.js source tree</a>.</p>",
      "modules": [
        {
          "textRaw": "Setting up per-process state",
          "name": "setting_up_per-process_state",
          "desc": "<p>Node.js requires some per-process state management in order to run:</p>\n<ul>\n<li>Arguments parsing for Node.js <a href=\"cli.html\">CLI options</a>,</li>\n<li>V8 per-process requirements, such as a <code>v8::Platform</code> instance.</li>\n</ul>\n<p>The following example shows how these can be set up. Some class names are from\nthe <code>node</code> and <code>v8</code> C++ namespaces, respectively.</p>\n<pre><code class=\"language-cpp\">int main(int argc, char** argv) {\n  argv = uv_setup_args(argc, argv);\n  std::vector&#x3C;std::string> args(argv, argv + argc);\n  std::vector&#x3C;std::string> exec_args;\n  std::vector&#x3C;std::string> errors;\n  // Parse Node.js CLI options, and print any errors that have occurred while\n  // trying to parse them.\n  int exit_code = node::InitializeNodeWithArgs(&#x26;args, &#x26;exec_args, &#x26;errors);\n  for (const std::string&#x26; error : errors)\n    fprintf(stderr, \"%s: %s\\n\", args[0].c_str(), error.c_str());\n  if (exit_code != 0) {\n    return exit_code;\n  }\n\n  // Create a v8::Platform instance. `MultiIsolatePlatform::Create()` is a way\n  // to create a v8::Platform instance that Node.js can use when creating\n  // Worker threads. When no `MultiIsolatePlatform` instance is present,\n  // Worker threads are disabled.\n  std::unique_ptr&#x3C;MultiIsolatePlatform> platform =\n      MultiIsolatePlatform::Create(4);\n  V8::InitializePlatform(platform.get());\n  V8::Initialize();\n\n  // See below for the contents of this function.\n  int ret = RunNodeInstance(platform.get(), args, exec_args);\n\n  V8::Dispose();\n  V8::ShutdownPlatform();\n  return ret;\n}\n</code></pre>",
          "type": "module",
          "displayName": "Setting up per-process state"
        },
        {
          "textRaw": "Per-instance state",
          "name": "per-instance_state",
          "meta": {
            "changes": [
              {
                "version": "v15.0.0",
                "pr-url": "https://github.com/nodejs/node/pull/35597",
                "description": "The `CommonEnvironmentSetup` and `SpinEventLoop` utilities were added."
              }
            ]
          },
          "desc": "<p>Node.js has a concept of a “Node.js instance”, that is commonly being referred\nto as <code>node::Environment</code>. Each <code>node::Environment</code> is associated with:</p>\n<ul>\n<li>Exactly one <code>v8::Isolate</code>, i.e. one JS Engine instance,</li>\n<li>Exactly one <code>uv_loop_t</code>, i.e. one event loop, and</li>\n<li>A number of <code>v8::Context</code>s, but exactly one main <code>v8::Context</code>.</li>\n<li>One <code>node::IsolateData</code> instance that contains information that could be\nshared by multiple <code>node::Environment</code>s that use the same <code>v8::Isolate</code>.\nCurrently, no testing if performed for this scenario.</li>\n</ul>\n<p>In order to set up a <code>v8::Isolate</code>, an <code>v8::ArrayBuffer::Allocator</code> needs\nto be provided. One possible choice is the default Node.js allocator, which\ncan be created through <code>node::ArrayBufferAllocator::Create()</code>. Using the Node.js\nallocator allows minor performance optimizations when addons use the Node.js\nC++ <code>Buffer</code> API, and is required in order to track <code>ArrayBuffer</code> memory in\n<a href=\"process.html#process_process_memoryusage\"><code>process.memoryUsage()</code></a>.</p>\n<p>Additionally, each <code>v8::Isolate</code> that is used for a Node.js instance needs to\nbe registered and unregistered with the <code>MultiIsolatePlatform</code> instance, if one\nis being used, in order for the platform to know which event loop to use\nfor tasks scheduled by the <code>v8::Isolate</code>.</p>\n<p>The <code>node::NewIsolate()</code> helper function creates a <code>v8::Isolate</code>,\nsets it up with some Node.js-specific hooks (e.g. the Node.js error handler),\nand registers it with the platform automatically.</p>\n<pre><code class=\"language-cpp\">int RunNodeInstance(MultiIsolatePlatform* platform,\n                    const std::vector&#x3C;std::string>&#x26; args,\n                    const std::vector&#x3C;std::string>&#x26; exec_args) {\n  int exit_code = 0;\n\n  // Setup up a libuv event loop, v8::Isolate, and Node.js Environment.\n  std::vector&#x3C;std::string> errors;\n  std::unique_ptr&#x3C;CommonEnvironmentSetup> setup =\n      CommonEnvironmentSetup::Create(platform, &#x26;errors, args, exec_args);\n  if (!setup) {\n    for (const std::string&#x26; err : errors)\n      fprintf(stderr, \"%s: %s\\n\", args[0].c_str(), err.c_str());\n    return 1;\n  }\n\n  Isolate* isolate = setup->isolate();\n  Environment* env = setup->env();\n\n  {\n    Locker locker(isolate);\n    Isolate::Scope isolate_scope(isolate);\n    // The v8::Context needs to be entered when node::CreateEnvironment() and\n    // node::LoadEnvironment() are being called.\n    Context::Scope context_scope(setup->context());\n\n    // Set up the Node.js instance for execution, and run code inside of it.\n    // There is also a variant that takes a callback and provides it with\n    // the `require` and `process` objects, so that it can manually compile\n    // and run scripts as needed.\n    // The `require` function inside this script does *not* access the file\n    // system, and can only load built-in Node.js modules.\n    // `module.createRequire()` is being used to create one that is able to\n    // load files from the disk, and uses the standard CommonJS file loader\n    // instead of the internal-only `require` function.\n    MaybeLocal&#x3C;Value> loadenv_ret = node::LoadEnvironment(\n        env,\n        \"const publicRequire =\"\n        \"  require('module').createRequire(process.cwd() + '/');\"\n        \"globalThis.require = publicRequire;\"\n        \"require('vm').runInThisContext(process.argv[1]);\");\n\n    if (loadenv_ret.IsEmpty())  // There has been a JS exception.\n      return 1;\n\n    exit_code = node::SpinEventLoop(env).FromMaybe(1);\n\n    // node::Stop() can be used to explicitly stop the event loop and keep\n    // further JavaScript from running. It can be called from any thread,\n    // and will act like worker.terminate() if called from another thread.\n    node::Stop(env);\n  }\n\n  return exit_code;\n}\n</code></pre>",
          "type": "module",
          "displayName": "Per-instance state"
        }
      ],
      "type": "module",
      "displayName": "C++ embedder API"
    }
  ]
}