C++ 임베더 API

Node.js는 다른 C++ 소프트웨어에서 Node.js 환경에서 JavaScript를 실행하는 데 사용할 수 있는 여러 C++ API를 제공합니다.

이러한 API에 대한 설명서는 Node.js 소스 트리의 src/node.h에서 찾을 수 있습니다. Node.js에서 제공하는 API 외에도 V8 임베더 API에서 일부 필수 개념이 제공됩니다.

Node.js를 임베디드 라이브러리로 사용하는 것은 Node.js에서 실행되는 코드를 작성하는 것과 다르기 때문에, 주요 변경 사항은 일반적인 Node.js deprecated 정책을 따르지 않으며 사전 경고 없이 각 semver 주요 릴리스에서 발생할 수 있습니다.

예시 임베딩 애플리케이션

다음 섹션에서는 이러한 API를 사용하여 node -e <코드>와 동등한 작업을 수행하는 애플리케이션(즉, JavaScript 코드를 가져와 Node.js 관련 환경에서 실행하는 애플리케이션)을 처음부터 만드는 방법에 대한 개요를 제공합니다.

전체 코드는 Node.js 소스 트리에서 찾을 수 있습니다.

프로세스별 상태 설정

Node.js를 실행하려면 일부 프로세스별 상태 관리가 필요합니다.

• Node.js CLI 옵션에 대한 인수 구문 분석
• v8::Platform 인스턴스와 같은 V8 프로세스별 요구 사항

다음 예시는 이러한 설정 방법을 보여줍니다. 일부 클래스 이름은 각각 node 및 v8 C++ 네임스페이스의 것입니다.

int main(int argc, char** argv) {
  argv = uv_setup_args(argc, argv);
  std::vector<std::string> args(argv, argv + argc);
  // Node.js CLI 옵션을 구문 분석하고, 구문 분석하는 동안 발생한 오류를 출력합니다.
  std::unique_ptr<node::InitializationResult> result =
      node::InitializeOncePerProcess(args, {
        node::ProcessInitializationFlags::kNoInitializeV8,
        node::ProcessInitializationFlags::kNoInitializeNodeV8Platform
      });

  for (const std::string& error : result->errors())
    fprintf(stderr, "%s: %s\n", args[0].c_str(), error.c_str());
  if (result->early_return() != 0) {
    return result->exit_code();
  }

  // v8::Platform 인스턴스를 생성합니다. `MultiIsolatePlatform::Create()`는 Worker 스레드를 생성할 때 Node.js가 사용할 수 있는 v8::Platform 인스턴스를 생성하는 방법입니다. `MultiIsolatePlatform` 인스턴스가 없으면 Worker 스레드가 비활성화됩니다.
  std::unique_ptr<MultiIsolatePlatform> platform =
      MultiIsolatePlatform::Create(4);
  V8::InitializePlatform(platform.get());
  V8::Initialize();

  // 이 함수의 내용은 아래에 설명되어 있습니다.
  int ret = RunNodeInstance(
      platform.get(), result->args(), result->exec_args());

  V8::Dispose();
  V8::DisposePlatform();

  node::TearDownOncePerProcess();
  return ret;
}

인스턴스별 상태 설정

[히스토리]

버전	변경 사항
v15.0.0	CommonEnvironmentSetup 및 SpinEventLoop 유틸리티 추가

Node.js에는 일반적으로 node::Environment로 불리는 "Node.js 인스턴스"라는 개념이 있습니다. 각 node::Environment는 다음과 연관됩니다.

• 정확히 하나의 v8::Isolate(즉, 하나의 JS 엔진 인스턴스),
• 정확히 하나의 uv_loop_t(즉, 하나의 이벤트 루프),
• 여러 개의 v8::Context이지만 정확히 하나의 주 v8::Context, 그리고
• 여러 node::Environment에서 공유될 수 있는 정보를 포함하는 하나의 node::IsolateData 인스턴스. 임베더는 node::IsolateData가 동일한 v8::Isolate를 사용하는 node::Environment에서만 공유되도록 해야 하며, Node.js는 이 확인을 수행하지 않습니다.

v8::Isolate를 설정하려면 v8::ArrayBuffer::Allocator를 제공해야 합니다. 한 가지 가능한 선택은 node::ArrayBufferAllocator::Create()를 통해 생성할 수 있는 기본 Node.js 할당자입니다. Node.js 할당자를 사용하면 애드온이 Node.js C++ Buffer API를 사용할 때 성능을 약간 최적화할 수 있으며 process.memoryUsage()에서 ArrayBuffer 메모리를 추적하는 데 필요합니다.

또한, Node.js 인스턴스에 사용되는 각 v8::Isolate는 플랫폼이 v8::Isolate에서 예약된 작업에 사용할 이벤트 루프를 알 수 있도록 MultiIsolatePlatform 인스턴스에 등록 및 등록 취소해야 합니다(사용 중인 경우).

node::NewIsolate() 도우미 함수는 v8::Isolate를 생성하고, 일부 Node.js 관련 후크(예: Node.js 오류 처리기)로 설정하고, 플랫폼에 자동으로 등록합니다.

int RunNodeInstance(MultiIsolatePlatform* platform,
                    const std::vector<std::string>& args,
                    const std::vector<std::string>& exec_args) {
  int exit_code = 0;

  // libuv 이벤트 루프, v8::Isolate 및 Node.js 환경 설정
  std::vector<std::string> errors;
  std::unique_ptr<CommonEnvironmentSetup> setup =
      CommonEnvironmentSetup::Create(platform, &errors, args, exec_args);
  if (!setup) {
    for (const std::string& err : errors)
      fprintf(stderr, "%s: %s\n", args[0].c_str(), err.c_str());
    return 1;
  }

  Isolate* isolate = setup->isolate();
  Environment* env = setup->env();

  {
    Locker locker(isolate);
    Isolate::Scope isolate_scope(isolate);
    HandleScope handle_scope(isolate);
    // `node::CreateEnvironment()` 및 `node::LoadEnvironment()`를 호출할 때 v8::Context에 들어가야 합니다.
    Context::Scope context_scope(setup->context());

    // 실행을 위해 Node.js 인스턴스를 설정하고 그 안에서 코드를 실행합니다.
    // 콜백을 받고 `require` 및 `process` 객체를 제공하는 변형도 있어서 필요에 따라 스크립트를 수동으로 컴파일하고 실행할 수 있습니다.
    // 이 스크립트 내의 `require` 함수는 파일 시스템에 액세스하지 않으며 내장 Node.js 모듈만 로드할 수 있습니다.
    // `module.createRequire()`는 디스크에서 파일을 로드하고 내부 전용 `require` 함수 대신 표준 CommonJS 파일 로더를 사용하는 것을 생성하는 데 사용됩니다.
    MaybeLocal<Value> loadenv_ret = node::LoadEnvironment(
        env,
        "const publicRequire ="
        "  require('node:module').createRequire(process.cwd() + '/');"
        "globalThis.require = publicRequire;"
        "require('node:vm').runInThisContext(process.argv[1]);");

    if (loadenv_ret.IsEmpty())  // JS 예외 발생
      return 1;

    exit_code = node::SpinEventLoop(env).FromMaybe(1);

    // `node::Stop()`은 이벤트 루프를 명시적으로 중지하고 더 이상의 JavaScript 실행을 방지하는 데 사용할 수 있습니다. 어떤 스레드에서든 호출할 수 있으며 다른 스레드에서 호출하면 `worker.terminate()`와 같이 작동합니다.
    node::Stop(env);
  }

  return exit_code;
}