Node-API
[Stable: 2 - Stable]
Stable: 2 Stability: 2 - Stable
Node-API(이전 N-API)는 네이티브 애드온을 구축하기 위한 API입니다. 기본 JavaScript 런타임(예: V8)과 독립적이며 Node.js 자체의 일부로 유지 관리됩니다. 이 API는 Node.js 버전 간에 Application Binary Interface(ABI) 안정성을 유지합니다. 기본 JavaScript 엔진의 변경으로부터 애드온을 보호하고 하나의 주요 버전에 대해 컴파일된 모듈을 재컴파일하지 않고도 나중 주요 버전의 Node.js에서 실행할 수 있도록 하기 위한 것입니다. ABI 안정성 가이드는 더 자세한 설명을 제공합니다.
애드온은 C++ 애드온 섹션에 설명된 것과 같은 방식/도구로 빌드/패키징됩니다. 유일한 차이점은 네이티브 코드에서 사용하는 API 집합입니다. V8 또는 Node.js용 네이티브 추상화 API를 사용하는 대신 Node-API에서 사용 가능한 함수를 사용합니다.
Node-API에서 노출하는 API는 일반적으로 JavaScript 값을 생성하고 조작하는 데 사용됩니다. 개념 및 작업은 일반적으로 ECMA-262 언어 사양에 지정된 아이디어에 매핑됩니다. API는 다음과 같은 속성을 가지고 있습니다.
- 모든 Node-API 호출은
napi_status
유형의 상태 코드를 반환합니다. 이 상태는 API 호출이 성공했는지 또는 실패했는지 나타냅니다. - API의 반환 값은 출력 매개 변수를 통해 전달됩니다.
- 모든 JavaScript 값은
napi_value
라는 불투명 유형 뒤에 추상화됩니다. - 오류 상태 코드의 경우
napi_get_last_error_info
를 사용하여 추가 정보를 얻을 수 있습니다. 자세한 내용은 오류 처리 섹션 오류 처리에서 확인할 수 있습니다.
Node-API는 Node.js 버전과 다양한 컴파일러 수준에서 ABI 안정성을 보장하는 C API입니다. C++ API는 사용하기가 더 쉬울 수 있습니다. C++ 사용을 지원하기 위해 프로젝트는 node-addon-api
라는 C++ 래퍼 모듈을 유지 관리합니다. 이 래퍼는 인라인 가능한 C++ API를 제공합니다. node-addon-api
로 빌드된 바이너리는 Node.js에서 내보낸 Node-API C 기반 함수에 대한 심볼에 종속됩니다. node-addon-api
는 Node-API를 호출하는 코드를 작성하는 더 효율적인 방법입니다. 예를 들어 다음 node-addon-api
코드를 살펴보겠습니다. 첫 번째 섹션은 node-addon-api
코드를 보여주고 두 번째 섹션은 애드온에서 실제로 사용되는 것을 보여줍니다.
Object obj = Object::New(env);
obj["foo"] = String::New(env, "bar");
napi_status status;
napi_value object, string;
status = napi_create_object(env, &object);
if (status != napi_ok) {
napi_throw_error(env, ...);
return;
}
status = napi_create_string_utf8(env, "bar", NAPI_AUTO_LENGTH, &string);
if (status != napi_ok) {
napi_throw_error(env, ...);
return;
}
status = napi_set_named_property(env, object, "foo", string);
if (status != napi_ok) {
napi_throw_error(env, ...);
return;
}
최종 결과는 애드온이 내보낸 C API만 사용한다는 것입니다. 결과적으로 C API가 제공하는 ABI 안정성의 이점을 여전히 얻을 수 있습니다.
C API 대신 node-addon-api
를 사용하는 경우 node-addon-api
에 대한 API docs부터 시작하십시오.
Node-API 리소스는 Node-API 및 node-addon-api
를 처음 접하는 개발자에게 훌륭한 방향과 팁을 제공합니다. 추가 미디어 리소스는 Node-API 미디어 페이지에서 찾을 수 있습니다.
ABI 안정성의 의미
Node-API는 ABI 안정성을 보장하지만, Node.js의 다른 부분과 애드온에서 사용되는 외부 라이브러리는 그렇지 않습니다. 특히, 다음 API 중 어느 것도 주요 버전 간에 ABI 안정성을 보장하지 않습니다.
- 다음을 통해 사용 가능한 Node.js C++ API
- Node.js에도 포함되어 있으며 다음을 통해 사용 가능한 libuv API
- 다음을 통해 사용 가능한 V8 API
따라서 애드온이 Node.js 주요 버전에서 ABI 호환성을 유지하려면,
#include <node_api.h>
를 사용하여 Node-API만을 독점적으로 사용하고, 사용하는 모든 외부 라이브러리에 대해 해당 외부 라이브러리가 Node-API와 유사한 ABI 안정성을 보장하는지 확인해야 합니다.
빌드
JavaScript로 작성된 모듈과 달리 Node-API를 사용하여 Node.js 네이티브 애드온을 개발하고 배포하려면 추가 도구 세트가 필요합니다. Node.js 개발에 필요한 기본 도구 외에도 네이티브 애드온 개발자는 C 및 C++ 코드를 바이너리로 컴파일할 수 있는 툴체인이 필요합니다. 또한, 네이티브 애드온의 배포 방법에 따라 네이티브 애드온의 사용자도 C/C++ 툴체인을 설치해야 합니다.
Linux 개발자의 경우 필요한 C/C++ 툴체인 패키지를 쉽게 사용할 수 있습니다. GCC는 다양한 플랫폼에서 Node.js를 빌드하고 테스트하는 데 Node.js 커뮤니티에서 널리 사용됩니다. 많은 개발자에게 LLVM 컴파일러 인프라도 좋은 선택입니다.
Mac 개발자의 경우 Xcode는 필요한 모든 컴파일러 도구를 제공합니다. 하지만 전체 Xcode IDE를 설치할 필요는 없습니다. 다음 명령어는 필요한 툴체인을 설치합니다.
xcode-select --install
Windows 개발자의 경우 Visual Studio는 필요한 모든 컴파일러 도구를 제공합니다. 하지만 전체 Visual Studio IDE를 설치할 필요는 없습니다. 다음 명령어는 필요한 툴체인을 설치합니다.
npm install --global windows-build-tools
다음 섹션에서는 Node.js 네이티브 애드온 개발 및 배포에 사용할 수 있는 추가 도구에 대해 설명합니다.
빌드 도구
여기에 나열된 두 도구 모두 네이티브 애드온을 성공적으로 설치하려면 네이티브 애드온의 사용자가 C/C++ 툴체인을 설치해야 합니다.
node-gyp
node-gyp는 Google의 GYP 도구의 gyp-next 포크를 기반으로 하는 빌드 시스템이며 npm에 번들로 포함되어 있습니다. GYP, 따라서 node-gyp는 Python이 설치되어 있어야 합니다.
역사적으로 node-gyp는 네이티브 애드온을 빌드하기 위한 선택 도구였습니다. 널리 채택되고 문서화되어 있습니다. 그러나 일부 개발자는 node-gyp의 한계에 직면했습니다.
CMake.js
CMake.js는 CMake를 기반으로 하는 대체 빌드 시스템입니다.
CMake.js는 이미 CMake를 사용하는 프로젝트 또는 node-gyp의 한계에 영향을 받는 개발자에게 좋은 선택입니다. build_with_cmake
는 CMake 기반 네이티브 애드온 프로젝트의 예입니다.
사전 컴파일된 바이너리 업로드
여기에 나열된 세 가지 도구를 통해 네이티브 애드온 개발자와 관리자는 바이너리를 공용 또는 비공개 서버에 생성하고 업로드할 수 있습니다. 이러한 도구는 일반적으로 Travis CI 및 AppVeyor와 같은 CI/CD 빌드 시스템과 통합되어 다양한 플랫폼과 아키텍처에 대한 바이너리를 빌드하고 업로드합니다. 그러면 C/C++ 툴체인을 설치할 필요가 없는 사용자가 이러한 바이너리를 다운로드할 수 있습니다.
node-pre-gyp
node-pre-gyp는 개발자가 선택한 서버에 바이너리를 업로드하는 기능을 추가하는 node-gyp 기반 도구입니다. node-pre-gyp는 Amazon S3에 바이너리를 업로드하는 기능을 특히 잘 지원합니다.
prebuild
prebuild는 node-gyp 또는 CMake.js를 사용한 빌드를 지원하는 도구입니다. 다양한 서버를 지원하는 node-pre-gyp와 달리 prebuild는 GitHub 릴리스에만 바이너리를 업로드합니다. prebuild는 CMake.js를 사용하는 GitHub 프로젝트에 좋은 선택입니다.
prebuildify
prebuildify는 node-gyp 기반의 도구입니다. prebuildify의 장점은 빌드된 바이너리가 npm에 업로드될 때 네이티브 애드온과 함께 번들로 제공된다는 것입니다. 바이너리는 npm에서 다운로드되며, 네이티브 애드온이 설치될 때 모듈 사용자에게 즉시 사용 가능합니다.
사용법
Node-API 함수를 사용하려면 node 개발 트리의 src 디렉토리에 있는 node_api.h
파일을 포함합니다.
#include <node_api.h>
이렇게 하면 지정된 Node.js 릴리스에 대한 기본 NAPI_VERSION
을 사용하게 됩니다. 특정 버전의 Node-API와의 호환성을 보장하려면 헤더를 포함할 때 버전을 명시적으로 지정할 수 있습니다.
#define NAPI_VERSION 3
#include <node_api.h>
이렇게 하면 Node-API 표면이 지정된(이전) 버전에서 사용 가능한 기능으로만 제한됩니다.
Node-API 표면의 일부는 실험적이며 명시적인 옵트인이 필요합니다.
#define NAPI_EXPERIMENTAL
#include <node_api.h>
이 경우 실험적 API를 포함한 전체 API 표면을 모듈 코드에서 사용할 수 있습니다.
때때로 이미 출시된 안정적인 API에 영향을 미치는 실험적 기능이 도입됩니다. 이러한 기능은 옵트아웃으로 비활성화할 수 있습니다.
#define NAPI_EXPERIMENTAL
#define NODE_API_EXPERIMENTAL_<FEATURE_NAME>_OPT_OUT
#include <node_api.h>
여기서 <FEATURE_NAME>
은 실험적 및 안정적인 API 모두에 영향을 미치는 실험적 기능의 이름입니다.
Node-API 버전 매트릭스
9 버전까지 Node-API 버전은 Node.js와 독립적으로 추가되고 버전이 지정되었습니다. 즉, 모든 버전은 이전 버전의 모든 API에 몇 가지 추가 기능이 있는 이전 버전에 대한 확장이었습니다. 각 Node.js 버전은 단일 Node-API 버전만 지원했습니다. 예를 들어 v18.15.0은 Node-API 버전 8만 지원합니다. 8은 이전 모든 버전의 엄격한 상위 집합이었기 때문에 ABI 안정성이 달성되었습니다.
9 버전부터 Node-API 버전은 독립적으로 버전이 지정되지만 Node-API 버전 9에서 실행된 애드온은 Node-API 버전 10에서 실행하려면 코드 업데이트가 필요할 수 있습니다. 그러나 Node.js 버전이 8보다 높은 Node-API 버전을 지원하는 경우 8과 지원하는 최고 버전 사이의 모든 버전을 지원하고 애드온이 더 높은 Node-API 버전을 선택하지 않는 한 버전 8 API를 제공하도록 기본 설정되므로 ABI 안정성이 유지됩니다. 이 방법은 기존 Node-API 함수를 더 잘 최적화하면서 ABI 안정성을 유지할 수 있는 유연성을 제공합니다. 기존 애드온은 이전 버전의 Node-API를 사용하여 재컴파일하지 않고도 계속 실행할 수 있습니다. 애드온에 최신 Node-API 버전의 기능이 필요한 경우 기존 코드를 변경하고 재컴파일하여 해당 새 기능을 사용해야 합니다.
Node-API 버전 9 이상을 지원하는 Node.js 버전에서 NAPI_VERSION=X
를 정의하고 기존 애드온 초기화 매크로를 사용하면 요청된 Node-API 버전이 런타임에 애드온에 통합됩니다. NAPI_VERSION
이 설정되지 않으면 8로 기본 설정됩니다.
이 표는 이전 스트림에서는 최신 정보가 아닐 수 있습니다. 최신 정보는 최신 API 설명서에 있습니다: Node-API 버전 매트릭스
Node-API 버전 | 지원 버전 |
---|---|
9 | v18.17.0+, 20.3.0+, 21.0.0 및 모든 이후 버전 |
8 | v12.22.0+, v14.17.0+, v15.12.0+, 16.0.0 및 모든 이후 버전 |
7 | v10.23.0+, v12.19.0+, v14.12.0+, 15.0.0 및 모든 이후 버전 |
6 | v10.20.0+, v12.17.0+, 14.0.0 및 모든 이후 버전 |
5 | v10.17.0+, v12.11.0+, 13.0.0 및 모든 이후 버전 |
4 | v10.16.0+, v11.8.0+, 12.0.0 및 모든 이후 버전 |
3 | v6.14.2*, 8.11.2+, v9.11.0+*, 10.0.0 및 모든 이후 버전 |
2 | v8.10.0+, v9.3.0+, 10.0.0 및 모든 이후 버전 |
1 | v8.6.0+*, v9.0.0+, 10.0.0 및 모든 이후 버전 |
- Node-API는 실험적이었습니다.
** Node.js 8.0.0은 Node-API를 실험적 기능으로 포함했습니다. Node-API 버전 1로 출시되었지만 Node.js 8.6.0까지 계속 발전했습니다. Node.js 8.6.0 이전 버전의 API는 다릅니다. Node-API 버전 3 이상을 권장합니다.
Node-API에 대해 설명된 각 API에는 추가됨:
, 안정적인 API에는 추가 헤더 Node-API 버전:
이 있습니다. Node-API 버전:
에 표시된 Node.js 버전 이상을 사용하는 경우 API를 직접 사용할 수 있습니다. Node-API 버전:
에 나열된 버전을 지원하지 않는 Node.js 버전을 사용하거나 Node-API 버전:
이 나열되지 않은 경우 #define NAPI_EXPERIMENTAL
이 node_api.h
또는 js_native_api.h
포함 전에 오는 경우에만 API를 사용할 수 있습니다. 추가됨:
에 표시된 버전보다 나중 버전의 Node.js에서 API를 사용할 수 없는 것으로 나타나는 경우 이것이 그 이유일 가능성이 큽니다.
네이티브 코드에서 ECMAScript 기능에 액세스하는 것과 엄격하게 관련된 Node-API는 js_native_api.h
및 js_native_api_types.h
에서 별도로 찾을 수 있습니다. 이러한 헤더에 정의된 API는 node_api.h
및 node_api_types.h
에 포함됩니다. 이러한 방식으로 헤더가 구성되는 것은 Node.js 외부에서 Node-API를 구현할 수 있도록 하기 위한 것입니다. 이러한 구현의 경우 Node.js 특정 API가 적용되지 않을 수 있습니다.
애드온의 Node.js 특정 부분은 실제 기능을 JavaScript 환경에 노출하는 코드와 분리할 수 있으므로 후자를 여러 Node-API 구현과 함께 사용할 수 있습니다. 아래 예에서 addon.c
및 addon.h
는 js_native_api.h
만 참조합니다. 이렇게 하면 addon.c
를 재사용하여 Node.js 구현의 Node-API 또는 Node.js 외부의 Node-API 구현을 컴파일할 수 있습니다.
addon_node.c
는 애드온에 대한 Node.js 특정 진입점을 포함하고 애드온이 Node.js 환경에 로드될 때 addon.c
를 호출하여 애드온을 인스턴스화하는 별도의 파일입니다.
// addon.h
#ifndef _ADDON_H_
#define _ADDON_H_
#include <js_native_api.h>
napi_value create_addon(napi_env env);
#endif // _ADDON_H_
// addon.c
#include "addon.h"
#define NODE_API_CALL(env, call) \
do { \
napi_status status = (call); \
if (status != napi_ok) { \
const napi_extended_error_info* error_info = NULL; \
napi_get_last_error_info((env), &error_info); \
const char* err_message = error_info->error_message; \
bool is_pending; \
napi_is_exception_pending((env), &is_pending); \
/* If an exception is already pending, don't rethrow it */ \
if (!is_pending) { \
const char* message = (err_message == NULL) \
? "empty error message" \
: err_message; \
napi_throw_error((env), NULL, message); \
} \
return NULL; \
} \
} while(0)
static napi_value
DoSomethingUseful(napi_env env, napi_callback_info info) {
// Do something useful.
return NULL;
}
napi_value create_addon(napi_env env) {
napi_value result;
NODE_API_CALL(env, napi_create_object(env, &result));
napi_value exported_function;
NODE_API_CALL(env, napi_create_function(env,
"doSomethingUseful",
NAPI_AUTO_LENGTH,
DoSomethingUseful,
NULL,
&exported_function));
NODE_API_CALL(env, napi_set_named_property(env,
result,
"doSomethingUseful",
exported_function));
return result;
}
// addon_node.c
#include <node_api.h>
#include "addon.h"
NAPI_MODULE_INIT(/* napi_env env, napi_value exports */) {
// This function body is expected to return a `napi_value`.
// The variables `napi_env env` and `napi_value exports` may be used within
// the body, as they are provided by the definition of `NAPI_MODULE_INIT()`.
return create_addon(env);
}
환경 수명 주기 API
8.7절의 ECMAScript 언어 명세는 JavaScript 코드가 실행되는 자체 포함 환경인 "Agent" 개념을 정의합니다. 프로세스에 의해 여러 개의 이러한 Agent가 동시에 또는 순차적으로 시작되고 종료될 수 있습니다.
Node.js 환경은 ECMAScript Agent에 해당합니다. 메인 프로세스에서 환경은 시작 시 생성되며, 별도의 스레드에서 추가 환경을 생성하여 워커 스레드로 사용할 수 있습니다. Node.js가 다른 애플리케이션에 포함된 경우 애플리케이션의 메인 스레드는 애플리케이션 프로세스의 수명 주기 동안 여러 번 Node.js 환경을 생성하고 파괴할 수도 있습니다. 애플리케이션에 의해 생성된 각 Node.js 환경은 수명 주기 동안 워커 스레드로 추가 환경을 생성하고 파괴할 수 있습니다.
네이티브 애드온의 관점에서 보면, 이는 제공하는 바인딩이 여러 번, 여러 컨텍스트에서, 심지어 여러 스레드에서 동시에 호출될 수 있음을 의미합니다.
네이티브 애드온은 Node.js 환경의 수명 주기 동안 사용하는 전역 상태를 할당해야 할 수 있습니다. 이를 통해 상태를 애드온의 각 인스턴스에 고유하게 만들 수 있습니다.
이를 위해 Node-API는 데이터를 연결하여 해당 수명 주기가 Node.js 환경의 수명 주기에 연결되도록 하는 방법을 제공합니다.
napi_set_instance_data
추가됨: v12.8.0, v10.20.0
N-API 버전: 6
napi_status napi_set_instance_data(node_api_basic_env env,
void* data,
napi_finalize finalize_cb,
void* finalize_hint);
[in] env
: Node-API 호출이 실행되는 환경입니다.[in] data
: 이 인스턴스의 바인딩에서 사용할 수 있도록 할 데이터 항목입니다.[in] finalize_cb
: 환경이 해체될 때 호출할 함수입니다. 함수는data
를 수신하여 해제할 수 있습니다.napi_finalize
에서 자세한 내용을 제공합니다.[in] finalize_hint
: 수집 중에 finalize 콜백에 전달할 선택적 힌트입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 data
를 현재 실행 중인 Node.js 환경과 연결합니다. data
는 나중에 napi_get_instance_data()
를 사용하여 검색할 수 있습니다. 이전에 napi_set_instance_data()
호출을 통해 설정된 현재 실행 중인 Node.js 환경과 연결된 기존 데이터는 덮어쓰여집니다. 이전 호출에서 finalize_cb
가 제공된 경우 호출되지 않습니다.
napi_get_instance_data
추가됨: v12.8.0, v10.20.0
N-API 버전: 6
napi_status napi_get_instance_data(node_api_basic_env env,
void** data);
[in] env
: Node-API 호출이 수행되는 환경입니다.[out] data
:napi_set_instance_data()
호출을 통해 현재 실행 중인 Node.js 환경에 이전에 연결된 데이터 항목입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 napi_set_instance_data()
를 통해 이전에 현재 실행 중인 Node.js 환경에 연결된 데이터를 검색합니다. 데이터가 설정되지 않은 경우 호출은 성공하고 data
는 NULL
로 설정됩니다.
기본 Node-API 데이터 형식
Node-API는 다양한 API에서 사용되는 추상화로 다음과 같은 기본 데이터 형식을 제공합니다. 이러한 API는 다른 Node-API 호출을 사용하여 내부적으로만 조사할 수 있는 불투명한 것으로 처리해야 합니다.
napi_status
추가됨: v8.0.0
N-API 버전: 1
Node-API 호출의 성공 또는 실패를 나타내는 정수 상태 코드입니다. 현재 다음 상태 코드가 지원됩니다.
typedef enum {
napi_ok,
napi_invalid_arg,
napi_object_expected,
napi_string_expected,
napi_name_expected,
napi_function_expected,
napi_number_expected,
napi_boolean_expected,
napi_array_expected,
napi_generic_failure,
napi_pending_exception,
napi_cancelled,
napi_escape_called_twice,
napi_handle_scope_mismatch,
napi_callback_scope_mismatch,
napi_queue_full,
napi_closing,
napi_bigint_expected,
napi_date_expected,
napi_arraybuffer_expected,
napi_detachable_arraybuffer_expected,
napi_would_deadlock, /* 사용되지 않음 */
napi_no_external_buffers_allowed,
napi_cannot_run_js
} napi_status;
API가 실패한 상태를 반환할 때 추가 정보가 필요한 경우 napi_get_last_error_info
를 호출하여 얻을 수 있습니다.
napi_extended_error_info
추가됨: v8.0.0
N-API 버전: 1
typedef struct {
const char* error_message;
void* engine_reserved;
uint32_t engine_error_code;
napi_status error_code;
} napi_extended_error_info;
error_message
: 오류에 대한 VM 중립적 설명이 포함된 UTF8 인코딩 문자열입니다.engine_reserved
: VM별 오류 세부 정보를 위해 예약되어 있습니다. 현재 어떤 VM에도 구현되어 있지 않습니다.engine_error_code
: VM별 오류 코드입니다. 현재 어떤 VM에도 구현되어 있지 않습니다.error_code
: 마지막 오류에서 발생한 Node-API 상태 코드입니다.
추가 정보는 오류 처리 섹션을 참조하십시오.
napi_env
napi_env
는 기본 Node-API 구현이 VM별 상태를 유지하는 데 사용할 수 있는 컨텍스트를 나타내는 데 사용됩니다. 이 구조체는 네이티브 함수가 호출될 때 전달되며, Node-API 호출을 수행할 때 다시 전달되어야 합니다. 구체적으로, 초기 네이티브 함수가 호출될 때 전달된 것과 동일한 napi_env
를 후속 중첩 Node-API 호출에 전달해야 합니다. 일반적인 재사용을 위해 napi_env
를 캐싱하고 서로 다른 Worker
스레드에서 실행되는 동일한 애드온의 인스턴스 간에 napi_env
를 전달하는 것은 허용되지 않습니다. 네이티브 애드온의 인스턴스가 언로드되면 napi_env
는 무효화됩니다. 이 이벤트에 대한 알림은 napi_add_env_cleanup_hook
및 napi_set_instance_data
에 제공된 콜백을 통해 전달됩니다.
node_api_basic_env
napi_env
의 이 변형은 동기식 finalizer(node_api_basic_finalize
)에 전달됩니다. node_api_basic_env
형식의 매개변수를 첫 번째 인수로 받는 Node-API의 하위 집합이 있습니다. 이러한 API는 JavaScript 엔진의 상태에 액세스하지 않으므로 동기식 finalizer에서 호출해도 안전합니다. 이러한 API에 napi_env
형식의 매개변수를 전달하는 것은 허용되지만, JavaScript 엔진 상태에 액세스하는 API에 node_api_basic_env
형식의 매개변수를 전달하는 것은 허용되지 않습니다. 캐스팅 없이 이렇게 하려고 하면 애드온이 잘못된 포인터 유형이 함수에 전달될 때 경고 및/또는 오류를 내도록 하는 플래그로 컴파일될 때 컴파일러 경고 또는 오류가 발생합니다. 동기식 finalizer에서 이러한 API를 호출하면 최종적으로 애플리케이션이 종료됩니다.
napi_value
이는 JavaScript 값을 나타내는 데 사용되는 불투명 포인터입니다.
napi_threadsafe_function
추가됨: v10.6.0
N-API 버전: 4
napi_call_threadsafe_function()
을 통해 여러 스레드에서 비동기적으로 호출할 수 있는 JavaScript 함수를 나타내는 불투명 포인터입니다.
napi_threadsafe_function_release_mode
추가됨: v10.6.0
N-API 버전: 4
스레드 안전 함수를 즉시 닫을지(napi_tsfn_abort
) 아니면 단순히 해제할지(napi_tsfn_release
) napi_release_threadsafe_function()
에 제공할 값입니다. 해제된 함수는 napi_acquire_threadsafe_function()
및 napi_call_threadsafe_function()
을 통해 후속 사용이 가능합니다.
typedef enum {
napi_tsfn_release,
napi_tsfn_abort
} napi_threadsafe_function_release_mode;
napi_threadsafe_function_call_mode
추가됨: v10.6.0
N-API 버전: 4
스레드 안전 함수와 연결된 큐가 가득 찼을 때 호출이 차단되어야 하는지 여부를 나타내는 napi_call_threadsafe_function()
에 제공할 값입니다.
typedef enum {
napi_tsfn_nonblocking,
napi_tsfn_blocking
} napi_threadsafe_function_call_mode;
Node-API 메모리 관리 유형
napi_handle_scope
특정 범위 내에서 생성된 객체의 수명을 제어하고 수정하는 데 사용되는 추상화입니다. 일반적으로 Node-API 값은 핸들 범위의 컨텍스트 내에서 생성됩니다. 네이티브 메서드가 JavaScript에서 호출될 때 기본 핸들 범위가 존재합니다. 사용자가 명시적으로 새로운 핸들 범위를 생성하지 않으면 Node-API 값은 기본 핸들 범위에서 생성됩니다. 네이티브 메서드 실행 이외의 코드 호출(예: libuv 콜백 호출 중)에 대해 모듈은 JavaScript 값 생성으로 이어질 수 있는 함수를 호출하기 전에 범위를 생성해야 합니다.
핸들 범위는 napi_open_handle_scope
를 사용하여 생성되고 napi_close_handle_scope
를 사용하여 삭제됩니다. 범위를 닫으면 GC에 핸들 범위의 수명 동안 생성된 모든 napi_value
가 현재 스택 프레임에서 더 이상 참조되지 않음을 나타낼 수 있습니다.
자세한 내용은 객체 수명 관리를 참조하십시오.
napi_escapable_handle_scope
추가됨: v8.0.0
N-API 버전: 1
Escapable handle scope는 특정 handle scope 내에서 생성된 값을 상위 scope로 반환하기 위한 특수한 유형의 handle scope입니다.
napi_ref
추가됨: v8.0.0
N-API 버전: 1
napi_value
를 참조하는 데 사용되는 추상화입니다. 이를 통해 사용자는 JavaScript 값의 수명을 관리하고, 최소 수명을 명시적으로 정의할 수 있습니다.
자세한 내용은 객체 수명 관리를 참조하십시오.
napi_type_tag
추가됨: v14.8.0, v12.19.0
N-API 버전: 8
두 개의 부호 없는 64비트 정수로 저장되는 128비트 값입니다. JavaScript 객체 또는 외부 객체에 "태그"를 지정하여 특정 유형임을 확인하는 UUID 역할을 합니다. 객체의 프로토타입이 조작된 경우 후자가 가양성을 보고할 수 있으므로 napi_instanceof
보다 더 강력한 검사입니다. 유형 태깅은 napi_wrap
과 함께 사용하는 것이 가장 유용합니다. 이는 래핑된 객체에서 검색된 포인터를 이전에 JavaScript 객체에 적용된 유형 태그에 해당하는 네이티브 유형으로 안전하게 캐스팅할 수 있도록 보장하기 때문입니다.
typedef struct {
uint64_t lower;
uint64_t upper;
} napi_type_tag;
napi_async_cleanup_hook_handle
추가됨: v14.10.0, v12.19.0
napi_add_async_cleanup_hook
에서 반환되는 불투명 값입니다. 비동기 정리 이벤트 체인이 완료되면 napi_remove_async_cleanup_hook
에 전달해야 합니다.
Node-API 콜백 유형
napi_callback_info
추가됨: v8.0.0
N-API 버전: 1
콜백 함수에 전달되는 불투명 데이터 유형입니다. 콜백이 호출된 컨텍스트에 대한 추가 정보를 얻는 데 사용할 수 있습니다.
napi_callback
추가됨: v8.0.0
N-API 버전: 1
Node-API를 통해 JavaScript에 노출될 사용자 제공 네이티브 함수에 대한 함수 포인터 유형입니다. 콜백 함수는 다음 서명을 충족해야 합니다.
typedef napi_value (*napi_callback)(napi_env, napi_callback_info);
객체 수명 관리에서 설명하는 이유가 없는 한 napi_callback
내부에서 handle 및/또는 콜백 scope를 생성할 필요가 없습니다.
node_api_basic_finalize
추가됨: v21.6.0, v20.12.0, v18.20.0
외부 소유 데이터가 연결된 객체가 가비지 수집되었으므로 정리가 준비되었음을 사용자에게 알리는 추가 기능에서 제공하는 함수 포인터 유형입니다. 사용자는 객체 수집 시 호출될 다음 서명을 충족하는 함수를 제공해야 합니다. 현재 node_api_basic_finalize
는 외부 데이터가 있는 객체가 수집될 때를 확인하는 데 사용할 수 있습니다.
typedef void (*node_api_basic_finalize)(node_api_basic_env env,
void* finalize_data,
void* finalize_hint);
객체 수명 관리에서 논의된 이유가 아닌 한, 함수 본문 내에서 핸들 및/또는 콜백 범위를 만드는 것은 필요하지 않습니다.
이러한 함수는 JavaScript 엔진이 JavaScript 코드를 실행할 수 없는 상태에서 호출될 수 있으므로 첫 번째 매개변수로 node_api_basic_env
를 허용하는 Node-API만 호출할 수 있습니다. node_api_post_finalizer
는 현재 가비지 수집 주기가 완료된 후 실행하기 위해 JavaScript 엔진 상태에 대한 액세스가 필요한 Node-API 호출을 예약하는 데 사용할 수 있습니다.
node_api_create_external_string_latin1
및 node_api_create_external_string_utf16
의 경우 외부 문자열은 환경 종료 후반부에 수집될 수 있으므로 env
매개변수는 null일 수 있습니다.
변경 이력:
- 실험적 (
NAPI_EXPERIMENTAL
): 첫 번째 매개변수로node_api_basic_env
를 허용하는 Node-API 호출만 호출할 수 있습니다. 그렇지 않으면 적절한 오류 메시지와 함께 애플리케이션이 종료됩니다. 이 기능은NODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT
을 정의하여 끌 수 있습니다.
napi_finalize
추가된 버전: v8.0.0
N-API 버전: 1
가비지 컬렉션 이벤트에 대한 응답으로 Node-API에 대한 일련의 호출을 가비지 컬렉션 주기가 완료된 후 예약할 수 있도록 사용자에게 허용하는 애드온 제공 함수에 대한 함수 포인터 유형입니다. 이러한 함수 포인터는 node_api_post_finalizer
와 함께 사용할 수 있습니다.
typedef void (*napi_finalize)(napi_env env,
void* finalize_data,
void* finalize_hint);
변경 이력:
- 실험적(
NAPI_EXPERIMENTAL
이 정의됨): 이 유형의 함수는node_api_post_finalizer
를 제외하고는 더 이상 finalizer로 사용할 수 없습니다. 대신node_api_basic_finalize
를 사용해야 합니다. 이 기능은NODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT
를 정의하여 끌 수 있습니다.
napi_async_execute_callback
추가된 버전: v8.0.0
N-API 버전: 1
비동기 작업을 지원하는 함수와 함께 사용되는 함수 포인터입니다. 콜백 함수는 다음 서명을 충족해야 합니다.
typedef void (*napi_async_execute_callback)(napi_env env, void* data);
이 함수의 구현에서는 JavaScript를 실행하거나 JavaScript 객체와 상호 작용하는 Node-API 호출을 피해야 합니다. Node-API 호출은 대신 napi_async_complete_callback
에 있어야 합니다. napi_env
매개변수를 사용하지 마십시오. JavaScript 실행으로 이어질 가능성이 높습니다.
napi_async_complete_callback
추가된 버전: v8.0.0
N-API 버전: 1
비동기 작업을 지원하는 함수와 함께 사용되는 함수 포인터입니다. 콜백 함수는 다음 서명을 충족해야 합니다.
typedef void (*napi_async_complete_callback)(napi_env env,
napi_status status,
void* data);
객체 수명 관리에서 설명하는 이유가 없는 한 함수 본문 내부에 핸들 및/또는 콜백 범위를 생성할 필요가 없습니다.
napi_threadsafe_function_call_js
추가됨: v10.6.0
N-API 버전: 4
비동기식 쓰레드 안전 함수 호출에 사용되는 함수 포인터입니다. 콜백은 메인 쓰레드에서 호출됩니다. 그 목적은 보조 쓰레드 중 하나에서 큐를 통해 도착하는 데이터 항목을 사용하여 JavaScript로의 호출(일반적으로 napi_call_function
을 통해)에 필요한 매개변수를 구성한 다음 JavaScript로 호출하는 것입니다.
큐를 통해 보조 쓰레드에서 도착하는 데이터는 data
매개변수에 제공되고 호출할 JavaScript 함수는 js_callback
매개변수에 제공됩니다.
Node-API는 이 콜백을 호출하기 전에 환경을 설정하므로 napi_make_callback
을 통해서가 아니라 napi_call_function
을 통해 JavaScript 함수를 호출하는 것으로 충분합니다.
콜백 함수는 다음 서명을 충족해야 합니다.
typedef void (*napi_threadsafe_function_call_js)(napi_env env,
napi_value js_callback,
void* context,
void* data);
[in] env
: API 호출에 사용할 환경 또는 쓰레드 안전 함수가 해제 중이고data
를 해제해야 할 수 있는 경우NULL
입니다.[in] js_callback
: 호출할 JavaScript 함수 또는 쓰레드 안전 함수가 해제 중이고data
를 해제해야 할 수 있는 경우NULL
입니다. 쓰레드 안전 함수가js_callback
없이 생성된 경우에도NULL
일 수 있습니다.[in] context
: 쓰레드 안전 함수가 생성된 선택적 데이터입니다.[in] data
: 보조 쓰레드에서 생성된 데이터입니다. 이 네이티브 데이터를js_callback
이 호출될 때 매개변수로 전달할 수 있는 JavaScript 값(Node-API 함수 사용)으로 변환하는 것은 콜백의 책임입니다. 이 포인터는 쓰레드와 이 콜백에 의해 전적으로 관리됩니다. 따라서 이 콜백은 데이터를 해제해야 합니다.
객체 수명 관리에서 논의된 이유가 아닌 한, 함수 본문 내부에 핸들 및/또는 콜백 범위를 생성할 필요가 없습니다.
napi_cleanup_hook
추가됨: v19.2.0, v18.13.0
N-API 버전: 3
napi_add_env_cleanup_hook
와 함께 사용되는 함수 포인터입니다. 환경이 해체될 때 호출됩니다.
콜백 함수는 다음 시그니처를 충족해야 합니다.
typedef void (*napi_cleanup_hook)(void* data);
[in] data
:napi_add_env_cleanup_hook
에 전달된 데이터입니다.
napi_async_cleanup_hook
추가됨: v14.10.0, v12.19.0
napi_add_async_cleanup_hook
와 함께 사용되는 함수 포인터입니다. 환경이 해체될 때 호출됩니다.
콜백 함수는 다음 시그니처를 충족해야 합니다.
typedef void (*napi_async_cleanup_hook)(napi_async_cleanup_hook_handle handle,
void* data);
[in] handle
: 비동기 정리 완료 후napi_remove_async_cleanup_hook
호출에 전달해야 하는 핸들입니다.[in] data
:napi_add_async_cleanup_hook
에 전달된 데이터입니다.
함수 본문은 비동기 정리 작업을 시작해야 하며, 그 끝에서 handle
은 napi_remove_async_cleanup_hook
호출에 전달되어야 합니다.
오류 처리
Node-API는 오류 처리에 반환 값과 JavaScript 예외를 모두 사용합니다. 다음 섹션에서는 각 경우에 대한 접근 방식을 설명합니다.
반환 값
모든 Node-API 함수는 동일한 오류 처리 패턴을 공유합니다. 모든 API 함수의 반환 형식은 napi_status
입니다.
요청이 성공하고 처리되지 않은 JavaScript 예외가 발생하지 않은 경우 반환 값은 napi_ok
가 됩니다. 오류가 발생하고 예외가 발생한 경우 오류에 대한 napi_status
값이 반환됩니다. 예외가 발생하고 오류가 발생하지 않은 경우 napi_pending_exception
이 반환됩니다.
napi_ok
또는 napi_pending_exception
이외의 반환 값이 반환되는 경우, 예외가 보류 중인지 확인하려면 napi_is_exception_pending
을 호출해야 합니다. 자세한 내용은 예외에 대한 섹션을 참조하십시오.
가능한 napi_status
값의 전체 집합은 napi_api_types.h
에 정의되어 있습니다.
napi_status
반환 값은 발생한 오류의 VM과 독립적인 표현을 제공합니다. 경우에 따라 오류를 나타내는 문자열과 VM(엔진) 관련 정보를 포함하여 더 자세한 정보를 얻는 것이 유용합니다.
이 정보를 검색하기 위해 napi_get_last_error_info
가 제공되며, 이는 napi_extended_error_info
구조체를 반환합니다. napi_extended_error_info
구조체의 형식은 다음과 같습니다.
추가됨: v8.0.0
N-API 버전: 1
typedef struct napi_extended_error_info {
const char* error_message;
void* engine_reserved;
uint32_t engine_error_code;
napi_status error_code;
};
error_message
: 발생한 오류의 텍스트 표현입니다.engine_reserved
: 엔진 전용으로 예약된 불투명 핸들입니다.engine_error_code
: VM 관련 오류 코드입니다.error_code
: 마지막 오류에 대한 Node-API 상태 코드입니다.
napi_get_last_error_info
는 마지막으로 호출된 Node-API 호출에 대한 정보를 반환합니다.
확장된 정보의 내용이나 형식에 의존하지 마십시오. SemVer의 적용 대상이 아니며 언제든지 변경될 수 있습니다. 로깅 목적으로만 사용됩니다.
napi_get_last_error_info
추가됨: v8.0.0
N-API 버전: 1
napi_status
napi_get_last_error_info(node_api_basic_env env,
const napi_extended_error_info** result);
[in] env
: API가 호출되는 환경입니다.[out] result
: 오류에 대한 자세한 정보가 포함된napi_extended_error_info
구조체입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 발생한 마지막 오류에 대한 정보가 포함된 napi_extended_error_info
구조체를 가져옵니다.
반환된 napi_extended_error_info
의 내용은 동일한 env
에서 Node-API 함수가 호출될 때까지 유효합니다. 여기에는 napi_is_exception_pending
호출이 포함되므로 나중에 사용할 수 있도록 정보를 복사해야 하는 경우가 많습니다. error_message
에 반환된 포인터는 정적으로 정의된 문자열을 가리키므로 다른 Node-API 함수가 호출되기 전에 error_message
필드에서 복사한 경우 해당 포인터를 안전하게 사용할 수 있습니다(덮어쓰여짐).
확장 정보의 내용이나 형식에 의존하지 마십시오. SemVer의 적용을 받지 않으며 언제든지 변경될 수 있습니다. 로깅 목적으로만 사용됩니다.
JavaScript 예외가 발생 중인 경우에도 이 API를 호출할 수 있습니다.
예외
모든 Node-API 함수 호출은 보류 중인 JavaScript 예외를 발생시킬 수 있습니다. JavaScript 실행을 유발하지 않을 수도 있는 모든 API 함수에도 해당됩니다.
함수가 반환하는 napi_status
가 napi_ok
이면 예외가 보류 중이 아니며 추가적인 작업이 필요하지 않습니다. 반환된 napi_status
가 napi_ok
또는 napi_pending_exception
이 아닌 경우, 단순히 즉시 반환하는 대신 복구하고 계속하려면, 예외가 보류 중인지 여부를 확인하기 위해 napi_is_exception_pending
을 호출해야 합니다.
Node-API 함수를 호출하고 예외가 이미 보류 중인 경우 대부분의 경우 함수는 napi_pending_exception
의 napi_status
를 사용하여 즉시 반환합니다. 그러나 모든 함수에 해당하는 것은 아닙니다. Node-API는 JavaScript로 돌아가기 전에 최소한의 정리를 허용하기 위해 함수의 하위 집합을 호출할 수 있도록 허용합니다. 이 경우 napi_status
는 함수의 상태를 반영합니다. 이전에 보류 중인 예외는 반영하지 않습니다. 혼동을 피하려면 모든 함수 호출 후 오류 상태를 확인하십시오.
예외가 보류 중인 경우 두 가지 방법 중 하나를 사용할 수 있습니다.
첫 번째 방법은 적절한 정리를 수행한 다음 JavaScript로 실행이 반환되도록 반환하는 것입니다. JavaScript로의 전환의 일환으로, 예외는 네이티브 메서드가 호출된 JavaScript 코드의 지점에서 throw됩니다. 예외가 보류 중인 동안 대부분의 Node-API 호출의 동작은 명시되지 않았으며, 많은 호출이 단순히 napi_pending_exception
을 반환하므로 최소한의 작업만 수행한 다음 예외를 처리할 수 있는 JavaScript로 돌아가십시오.
두 번째 방법은 예외를 처리하려고 시도하는 것입니다. 네이티브 코드가 예외를 catch하고 적절한 조치를 취한 다음 계속할 수 있는 경우가 있습니다. 이것은 예외를 안전하게 처리할 수 있는 것으로 알려진 특정 경우에만 권장됩니다. 이러한 경우 napi_get_and_clear_last_exception
을 사용하여 예외를 가져오고 지울 수 있습니다. 성공하면 result는 throw된 마지막 JavaScript Object
에 대한 핸들을 포함합니다. 예외를 가져온 후 예외를 처리할 수 없는 것으로 판단되면 napi_throw
를 사용하여 다시 throw할 수 있습니다. 여기서 error는 throw될 JavaScript 값입니다.
네이티브 코드가 예외를 throw하거나 napi_value
가 JavaScript Error
객체의 인스턴스인지 확인해야 하는 경우 다음 유틸리티 함수도 사용할 수 있습니다. napi_throw_error
, napi_throw_type_error
, napi_throw_range_error
, node_api_throw_syntax_error
및 napi_is_error
.
네이티브 코드가 Error
객체를 생성해야 하는 경우 다음 유틸리티 함수도 사용할 수 있습니다. napi_create_error
, napi_create_type_error
, napi_create_range_error
및 node_api_create_syntax_error
. 여기서 result는 새로 생성된 JavaScript Error
객체를 참조하는 napi_value
입니다.
Node.js 프로젝트는 내부적으로 생성된 모든 오류에 오류 코드를 추가하고 있습니다. 애플리케이션에서 모든 오류 검사에 이러한 오류 코드를 사용하는 것이 목표입니다. 관련 오류 메시지는 유지되지만, SemVer가 적용되지 않을 것이라는 예상으로 로깅 및 표시에만 사용될 것입니다. Node-API에서 내부 기능과 모듈별 기능 모두를 지원하기 위해(좋은 방법
이므로) throw_
및 create_
함수는 오류 객체에 추가할 코드의 문자열인 선택적 코드 매개변수를 사용합니다. 선택적 매개변수가 NULL
이면 오류와 연결된 코드가 없습니다. 코드가 제공되면 오류와 관련된 이름도 다음과 같이 업데이트됩니다.
originalName [code]
여기서 originalName
은 오류와 관련된 원래 이름이고 code
는 제공된 코드입니다. 예를 들어, 코드가 'ERR_ERROR_1'
이고 TypeError
가 생성 중이면 이름은 다음과 같습니다.
TypeError [ERR_ERROR_1]
napi_throw
추가됨: v8.0.0
N-API 버전: 1
NAPI_EXTERN napi_status napi_throw(napi_env env, napi_value error);
[in] env
: API가 호출되는 환경입니다.[in] error
: throw할 JavaScript 값입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 제공된 JavaScript 값을 throw합니다.
napi_throw_error
추가됨: v8.0.0
N-API 버전: 1
NAPI_EXTERN napi_status napi_throw_error(napi_env env,
const char* code,
const char* msg);
[in] env
: API가 호출되는 환경입니다.[in] code
: 오류에 설정할 선택적 오류 코드입니다.[in] msg
: 오류와 연결할 텍스트를 나타내는 C 문자열입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 제공된 텍스트를 사용하여 JavaScript Error
를 throw합니다.
napi_throw_type_error
추가됨: v8.0.0
N-API 버전: 1
NAPI_EXTERN napi_status napi_throw_type_error(napi_env env,
const char* code,
const char* msg);
[in] env
: API가 호출되는 환경입니다.[in] code
: 오류에 설정할 선택적 오류 코드입니다.[in] msg
: 오류와 연결할 텍스트를 나타내는 C 문자열입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 제공된 텍스트를 사용하여 JavaScript TypeError
를 throw합니다.
napi_throw_range_error
추가됨: v8.0.0
N-API 버전: 1
NAPI_EXTERN napi_status napi_throw_range_error(napi_env env,
const char* code,
const char* msg);
[in] env
: API가 호출되는 환경입니다.[in] code
: 오류에 설정할 선택적 오류 코드입니다.[in] msg
: 오류와 연결할 텍스트를 나타내는 C 문자열입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 제공된 텍스트를 사용하여 JavaScript RangeError
를 throw합니다.
node_api_throw_syntax_error
추가됨: v17.2.0, v16.14.0
N-API 버전: 9
NAPI_EXTERN napi_status node_api_throw_syntax_error(napi_env env,
const char* code,
const char* msg);
[in] env
: API가 호출되는 환경입니다.[in] code
: 오류에 설정될 선택적 오류 코드입니다.[in] msg
: 오류와 연결될 텍스트를 나타내는 C 문자열입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 제공된 텍스트를 사용하여 JavaScript SyntaxError
를 throw합니다.
napi_is_error
추가됨: v8.0.0
N-API 버전: 1
NAPI_EXTERN napi_status napi_is_error(napi_env env,
napi_value value,
bool* result);
[in] env
: API가 호출되는 환경입니다.[in] value
: 확인할napi_value
입니다.[out] result
:napi_value
가 오류를 나타내는 경우 true, 그렇지 않으면 false로 설정되는 부울 값입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 napi_value
가 오류 객체를 나타내는지 확인합니다.
napi_create_error
추가됨: v8.0.0
N-API 버전: 1
NAPI_EXTERN napi_status napi_create_error(napi_env env,
napi_value code,
napi_value msg,
napi_value* result);
[in] env
: API가 호출되는 환경입니다.[in] code
: 오류와 연결될 오류 코드의 문자열이 포함된 선택적napi_value
입니다.[in] msg
:Error
의 메시지로 사용될 JavaScriptstring
을 참조하는napi_value
입니다.[out] result
: 생성된 오류를 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 제공된 텍스트를 사용하여 JavaScript Error
를 반환합니다.
napi_create_type_error
추가됨: v8.0.0
N-API 버전: 1
NAPI_EXTERN napi_status napi_create_type_error(napi_env env,
napi_value code,
napi_value msg,
napi_value* result);
[in] env
: API가 호출되는 환경입니다.[in] code
: 오류와 연결될 오류 코드의 문자열이 포함된 선택적napi_value
입니다.[in] msg
:Error
의 메시지로 사용될 JavaScriptstring
을 참조하는napi_value
입니다.[out] result
: 생성된 오류를 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 제공된 텍스트를 사용하여 JavaScript TypeError
를 반환합니다.
napi_create_range_error
추가됨: v8.0.0
N-API 버전: 1
NAPI_EXTERN napi_status napi_create_range_error(napi_env env,
napi_value code,
napi_value msg,
napi_value* result);
[in] env
: API가 호출되는 환경입니다.[in] code
: 오류와 연결될 오류 코드 문자열이 포함된 선택적napi_value
입니다.[in] msg
:Error
의 메시지로 사용될 JavaScriptstring
을 참조하는napi_value
입니다.[out] result
: 생성된 오류를 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 제공된 텍스트를 사용하여 JavaScript RangeError
를 반환합니다.
node_api_create_syntax_error
추가됨: v17.2.0, v16.14.0
N-API 버전: 9
NAPI_EXTERN napi_status node_api_create_syntax_error(napi_env env,
napi_value code,
napi_value msg,
napi_value* result);
[in] env
: API가 호출되는 환경입니다.[in] code
: 오류와 연결될 오류 코드 문자열이 포함된 선택적napi_value
입니다.[in] msg
:Error
의 메시지로 사용될 JavaScriptstring
을 참조하는napi_value
입니다.[out] result
: 생성된 오류를 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 제공된 텍스트를 사용하여 JavaScript SyntaxError
를 반환합니다.
napi_get_and_clear_last_exception
추가됨: v8.0.0
N-API 버전: 1
napi_status napi_get_and_clear_last_exception(napi_env env,
napi_value* result);
[in] env
: API가 호출되는 환경입니다.[out] result
: 예외가 대기 중인 경우 예외, 그렇지 않으면NULL
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 JavaScript 예외가 대기 중인 경우에도 호출할 수 있습니다.
napi_is_exception_pending
추가됨: v8.0.0
N-API 버전: 1
napi_status napi_is_exception_pending(napi_env env, bool* result);
[in] env
: API가 호출되는 환경입니다.[out] result
: 예외가 대기 중인 경우 true로 설정되는 부울 값입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 JavaScript 예외가 대기 중인 경우에도 호출할 수 있습니다.
napi_fatal_exception
추가됨: v9.10.0
N-API 버전: 3
napi_status napi_fatal_exception(napi_env env, napi_value err);
[in] env
: API가 호출되는 환경입니다.[in] err
:'uncaughtException'
에 전달되는 오류입니다.
JavaScript에서 'uncaughtException'
을 트리거합니다. 비동기 콜백이 복구할 방법이 없는 예외를 throw하는 경우 유용합니다.
치명적인 오류
네이티브 애드온에서 복구할 수 없는 오류가 발생하는 경우, 프로세스를 즉시 종료하기 위해 치명적인 오류를 throw할 수 있습니다.
napi_fatal_error
추가됨: v8.2.0
N-API 버전: 1
NAPI_NO_RETURN void napi_fatal_error(const char* location,
size_t location_len,
const char* message,
size_t message_len);
[in] location
: 오류가 발생한 위치(선택 사항)입니다.[in] location_len
: 바이트 단위의 위치 길이 또는 null로 종료되는 경우NAPI_AUTO_LENGTH
입니다.[in] message
: 오류와 관련된 메시지입니다.[in] message_len
: 바이트 단위의 메시지 길이 또는 null로 종료되는 경우NAPI_AUTO_LENGTH
입니다.
함수 호출은 반환되지 않으며 프로세스가 종료됩니다.
이 API는 JavaScript 예외가 대기 중인 경우에도 호출할 수 있습니다.
객체 수명 관리
Node-API 호출이 이루어짐에 따라, 기본 VM의 힙에 있는 객체에 대한 핸들이 napi_values
로 반환될 수 있습니다. 이러한 핸들은 네이티브 코드에서 더 이상 필요하지 않을 때까지 객체를 '활성' 상태로 유지해야 합니다. 그렇지 않으면 네이티브 코드가 사용을 완료하기 전에 객체가 수집될 수 있습니다.
객체 핸들이 반환됨에 따라 '범위'와 연결됩니다. 기본 범위의 수명은 네이티브 메서드 호출의 수명과 연결됩니다. 결과적으로 기본적으로 핸들은 유효한 상태를 유지하고 이러한 핸들과 연결된 객체는 네이티브 메서드 호출의 수명 동안 활성 상태로 유지됩니다.
그러나 많은 경우 핸들이 네이티브 메서드보다 짧거나 긴 수명 동안 유효해야 합니다. 다음 섹션에서는 핸들 수명을 기본값에서 변경하는 데 사용할 수 있는 Node-API 함수에 대해 설명합니다.
네이티브 메서드보다 짧은 핸들 수명주기 만들기
네이티브 메서드의 수명주기보다 짧은 핸들 수명주기를 만드는 것이 종종 필요합니다. 예를 들어, 큰 배열의 요소를 반복하는 루프가 있는 네이티브 메서드를 고려해 보세요.
for (int i = 0; i < 1000000; i++) {
napi_value result;
napi_status status = napi_get_element(env, object, i, &result);
if (status != napi_ok) {
break;
}
// 요소를 사용하여 작업 수행
}
이렇게 하면 많은 수의 핸들이 생성되어 상당한 리소스를 소모하게 됩니다. 또한 네이티브 코드는 가장 최근의 핸들만 사용할 수 있지만, 모든 연관된 객체는 동일한 범위를 공유하기 때문에 계속해서 살아 있게 됩니다.
이러한 경우를 처리하기 위해 Node-API는 새로 생성된 핸들이 연결될 새로운 '범위'를 설정하는 기능을 제공합니다. 해당 핸들이 더 이상 필요하지 않으면 범위를 '닫을' 수 있으며, 범위와 연결된 모든 핸들은 무효화됩니다. 범위를 열고 닫는 데 사용할 수 있는 메서드는 napi_open_handle_scope
와 napi_close_handle_scope
입니다.
Node-API는 중첩된 단일 범위 계층 구조만 지원합니다. 어느 시점에도 활성 범위는 하나뿐이며, 모든 새 핸들은 활성화된 동안 해당 범위와 연결됩니다. 범위는 열린 순서의 역순으로 닫아야 합니다. 또한 네이티브 메서드 내에서 생성된 모든 범위는 해당 메서드에서 반환하기 전에 닫아야 합니다.
앞의 예제에서 napi_open_handle_scope
와 napi_close_handle_scope
호출을 추가하면 루프 실행 전체에서 최대 하나의 핸들만 유효하게 유지됩니다.
for (int i = 0; i < 1000000; i++) {
napi_handle_scope scope;
napi_status status = napi_open_handle_scope(env, &scope);
if (status != napi_ok) {
break;
}
napi_value result;
status = napi_get_element(env, object, i, &result);
if (status != napi_ok) {
break;
}
// 요소를 사용하여 작업 수행
status = napi_close_handle_scope(env, scope);
if (status != napi_ok) {
break;
}
}
범위를 중첩할 때 내부 범위의 핸들이 해당 범위의 수명주기보다 오래 지속되어야 하는 경우가 있습니다. Node-API는 이러한 경우를 지원하기 위해 '탈출 가능한 범위'를 지원합니다. 탈출 가능한 범위를 사용하면 하나의 핸들을 '승격'하여 현재 범위를 '탈출'할 수 있으며, 핸들의 수명주기는 현재 범위에서 외부 범위로 변경됩니다.
탈출 가능한 범위를 열고 닫는 데 사용할 수 있는 메서드는 napi_open_escapable_handle_scope
와 napi_close_escapable_handle_scope
입니다.
핸들을 승격하려는 요청은 napi_escape_handle
을 통해 이루어지며, 이 메서드는 한 번만 호출할 수 있습니다.
napi_open_handle_scope
추가됨: v8.0.0
N-API 버전: 1
NAPI_EXTERN napi_status napi_open_handle_scope(napi_env env,
napi_handle_scope* result);
[in] env
: API가 호출되는 환경입니다.[out] result
: 새 스코프를 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 새로운 스코프를 엽니다.
napi_close_handle_scope
추가됨: v8.0.0
N-API 버전: 1
NAPI_EXTERN napi_status napi_close_handle_scope(napi_env env,
napi_handle_scope scope);
[in] env
: API가 호출되는 환경입니다.[in] scope
: 닫을 스코프를 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 전달된 스코프를 닫습니다. 스코프는 생성된 역순으로 닫아야 합니다.
이 API는 보류 중인 JavaScript 예외가 있는 경우에도 호출할 수 있습니다.
napi_open_escapable_handle_scope
추가됨: v8.0.0
N-API 버전: 1
NAPI_EXTERN napi_status
napi_open_escapable_handle_scope(napi_env env,
napi_handle_scope* result);
[in] env
: API가 호출되는 환경입니다.[out] result
: 새 스코프를 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 외부 스코프로 하나의 객체를 승격시킬 수 있는 새로운 스코프를 엽니다.
napi_close_escapable_handle_scope
추가됨: v8.0.0
N-API 버전: 1
NAPI_EXTERN napi_status
napi_close_escapable_handle_scope(napi_env env,
napi_handle_scope scope);
[in] env
: API가 호출되는 환경입니다.[in] scope
: 닫을 스코프를 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 전달된 스코프를 닫습니다. 스코프는 생성된 역순으로 닫아야 합니다.
이 API는 보류 중인 JavaScript 예외가 있는 경우에도 호출할 수 있습니다.
napi_escape_handle
추가됨: v8.0.0
N-API 버전: 1
napi_status napi_escape_handle(napi_env env,
napi_escapable_handle_scope scope,
napi_value escapee,
napi_value* result);
[in] env
: API가 호출되는 환경입니다.[in] scope
: 현재 범위를 나타내는napi_value
입니다.[in] escapee
: escaping될 JavaScriptObject
를 나타내는napi_value
입니다.[out] result
: 외부 범위에서 escaping된Object
에 대한 핸들을 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 JavaScript 객체에 대한 핸들을 승격시켜 외부 범위의 수명 동안 유효하게 만듭니다. 범위당 한 번만 호출할 수 있습니다. 한 번 이상 호출하면 오류가 반환됩니다.
이 API는 보류 중인 JavaScript 예외가 있는 경우에도 호출할 수 있습니다.
네이티브 메서드보다 수명이 긴 값에 대한 참조
어떤 경우에는 애드온이 단일 네이티브 메서드 호출보다 수명이 긴 값을 생성하고 참조해야 할 수 있습니다. 예를 들어, 생성자를 만들고 나중에 인스턴스를 생성하기 위한 요청에서 해당 생성자를 사용하려면 여러 다른 인스턴스 생성 요청에서 생성자 객체를 참조할 수 있어야 합니다. 이전 섹션에서 설명한 것처럼 napi_value
로 반환된 일반 핸들로는 이것이 불가능합니다. 일반 핸들의 수명은 범위에 의해 관리되며 모든 범위는 네이티브 메서드가 끝나기 전에 닫혀야 합니다.
Node-API는 값에 대한 영속 참조를 생성하는 메서드를 제공합니다. 현재 Node-API는 객체, 외부, 함수 및 심볼을 포함한 제한된 값 유형 집합에 대해서만 참조를 생성할 수 있습니다.
각 참조에는 0 이상의 값을 갖는 연관된 카운트가 있으며, 이는 참조가 해당 값을 계속 유지할지 여부를 결정합니다. 카운트가 0인 참조는 값이 수집되는 것을 방지하지 않습니다. 객체(객체, 함수, 외부) 및 심볼 유형의 값은 '약한' 참조가 되며 수집되지 않는 동안에도 계속 액세스할 수 있습니다. 0보다 큰 카운트는 값이 수집되는 것을 방지합니다.
심볼 값에는 여러 가지 종류가 있습니다. 진정한 약한 참조 동작은 napi_create_symbol
함수 또는 JavaScript Symbol()
생성자 호출을 사용하여 생성된 로컬 심볼에 의해서만 지원됩니다. node_api_symbol_for
함수 또는 JavaScript Symbol.for()
함수 호출을 사용하여 생성된 전역적으로 등록된 심볼은 가비지 수집기가 수집하지 않기 때문에 항상 강한 참조로 유지됩니다. Symbol.iterator
와 같은 잘 알려진 심볼도 마찬가지입니다. 이것들은 가비지 수집기에서 수집되지 않습니다.
참조는 초기 참조 카운트로 생성할 수 있습니다. 그런 다음 카운트는 napi_reference_ref
및 napi_reference_unref
를 통해 수정할 수 있습니다. 카운트가 0인 참조에 대해 객체가 수집되면 참조와 연결된 객체를 가져오는 후속 호출 napi_get_reference_value
은 반환된 napi_value
에 대해 NULL
을 반환합니다. 객체가 수집된 참조에 대해 napi_reference_ref
를 호출하려고 하면 오류가 발생합니다.
애드온에서 더 이상 필요하지 않으면 참조를 삭제해야 합니다. 참조가 삭제되면 해당 객체가 수집되는 것을 더 이상 방지하지 않습니다. 영속 참조를 삭제하지 않으면 영속 참조에 대한 네이티브 메모리와 힙에 있는 해당 객체가 영구히 유지되어 '메모리 누수'가 발생합니다.
동일한 객체를 참조하는 여러 영속 참조를 생성할 수 있으며, 각 참조는 개별 카운트를 기반으로 객체를 계속 유지하거나 유지하지 않습니다. 동일한 객체에 대한 여러 영속 참조는 예기치 않게 네이티브 메모리를 계속 유지할 수 있습니다. 영속 참조에 대한 네이티브 구조는 참조된 객체에 대한 finalizer가 실행될 때까지 계속 유지되어야 합니다. 동일한 객체에 대해 새로운 영속 참조가 생성되면 해당 객체에 대한 finalizer가 실행되지 않고 이전 영속 참조가 가리키는 네이티브 메모리가 해제되지 않습니다. 가능한 경우 napi_reference_unref
와 함께 napi_delete_reference
를 호출하면 이를 방지할 수 있습니다.
변경 내역:
- 실험적(
NAPI_EXPERIMENTAL
이 정의됨): 모든 값 유형에 대해 참조를 생성할 수 있습니다. 새로 지원되는 값 유형은 약한 참조 의미 체계를 지원하지 않으며 이러한 유형의 값은 참조 카운트가 0이 되면 해제되고 더 이상 참조에서 액세스할 수 없습니다.
napi_create_reference
추가됨: v8.0.0
N-API 버전: 1
NAPI_EXTERN napi_status napi_create_reference(napi_env env,
napi_value value,
uint32_t initial_refcount,
napi_ref* result);
[in] env
: API가 호출되는 환경입니다.[in] value
: 참조가 생성될napi_value
입니다.[in] initial_refcount
: 새 참조의 초기 참조 카운트입니다.[out] result
: 새 참조를 가리키는napi_ref
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 전달된 값에 대해 지정된 참조 카운트를 가진 새 참조를 생성합니다.
napi_delete_reference
추가됨: v8.0.0
N-API 버전: 1
NAPI_EXTERN napi_status napi_delete_reference(napi_env env, napi_ref ref);
[in] env
: API가 호출되는 환경입니다.[in] ref
: 삭제할napi_ref
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 전달된 참조를 삭제합니다.
이 API는 보류 중인 JavaScript 예외가 있어도 호출할 수 있습니다.
napi_reference_ref
추가됨: v8.0.0
N-API 버전: 1
NAPI_EXTERN napi_status napi_reference_ref(napi_env env,
napi_ref ref,
uint32_t* result);
[in] env
: API가 호출되는 환경입니다.[in] ref
: 참조 카운트가 증가될napi_ref
입니다.[out] result
: 새로운 참조 카운트입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 전달된 참조의 참조 카운트를 증가시키고 결과 참조 카운트를 반환합니다.
napi_reference_unref
추가됨: v8.0.0
N-API 버전: 1
NAPI_EXTERN napi_status napi_reference_unref(napi_env env,
napi_ref ref,
uint32_t* result);
[in] env
: API가 호출되는 환경입니다.[in] ref
: 참조 카운트가 감소될napi_ref
입니다.[out] result
: 새로운 참조 카운트입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 전달된 참조의 참조 카운트를 감소시키고 결과 참조 카운트를 반환합니다.
napi_get_reference_value
추가됨: v8.0.0
N-API 버전: 1
NAPI_EXTERN napi_status napi_get_reference_value(napi_env env,
napi_ref ref,
napi_value* result);
[in] env
: API가 호출되는 환경입니다.[in] ref
: 해당 값이 요청되는napi_ref
입니다.[out] result
:napi_ref
가 참조하는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
유효한 경우, 이 API는 napi_ref
와 연결된 JavaScript 값을 나타내는 napi_value
를 반환합니다. 그렇지 않으면, result는 NULL
이 됩니다.
현재 Node.js 환경 종료 시 정리
Node.js 프로세스는 일반적으로 종료 시 모든 리소스를 해제하지만, Node.js의 임베더 또는 향후 Worker 지원에서는 현재 Node.js 환경이 종료될 때 실행될 정리 후크를 애드온이 등록해야 할 수 있습니다.
Node-API는 이러한 콜백을 등록하고 등록 해제하는 함수를 제공합니다. 해당 콜백이 실행될 때 애드온이 보유하고 있는 모든 리소스는 해제되어야 합니다.
napi_add_env_cleanup_hook
추가됨: v10.2.0
N-API 버전: 3
NODE_EXTERN napi_status napi_add_env_cleanup_hook(node_api_basic_env env,
napi_cleanup_hook fun,
void* arg);
현재 Node.js 환경이 종료될 때 arg
매개변수와 함께 실행될 함수로 fun
을 등록합니다.
다른 arg
값을 사용하여 함수를 여러 번 안전하게 지정할 수 있습니다. 이 경우에도 여러 번 호출됩니다. 동일한 fun
과 arg
값을 여러 번 제공하는 것은 허용되지 않으며 프로세스가 중단됩니다.
후크는 역순으로 호출됩니다. 즉, 가장 최근에 추가된 후크가 먼저 호출됩니다.
이 후크는 napi_remove_env_cleanup_hook
을 사용하여 제거할 수 있습니다. 일반적으로 이 후크가 추가된 리소스가 어쨌든 해체될 때 발생합니다.
비동기 정리의 경우 napi_add_async_cleanup_hook
을 사용할 수 있습니다.
napi_remove_env_cleanup_hook
추가됨: v10.2.0
N-API 버전: 3
NAPI_EXTERN napi_status napi_remove_env_cleanup_hook(node_api_basic_env env,
void (*fun)(void* arg),
void* arg);
현재 Node.js 환경이 종료될 때 arg
매개변수와 함께 실행될 함수로 fun
을 등록 해제합니다. 인수와 함수 값은 정확하게 일치해야 합니다.
이 함수는 원래 napi_add_env_cleanup_hook
을 사용하여 등록되어야 하며, 그렇지 않으면 프로세스가 중단됩니다.
napi_add_async_cleanup_hook
[히스토리]
버전 | 변경 사항 |
---|---|
v14.10.0, v12.19.0 | hook 콜백의 시그니처 변경 |
v14.8.0, v12.19.0 | 추가됨: v14.8.0, v12.19.0 |
N-API 버전: 8
NAPI_EXTERN napi_status napi_add_async_cleanup_hook(
node_api_basic_env env,
napi_async_cleanup_hook hook,
void* arg,
napi_async_cleanup_hook_handle* remove_handle);
[in] env
: API가 호출되는 환경입니다.[in] hook
: 환경 해체 시 호출할 함수 포인터입니다.[in] arg
: 호출될 때hook
에 전달할 포인터입니다.[out] remove_handle
: 비동기 정리 후크를 참조하는 선택적 핸들입니다.
현재 Node.js 환경이 종료될 때 remove_handle
및 arg
매개변수와 함께 실행될 함수로 napi_async_cleanup_hook
유형의 함수인 hook
을 등록합니다.
napi_add_env_cleanup_hook
과 달리 후크는 비동기적일 수 있습니다.
그 외에는 일반적으로 napi_add_env_cleanup_hook
의 동작과 일치합니다.
remove_handle
이 NULL
이 아니면, 후크가 이미 호출되었는지 여부에 관계없이 나중에 napi_remove_async_cleanup_hook
에 전달해야 하는 불투명 값이 저장됩니다. 일반적으로 이 후크가 추가된 리소스가 어쨌든 해체될 때 발생합니다.
napi_remove_async_cleanup_hook
[히스토리]
버전 | 변경 사항 |
---|---|
v14.10.0, v12.19.0 | env 매개변수 제거 |
v14.8.0, v12.19.0 | 추가됨: v14.8.0, v12.19.0 |
NAPI_EXTERN napi_status napi_remove_async_cleanup_hook(
napi_async_cleanup_hook_handle remove_handle);
[in] remove_handle
:napi_add_async_cleanup_hook
로 생성된 비동기 정리 후크의 핸들.
remove_handle
에 해당하는 정리 후크의 등록을 취소합니다. 이미 실행이 시작되지 않은 경우 후크가 실행되지 않습니다. napi_add_async_cleanup_hook
에서 얻은 모든 napi_async_cleanup_hook_handle
값에 대해 호출해야 합니다.
Node.js 환경 종료 시 최종화
Node.js 환경은 worker.terminate()
요청과 같이 JavaScript 실행이 허용되지 않는 즉시 임의의 시점에 해체될 수 있습니다. 환경이 해체될 때, JavaScript 객체, 스레드 안전 함수 및 환경 인스턴스 데이터의 등록된 napi_finalize
콜백이 즉시 독립적으로 호출됩니다.
napi_finalize
콜백의 호출은 수동으로 등록된 정리 후크 이후에 예약됩니다. napi_finalize
콜백에서 use-after-free를 방지하기 위해 환경 종료 중 애드온 최종화의 적절한 순서를 보장하기 위해 애드온은 napi_add_env_cleanup_hook
및 napi_add_async_cleanup_hook
을 사용하여 정리 후크를 등록하여 할당된 리소스를 적절한 순서로 수동으로 해제해야 합니다.
모듈 등록
Node-API 모듈은 NODE_MODULE
매크로 대신 다음을 사용하는 것을 제외하고 다른 모듈과 유사한 방식으로 등록됩니다.
NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)
다음 차이점은 Init
메서드의 시그니처입니다. Node-API 모듈의 경우 다음과 같습니다.
napi_value Init(napi_env env, napi_value exports);
Init
의 반환 값은 모듈의 exports
객체로 처리됩니다. 편의를 위해 Init
메서드에는 exports
매개변수를 통해 빈 객체가 전달됩니다. Init
이 NULL
을 반환하면 exports
로 전달된 매개변수가 모듈에 의해 내보내집니다. Node-API 모듈은 module
객체를 수정할 수 없지만 모듈의 exports
속성으로 아무거나 지정할 수 있습니다.
hello
메서드를 함수로 추가하여 애드온에서 제공하는 메서드로 호출할 수 있도록 합니다.
napi_value Init(napi_env env, napi_value exports) {
napi_status status;
napi_property_descriptor desc = {
"hello",
NULL,
Method,
NULL,
NULL,
NULL,
napi_writable | napi_enumerable | napi_configurable,
NULL
};
status = napi_define_properties(env, exports, 1, &desc);
if (status != napi_ok) return NULL;
return exports;
}
애드온에 대한 require()
가 반환할 함수를 설정합니다.
napi_value Init(napi_env env, napi_value exports) {
napi_value method;
napi_status status;
status = napi_create_function(env, "exports", NAPI_AUTO_LENGTH, Method, NULL, &method);
if (status != napi_ok) return NULL;
return method;
}
새 인스턴스를 생성할 수 있도록 클래스를 정의합니다(객체 래핑과 함께 자주 사용됨).
// NOTE: 부분 예제, 참조된 모든 코드가 포함된 것은 아닙니다.
napi_value Init(napi_env env, napi_value exports) {
napi_status status;
napi_property_descriptor properties[] = {
{ "value", NULL, NULL, GetValue, SetValue, NULL, napi_writable | napi_configurable, NULL },
DECLARE_NAPI_METHOD("plusOne", PlusOne),
DECLARE_NAPI_METHOD("multiply", Multiply),
};
napi_value cons;
status =
napi_define_class(env, "MyObject", New, NULL, 3, properties, &cons);
if (status != napi_ok) return NULL;
status = napi_create_reference(env, cons, 1, &constructor);
if (status != napi_ok) return NULL;
status = napi_set_named_property(env, exports, "MyObject", cons);
if (status != napi_ok) return NULL;
return exports;
}
NAPI_MODULE
과 Init
함수를 정의하는 축약형으로 작동하는 NAPI_MODULE_INIT
매크로를 사용할 수도 있습니다.
NAPI_MODULE_INIT(/* napi_env env, napi_value exports */) {
napi_value answer;
napi_status result;
status = napi_create_int64(env, 42, &answer);
if (status != napi_ok) return NULL;
status = napi_set_named_property(env, exports, "answer", answer);
if (status != napi_ok) return NULL;
return exports;
}
env
및 exports
매개변수는 매크로 호출 후 함수 본문에 제공됩니다.
모든 Node-API 애드온은 컨텍스트 인식이므로 여러 번 로드될 수 있습니다. 이러한 모듈을 선언할 때 몇 가지 설계 고려 사항이 있습니다. 컨텍스트 인식 애드온에 대한 설명서에서 자세한 내용을 확인하십시오.
env
및 exports
변수는 매크로 호출 후 함수 본문 내에서 사용할 수 있습니다.
객체에 속성을 설정하는 방법에 대한 자세한 내용은 JavaScript 속성 사용 섹션을 참조하십시오.
일반적으로 애드온 모듈을 빌드하는 방법에 대한 자세한 내용은 기존 API를 참조하십시오.
JavaScript 값 사용하기
Node-API는 모든 유형의 JavaScript 값을 생성하기 위한 API 집합을 제공합니다. 이러한 유형 중 일부는 ECMAScript 언어 사양의 6절에서 설명되어 있습니다.
기본적으로 이러한 API는 다음 중 하나를 수행하는 데 사용됩니다.
Node-API 값은 napi_value
유형으로 표현됩니다. JavaScript 값이 필요한 Node-API 호출은 napi_value
를 사용합니다. 어떤 경우에는 API가 사전에 napi_value
의 유형을 확인합니다. 그러나 성능 향상을 위해 호출자는 해당 napi_value
가 API에서 예상하는 JavaScript 유형인지 확인하는 것이 좋습니다.
열거형 유형
napi_key_collection_mode
추가됨: v13.7.0, v12.17.0, v10.20.0
N-API 버전: 6
typedef enum {
napi_key_include_prototypes,
napi_key_own_only
} napi_key_collection_mode;
Keys/Properties
필터 열거형을 설명합니다.
napi_key_collection_mode
는 수집된 속성의 범위를 제한합니다.
napi_key_own_only
는 수집된 속성을 지정된 객체로만 제한합니다. napi_key_include_prototypes
는 객체의 프로토타입 체인의 모든 키도 포함합니다.
napi_key_filter
추가됨: v13.7.0, v12.17.0, v10.20.0
N-API 버전: 6
typedef enum {
napi_key_all_properties = 0,
napi_key_writable = 1,
napi_key_enumerable = 1 << 1,
napi_key_configurable = 1 << 2,
napi_key_skip_strings = 1 << 3,
napi_key_skip_symbols = 1 << 4
} napi_key_filter;
속성 필터 비트입니다. 이들은 OR 연산을 사용하여 복합 필터를 구성할 수 있습니다.
napi_key_conversion
추가됨: v13.7.0, v12.17.0, v10.20.0
N-API 버전: 6
typedef enum {
napi_key_keep_numbers,
napi_key_numbers_to_strings
} napi_key_conversion;
napi_key_numbers_to_strings
는 정수 인덱스를 문자열로 변환합니다. napi_key_keep_numbers
는 정수 인덱스에 대해 숫자를 반환합니다.
napi_valuetype
typedef enum {
// ES6 유형 (typeof에 해당)
napi_undefined,
napi_null,
napi_boolean,
napi_number,
napi_string,
napi_symbol,
napi_object,
napi_function,
napi_external,
napi_bigint,
} napi_valuetype;
napi_value
의 유형을 설명합니다. 이는 일반적으로 ECMAScript 언어 사양의 6.1절에 설명된 유형에 해당합니다. 해당 절의 유형 외에도 napi_valuetype
는 외부 데이터가 있는 Function
과 Object
를 나타낼 수도 있습니다.
napi_external
유형의 JavaScript 값은 JavaScript에서 속성을 설정할 수 없고 프로토타입이 없는 일반 객체로 나타납니다.
napi_typedarray_type
typedef enum {
napi_int8_array,
napi_uint8_array,
napi_uint8_clamped_array,
napi_int16_array,
napi_uint16_array,
napi_int32_array,
napi_uint32_array,
napi_float32_array,
napi_float64_array,
napi_bigint64_array,
napi_biguint64_array,
} napi_typedarray_type;
이는 TypedArray
의 기본 이진 스칼라 데이터 유형을 나타냅니다. 이 열거형의 요소는 ECMAScript 언어 사양의 22.2절에 해당합니다.
객체 생성 함수
napi_create_array
추가됨: v8.0.0
N-API 버전: 1
napi_status napi_create_array(napi_env env, napi_value* result)
[in] env
: Node-API 호출이 수행되는 환경입니다.[out] result
: JavaScriptArray
를 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 JavaScript Array
유형에 해당하는 Node-API 값을 반환합니다. JavaScript 배열은 ECMAScript 언어 사양의 22.1절에 설명되어 있습니다.
napi_create_array_with_length
추가됨: v8.0.0
N-API 버전: 1
napi_status napi_create_array_with_length(napi_env env,
size_t length,
napi_value* result)
[in] env
: API가 호출되는 환경입니다.[in] length
:Array
의 초기 길이입니다.[out] result
: JavaScriptArray
를 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 JavaScript Array
유형에 해당하는 Node-API 값을 반환합니다. Array
의 length 속성은 전달된 length 매개변수로 설정됩니다. 그러나 배열이 생성될 때 기본 버퍼가 VM에 의해 미리 할당될 것이라고 보장되지는 않습니다. 해당 동작은 기본 VM 구현에 따라 달라집니다. 버퍼가 C를 통해 직접 읽고 쓰기 가능한 연속적인 메모리 블록이어야 하는 경우 napi_create_external_arraybuffer
를 사용하는 것을 고려하십시오.
JavaScript 배열은 ECMAScript 언어 사양의 22.1절에 설명되어 있습니다.
napi_create_arraybuffer
추가됨: v8.0.0
N-API 버전: 1
napi_status napi_create_arraybuffer(napi_env env,
size_t byte_length,
void** data,
napi_value* result)
[in] env
: API가 호출되는 환경입니다.[in] length
: 생성할 ArrayBuffer의 바이트 길이입니다.[out] data
:ArrayBuffer
의 기본 바이트 버퍼에 대한 포인터입니다.data
는NULL
을 전달하여 선택적으로 무시할 수 있습니다.[out] result
: JavaScriptArrayBuffer
를 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 JavaScript ArrayBuffer
에 해당하는 Node-API 값을 반환합니다. ArrayBuffer
는 고정 길이 바이너리 데이터 버퍼를 나타내는 데 사용됩니다. 일반적으로 TypedArray
객체의 백업 버퍼로 사용됩니다. 할당된 ArrayBuffer
는 전달된 length
매개변수에 의해 크기가 결정되는 기본 바이트 버퍼를 갖습니다. 호출자가 버퍼를 직접 조작하려는 경우 기본 버퍼가 선택적으로 호출자에게 반환됩니다. 이 버퍼는 네이티브 코드에서만 직접 작성할 수 있습니다. JavaScript에서 이 버퍼에 쓰려면 형식화된 배열 또는 DataView
객체를 생성해야 합니다.
JavaScript ArrayBuffer
객체는 ECMAScript 언어 사양의 24.1절에 설명되어 있습니다.
napi_create_buffer
추가됨: v8.0.0
N-API 버전: 1
napi_status napi_create_buffer(napi_env env,
size_t size,
void** data,
napi_value* result)
[in] env
: API가 호출되는 환경입니다.[in] size
: 기본 버퍼의 바이트 크기입니다.[out] data
: 기본 버퍼에 대한 원시 포인터입니다.data
는NULL
을 전달하여 선택적으로 무시할 수 있습니다.[out] result
:node::Buffer
를 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 node::Buffer
객체를 할당합니다. 이것은 여전히 완벽하게 지원되는 데이터 구조이지만, 대부분의 경우 TypedArray
를 사용해도 충분합니다.
napi_create_buffer_copy
추가됨: v8.0.0
N-API 버전: 1
napi_status napi_create_buffer_copy(napi_env env,
size_t length,
const void* data,
void** result_data,
napi_value* result)
[in] env
: API가 호출되는 환경입니다.[in] size
: 입력 버퍼의 크기(바이트)(새 버퍼의 크기와 같아야 함).[in] data
: 복사할 기본 버퍼에 대한 원시 포인터.[out] result_data
: 새Buffer
의 기본 데이터 버퍼에 대한 포인터.result_data
는NULL
을 전달하여 선택적으로 무시할 수 있습니다.[out] result
:node::Buffer
를 나타내는napi_value
.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 node::Buffer
객체를 할당하고 전달된 버퍼에서 복사된 데이터로 초기화합니다. 이것은 여전히 완벽하게 지원되는 데이터 구조이지만, 대부분의 경우 TypedArray
를 사용해도 충분합니다.
napi_create_date
추가됨: v11.11.0, v10.17.0
N-API 버전: 5
napi_status napi_create_date(napi_env env,
double time,
napi_value* result);
[in] env
: API가 호출되는 환경입니다.[in] time
: 1970년 1월 1일 UTC 이후 밀리초 단위의 ECMAScript 시간 값.[out] result
: JavaScriptDate
를 나타내는napi_value
.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 윤초를 관찰하지 않습니다. ECMAScript가 POSIX 시간 사양과 일치하므로 무시됩니다.
이 API는 JavaScript Date
객체를 할당합니다.
JavaScript Date
객체는 ECMAScript 언어 사양의 20.3절에 설명되어 있습니다.
napi_create_external
추가됨: v8.0.0
N-API 버전: 1
napi_status napi_create_external(napi_env env,
void* data,
napi_finalize finalize_cb,
void* finalize_hint,
napi_value* result)
[in] env
: API가 호출되는 환경입니다.[in] data
: 외부 데이터에 대한 원시 포인터.[in] finalize_cb
: 외부 값이 수집될 때 호출할 선택적 콜백입니다.napi_finalize
에서 자세한 내용을 제공합니다.[in] finalize_hint
: 수집 중에 마무리 콜백에 전달할 선택적 힌트.[out] result
: 외부 값을 나타내는napi_value
.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 외부 데이터가 연결된 JavaScript 값을 할당합니다. 이것은 JavaScript 코드를 통해 외부 데이터를 전달하는 데 사용되므로 나중에 napi_get_value_external
을 사용하여 네이티브 코드에서 검색할 수 있습니다.
API는 생성된 JavaScript 객체가 가비지 수집될 때 호출되는 napi_finalize
콜백을 추가합니다.
생성된 값은 객체가 아니므로 추가 속성을 지원하지 않습니다. 별개의 값 유형으로 간주됩니다. 외부 값을 사용하여 napi_typeof()
를 호출하면 napi_external
이 생성됩니다.
napi_create_external_arraybuffer
추가됨: v8.0.0
N-API 버전: 1
napi_status
napi_create_external_arraybuffer(napi_env env,
void* external_data,
size_t byte_length,
napi_finalize finalize_cb,
void* finalize_hint,
napi_value* result)
[in] env
: API가 호출되는 환경입니다.[in] external_data
:ArrayBuffer
의 기본 바이트 버퍼에 대한 포인터입니다.[in] byte_length
: 기본 버퍼의 바이트 길이입니다.[in] finalize_cb
:ArrayBuffer
가 수거될 때 호출할 선택적 콜백입니다.napi_finalize
에서 자세한 내용을 확인할 수 있습니다.[in] finalize_hint
: 수거 중 finalize 콜백에 전달할 선택적 힌트입니다.[out] result
: JavaScriptArrayBuffer
를 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
Node.js 이외의 일부 런타임에서는 외부 버퍼 지원이 중단되었습니다. Node.js 이외의 런타임에서는 이 메서드가 외부 버퍼가 지원되지 않음을 나타내는 napi_no_external_buffers_allowed
를 반환할 수 있습니다. 이러한 런타임 중 하나는 이 문제 electron/issues/35801에서 설명된 것처럼 Electron입니다.
모든 런타임과의 가장 광범위한 호환성을 유지하려면 노드-API 헤더를 포함하기 전에 애드온에서 NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED
를 정의할 수 있습니다. 이렇게 하면 외부 버퍼를 생성하는 2개의 함수가 숨겨집니다. 이렇게 하면 실수로 이러한 메서드 중 하나를 사용하는 경우 컴파일 오류가 발생합니다.
이 API는 JavaScript ArrayBuffer
에 해당하는 Node-API 값을 반환합니다. ArrayBuffer
의 기본 바이트 버퍼는 외부에서 할당되고 관리됩니다. 호출자는 finalize 콜백이 호출될 때까지 바이트 버퍼가 유효하게 유지되도록 해야 합니다.
API는 방금 생성된 JavaScript 객체가 가비지 수집될 때 호출될 napi_finalize
콜백을 추가합니다.
JavaScript ArrayBuffer
는 ECMAScript 언어 사양의 24.1절에 설명되어 있습니다.
napi_create_external_buffer
추가됨: v8.0.0
N-API 버전: 1
napi_status napi_create_external_buffer(napi_env env,
size_t length,
void* data,
napi_finalize finalize_cb,
void* finalize_hint,
napi_value* result)
[in] env
: API가 호출되는 환경입니다.[in] length
: 입력 버퍼의 크기(바이트)(새 버퍼의 크기와 같아야 함).[in] data
: JavaScript에 노출할 기본 버퍼에 대한 원시 포인터.[in] finalize_cb
:ArrayBuffer
가 수집될 때 호출할 선택적 콜백입니다.napi_finalize
에서 자세한 내용을 확인할 수 있습니다.[in] finalize_hint
: 수집 중 finalize 콜백에 전달할 선택적 힌트.[out] result
:node::Buffer
를 나타내는napi_value
.
API가 성공하면 napi_ok
를 반환합니다.
Node.js 이외의 일부 런타임은 외부 버퍼 지원을 중단했습니다. Node.js 이외의 런타임에서 이 메서드는 외부 버퍼가 지원되지 않음을 나타내는 napi_no_external_buffers_allowed
를 반환할 수 있습니다. 이러한 런타임 중 하나는 이 문제 electron/issues/35801에 설명된 대로 Electron입니다.
모든 런타임과의 최대한의 호환성을 유지하려면 node-api 헤더를 포함하기 전에 애드온에서 NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED
를 정의할 수 있습니다. 그렇게 하면 외부 버퍼를 생성하는 2개의 함수가 숨겨집니다. 이렇게 하면 실수로 이러한 메서드 중 하나를 사용하는 경우 컴파일 오류가 발생합니다.
이 API는 node::Buffer
객체를 할당하고 전달된 버퍼를 백업으로 하는 데이터로 초기화합니다. 이것은 여전히 완전히 지원되는 데이터 구조이지만, 대부분의 경우 TypedArray
를 사용해도 충분합니다.
이 API는 방금 생성된 JavaScript 객체가 가비지 수집된 후 호출되는 napi_finalize
콜백을 추가합니다.
Node.js >=4의 경우 Buffers
는 Uint8Array
입니다.
napi_create_object
추가됨: v8.0.0
N-API 버전: 1
napi_status napi_create_object(napi_env env, napi_value* result)
[in] env
: API가 호출되는 환경입니다.[out] result
: JavaScriptObject
를 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 기본 JavaScript Object
를 할당합니다. JavaScript에서 new Object()
를 하는 것과 같습니다.
JavaScript Object
형식은 ECMAScript 언어 사양의 6.1.7절에 설명되어 있습니다.
napi_create_symbol
추가됨: v8.0.0
N-API 버전: 1
napi_status napi_create_symbol(napi_env env,
napi_value description,
napi_value* result)
[in] env
: API가 호출되는 환경입니다.[in] description
: 심볼의 설명으로 설정될 JavaScriptstring
을 참조하는 선택적napi_value
입니다.[out] result
: JavaScriptsymbol
을 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 UTF8로 인코딩된 C 문자열에서 JavaScript symbol
값을 만듭니다.
JavaScript symbol
형식은 ECMAScript 언어 사양의 19.4절에 설명되어 있습니다.
node_api_symbol_for
추가됨: v17.5.0, v16.15.0
N-API 버전: 9
napi_status node_api_symbol_for(napi_env env,
const char* utf8description,
size_t length,
napi_value* result)
[in] env
: API가 호출되는 환경입니다.[in] utf8description
: 심볼의 설명으로 사용될 텍스트를 나타내는 UTF-8 C 문자열입니다.[in] length
: 설명 문자열의 길이(바이트)입니다. null로 끝나는 경우NAPI_AUTO_LENGTH
입니다.[out] result
: JavaScriptsymbol
을 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 지정된 설명을 가진 기존 심볼을 전역 레지스트리에서 검색합니다. 심볼이 이미 존재하면 반환되고, 그렇지 않으면 레지스트리에 새 심볼이 생성됩니다.
JavaScript symbol
형식은 ECMAScript 언어 사양의 19.4절에 설명되어 있습니다.
napi_create_typedarray
추가됨: v8.0.0
N-API 버전: 1
napi_status napi_create_typedarray(napi_env env,
napi_typedarray_type type,
size_t length,
napi_value arraybuffer,
size_t byte_offset,
napi_value* result)
[in] env
: API가 호출되는 환경입니다.[in] type
:TypedArray
내 요소의 스칼라 데이터 유형입니다.[in] length
:TypedArray
의 요소 개수입니다.[in] arraybuffer
: 형식화된 배열의 기반이 되는ArrayBuffer
입니다.[in] byte_offset
:TypedArray
를 투영할 시작 위치의ArrayBuffer
내 바이트 오프셋입니다.[out] result
: JavaScriptTypedArray
를 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 기존 ArrayBuffer
를 기반으로 JavaScript TypedArray
객체를 생성합니다. TypedArray
객체는 각 요소가 동일한 기본 이진 스칼라 데이터 유형을 갖는 기본 데이터 버퍼에 대한 배열과 같은 뷰를 제공합니다.
(length * size_of_element) + byte_offset
은 전달된 배열의 바이트 크기보다 작거나 같아야 합니다. 그렇지 않으면 RangeError
예외가 발생합니다.
JavaScript TypedArray
객체는 ECMAScript 언어 사양의 22.2절에 설명되어 있습니다.
node_api_create_buffer_from_arraybuffer
추가됨: v23.0.0
napi_status NAPI_CDECL node_api_create_buffer_from_arraybuffer(napi_env env,
napi_value arraybuffer,
size_t byte_offset,
size_t byte_length,
napi_value* result)
[in] env
: API가 호출되는 환경입니다.[in] arraybuffer
: 버퍼가 생성될ArrayBuffer
입니다.[in] byte_offset
: 버퍼 생성을 시작할ArrayBuffer
내 바이트 오프셋입니다.[in] byte_length
:ArrayBuffer
에서 생성할 버퍼의 바이트 길이입니다.[out] result
: 생성된 JavaScriptBuffer
객체를 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 기존 ArrayBuffer
에서 JavaScript Buffer
객체를 생성합니다. Buffer
객체는 Node.js 전용 클래스로 JavaScript에서 이진 데이터를 직접 처리하는 방법을 제공합니다.
바이트 범위 [byte_offset, byte_offset + byte_length)
는 ArrayBuffer
의 경계 내에 있어야 합니다. byte_offset + byte_length
가 ArrayBuffer
의 크기를 초과하면 RangeError
예외가 발생합니다.
napi_create_dataview
추가됨: v8.3.0
N-API 버전: 1
napi_status napi_create_dataview(napi_env env,
size_t byte_length,
napi_value arraybuffer,
size_t byte_offset,
napi_value* result)
[in] env
: API가 호출되는 환경입니다.[in] length
:DataView
의 요소 개수입니다.[in] arraybuffer
:DataView
의 기반이 되는ArrayBuffer
입니다.[in] byte_offset
:ArrayBuffer
내에서DataView
를 투영할 시작 바이트 오프셋입니다.[out] result
: JavaScriptDataView
를 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 기존 ArrayBuffer
를 기반으로 JavaScript DataView
객체를 생성합니다. DataView
객체는 기본 데이터 버퍼에 대한 배열과 같은 뷰를 제공하지만, ArrayBuffer
에 크기와 유형이 다른 항목을 허용합니다.
byte_length + byte_offset
이 전달된 배열의 바이트 크기 이하여야 합니다. 그렇지 않으면 RangeError
예외가 발생합니다.
JavaScript DataView
객체는 ECMAScript 언어 사양의 24.3절에 설명되어 있습니다.
C 유형에서 Node-API로 변환하는 함수
napi_create_int32
추가됨: v8.4.0
N-API 버전: 1
napi_status napi_create_int32(napi_env env, int32_t value, napi_value* result)
[in] env
: API가 호출되는 환경입니다.[in] value
: JavaScript에서 표현될 정수 값입니다.[out] result
: JavaScriptnumber
를 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 C int32_t
유형을 JavaScript number
유형으로 변환하는 데 사용됩니다.
JavaScript number
유형은 ECMAScript 언어 사양의 6.1.6절에 설명되어 있습니다.
napi_create_uint32
추가된 버전: v8.4.0
N-API 버전: 1
napi_status napi_create_uint32(napi_env env, uint32_t value, napi_value* result)
[in] env
: API가 호출되는 환경입니다.[in] value
: JavaScript에 표현될 부호 없는 정수 값입니다.[out] result
: JavaScriptnumber
를 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 C uint32_t
형식에서 JavaScript number
형식으로 변환하는 데 사용됩니다.
JavaScript number
형식은 ECMAScript 언어 사양의 섹션 6.1.6에 설명되어 있습니다.
napi_create_int64
추가된 버전: v8.4.0
N-API 버전: 1
napi_status napi_create_int64(napi_env env, int64_t value, napi_value* result)
[in] env
: API가 호출되는 환경입니다.[in] value
: JavaScript에 표현될 정수 값입니다.[out] result
: JavaScriptnumber
를 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 C int64_t
형식에서 JavaScript number
형식으로 변환하는 데 사용됩니다.
JavaScript number
형식은 ECMAScript 언어 사양의 섹션 6.1.6에 설명되어 있습니다. int64_t
의 전체 범위는 JavaScript에서 완전한 정밀도로 표현할 수 없습니다. Number.MIN_SAFE_INTEGER
-(2**53 - 1)
- Number.MAX_SAFE_INTEGER
(2**53 - 1)
범위를 벗어나는 정수 값은 정밀도를 잃게 됩니다.
napi_create_double
추가된 버전: v8.4.0
N-API 버전: 1
napi_status napi_create_double(napi_env env, double value, napi_value* result)
[in] env
: API가 호출되는 환경입니다.[in] value
: JavaScript에 표현될 배정밀도 값입니다.[out] result
: JavaScriptnumber
를 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 C double
형식에서 JavaScript number
형식으로 변환하는 데 사용됩니다.
JavaScript number
형식은 ECMAScript 언어 사양의 섹션 6.1.6에 설명되어 있습니다.
napi_create_bigint_int64
추가 버전: v10.7.0
N-API 버전: 6
napi_status napi_create_bigint_int64(napi_env env,
int64_t value,
napi_value* result);
[in] env
: API가 호출되는 환경입니다.[in] value
: JavaScript에 표시될 정수 값입니다.[out] result
: JavaScriptBigInt
를 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 C int64_t
형식을 JavaScript BigInt
형식으로 변환합니다.
napi_create_bigint_uint64
추가 버전: v10.7.0
N-API 버전: 6
napi_status napi_create_bigint_uint64(napi_env env,
uint64_t value,
napi_value* result);
[in] env
: API가 호출되는 환경입니다.[in] value
: JavaScript에 표시될 부호 없는 정수 값입니다.[out] result
: JavaScriptBigInt
를 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 C uint64_t
형식을 JavaScript BigInt
형식으로 변환합니다.
napi_create_bigint_words
추가 버전: v10.7.0
N-API 버전: 6
napi_status napi_create_bigint_words(napi_env env,
int sign_bit,
size_t word_count,
const uint64_t* words,
napi_value* result);
[in] env
: API가 호출되는 환경입니다.[in] sign_bit
: 결과BigInt
가 양수인지 음수인지 결정합니다.[in] word_count
:words
배열의 길이입니다.[in] words
: little-endian 64비트 단어의uint64_t
배열입니다.[out] result
: JavaScriptBigInt
를 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 부호 없는 64비트 단어 배열을 단일 BigInt
값으로 변환합니다.
결과 BigInt
는 다음과 같이 계산됩니다: (–1) (words[0]
× (2) + words[1]
× (2) + …)
napi_create_string_latin1
추가된 버전: v8.0.0
N-API 버전: 1
napi_status napi_create_string_latin1(napi_env env,
const char* str,
size_t length,
napi_value* result);
[in] env
: API가 호출된 환경입니다.[in] str
: ISO-8859-1 인코딩된 문자열을 나타내는 문자 버퍼입니다.[in] length
: 바이트 단위의 문자열 길이입니다. null로 끝나는 경우NAPI_AUTO_LENGTH
입니다.[out] result
: JavaScriptstring
을 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 ISO-8859-1 인코딩된 C 문자열에서 JavaScript string
값을 생성합니다. 네이티브 문자열은 복사됩니다.
JavaScript string
타입은 ECMAScript 언어 사양의 섹션 6.1.4에 설명되어 있습니다.
node_api_create_external_string_latin1
추가된 버전: v20.4.0, v18.18.0
napi_status
node_api_create_external_string_latin1(napi_env env,
char* str,
size_t length,
napi_finalize finalize_callback,
void* finalize_hint,
napi_value* result,
bool* copied);
[in] env
: API가 호출된 환경입니다.[in] str
: ISO-8859-1 인코딩된 문자열을 나타내는 문자 버퍼입니다.[in] length
: 바이트 단위의 문자열 길이입니다. null로 끝나는 경우NAPI_AUTO_LENGTH
입니다.[in] finalize_callback
: 문자열이 수집될 때 호출되는 함수입니다. 이 함수는 다음 매개변수를 사용하여 호출됩니다.[in] env
: 애드온이 실행 중인 환경입니다. 이 값은 문자열이 워커 또는 메인 Node.js 인스턴스 종료의 일부로 수집되는 경우 null일 수 있습니다.[in] data
:void*
포인터인 값str
입니다.[in] finalize_hint
: API에 제공된 값finalize_hint
입니다.napi_finalize
에서 자세한 정보를 제공합니다. 이 매개변수는 선택 사항입니다. null 값을 전달하면 해당 JavaScript 문자열이 수집될 때 애드온에 알릴 필요가 없음을 의미합니다.
[in] finalize_hint
: 수집 중 최종화 콜백에 전달할 선택적 힌트입니다.[out] result
: JavaScriptstring
을 나타내는napi_value
입니다.[out] copied
: 문자열이 복사되었는지 여부입니다. 복사된 경우, finalizer가 이미 호출되어str
을 파괴했을 것입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 ISO-8859-1 인코딩된 C 문자열에서 JavaScript string
값을 생성합니다. 네이티브 문자열은 복사되지 않을 수 있으며 따라서 JavaScript 값의 전체 수명 동안 존재해야 합니다.
JavaScript string
타입은 ECMAScript 언어 사양의 섹션 6.1.4에 설명되어 있습니다.
napi_create_string_utf16
추가된 버전: v8.0.0
N-API 버전: 1
napi_status napi_create_string_utf16(napi_env env,
const char16_t* str,
size_t length,
napi_value* result)
[in] env
: API가 호출되는 환경입니다.[in] str
: UTF16-LE 인코딩된 문자열을 나타내는 문자 버퍼입니다.[in] length
: 두 바이트 코드 단위로 된 문자열의 길이입니다. null로 종료되는 경우NAPI_AUTO_LENGTH
를 사용합니다.[out] result
: JavaScriptstring
을 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 UTF16-LE 인코딩된 C 문자열에서 JavaScript string
값을 생성합니다. 네이티브 문자열이 복사됩니다.
JavaScript string
유형은 ECMAScript 언어 사양의 섹션 6.1.4에 설명되어 있습니다.
node_api_create_external_string_utf16
추가된 버전: v20.4.0, v18.18.0
napi_status
node_api_create_external_string_utf16(napi_env env,
char16_t* str,
size_t length,
napi_finalize finalize_callback,
void* finalize_hint,
napi_value* result,
bool* copied);
[in] env
: API가 호출되는 환경입니다.[in] str
: UTF16-LE 인코딩된 문자열을 나타내는 문자 버퍼입니다.[in] length
: 두 바이트 코드 단위로 된 문자열의 길이입니다. null로 종료되는 경우NAPI_AUTO_LENGTH
를 사용합니다.[in] finalize_callback
: 문자열이 수집될 때 호출할 함수입니다. 이 함수는 다음 매개변수로 호출됩니다.[in] env
: 애드온이 실행 중인 환경입니다. 이 값은 문자열이 워커 또는 기본 Node.js 인스턴스의 종료의 일부로 수집되는 경우 null일 수 있습니다.[in] data
:void*
포인터인str
값입니다.[in] finalize_hint
: API에 제공된finalize_hint
값입니다.napi_finalize
에서 더 자세한 내용을 제공합니다. 이 매개변수는 선택 사항입니다. null 값을 전달하면 해당 JavaScript 문자열이 수집될 때 애드온에 알릴 필요가 없음을 의미합니다.
[in] finalize_hint
: 수집 중에 finalize 콜백에 전달할 선택적 힌트입니다.[out] result
: JavaScriptstring
을 나타내는napi_value
입니다.[out] copied
: 문자열이 복사되었는지 여부입니다. 복사된 경우 finalizer가 이미str
을 삭제하기 위해 호출되었습니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 UTF16-LE 인코딩된 C 문자열에서 JavaScript string
값을 생성합니다. 네이티브 문자열은 복사되지 않을 수 있으므로 JavaScript 값의 전체 수명 주기 동안 존재해야 합니다.
JavaScript string
유형은 ECMAScript 언어 사양의 섹션 6.1.4에 설명되어 있습니다.
napi_create_string_utf8
추가된 버전: v8.0.0
N-API 버전: 1
napi_status napi_create_string_utf8(napi_env env,
const char* str,
size_t length,
napi_value* result)
[in] env
: API가 호출되는 환경입니다.[in] str
: UTF8로 인코딩된 문자열을 나타내는 문자 버퍼입니다.[in] length
: 바이트 단위의 문자열 길이이거나, null로 종료된 경우NAPI_AUTO_LENGTH
입니다.[out] result
: JavaScriptstring
을 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 UTF8로 인코딩된 C 문자열에서 JavaScript string
값을 생성합니다. 네이티브 문자열은 복사됩니다.
JavaScript string
유형은 ECMAScript 언어 사양의 섹션 6.1.4에 설명되어 있습니다.
최적화된 속성 키를 생성하는 함수
V8을 포함한 많은 JavaScript 엔진은 내부화된 문자열을 속성 값을 설정하고 가져오는 키로 사용합니다. 일반적으로 해시 테이블을 사용하여 이러한 문자열을 생성하고 조회합니다. 키 생성당 약간의 비용이 추가되지만 전체 문자열 대신 문자열 포인터 비교를 가능하게 하여 이후 성능을 향상시킵니다.
새 JavaScript 문자열을 속성 키로 사용하려는 경우 일부 JavaScript 엔진의 경우 이 섹션의 함수를 사용하는 것이 더 효율적입니다. 그렇지 않으면 속성 키 생성 방법으로 문자열을 만들고 저장하는 데 추가 오버헤드가 있을 수 있으므로 napi_create_string_utf8
또는 node_api_create_external_string_utf8
시리즈 함수를 사용하세요.
node_api_create_property_key_latin1
추가된 버전: v22.9.0, v20.18.0
napi_status NAPI_CDECL node_api_create_property_key_latin1(napi_env env,
const char* str,
size_t length,
napi_value* result);
[in] env
: API가 호출되는 환경입니다.[in] str
: ISO-8859-1로 인코딩된 문자열을 나타내는 문자 버퍼입니다.[in] length
: 바이트 단위의 문자열 길이이거나, null로 종료된 경우NAPI_AUTO_LENGTH
입니다.[out] result
: 객체의 속성 키로 사용될 최적화된 JavaScriptstring
을 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 객체의 속성 키로 사용될 ISO-8859-1로 인코딩된 C 문자열에서 최적화된 JavaScript string
값을 생성합니다. 네이티브 문자열은 복사됩니다. napi_create_string_latin1
과 달리 동일한 str
포인터로 이 함수를 후속 호출하면 엔진에 따라 요청된 napi_value
생성 속도가 빨라질 수 있습니다.
JavaScript string
유형은 ECMAScript 언어 사양의 섹션 6.1.4에 설명되어 있습니다.
node_api_create_property_key_utf16
추가 버전: v21.7.0, v20.12.0
napi_status NAPI_CDECL node_api_create_property_key_utf16(napi_env env,
const char16_t* str,
size_t length,
napi_value* result);
[in] env
: API가 호출되는 환경입니다.[in] str
: UTF16-LE로 인코딩된 문자열을 나타내는 문자 버퍼입니다.[in] length
: 문자열의 길이를 2바이트 코드 단위로 나타냅니다. null로 끝나는 문자열의 경우NAPI_AUTO_LENGTH
입니다.[out] result
: 객체의 속성 키로 사용될 최적화된 JavaScriptstring
을 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 객체의 속성 키로 사용될 UTF16-LE로 인코딩된 C 문자열에서 최적화된 JavaScript string
값을 만듭니다. 네이티브 문자열은 복사됩니다.
JavaScript string
유형은 ECMAScript 언어 사양의 섹션 6.1.4에 설명되어 있습니다.
node_api_create_property_key_utf8
추가 버전: v22.9.0, v20.18.0
napi_status NAPI_CDECL node_api_create_property_key_utf8(napi_env env,
const char* str,
size_t length,
napi_value* result);
[in] env
: API가 호출되는 환경입니다.[in] str
: UTF8로 인코딩된 문자열을 나타내는 문자 버퍼입니다.[in] length
: 문자열의 길이를 2바이트 코드 단위로 나타냅니다. null로 끝나는 문자열의 경우NAPI_AUTO_LENGTH
입니다.[out] result
: 객체의 속성 키로 사용될 최적화된 JavaScriptstring
을 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 객체의 속성 키로 사용될 UTF8로 인코딩된 C 문자열에서 최적화된 JavaScript string
값을 만듭니다. 네이티브 문자열은 복사됩니다.
JavaScript string
유형은 ECMAScript 언어 사양의 섹션 6.1.4에 설명되어 있습니다.
Node-API에서 C 타입으로 변환하는 함수
napi_get_array_length
추가 버전: v8.0.0
N-API 버전: 1
napi_status napi_get_array_length(napi_env env,
napi_value value,
uint32_t* result)
[in] env
: API가 호출되는 환경입니다.[in] value
: 길이를 조회할 JavaScriptArray
를 나타내는napi_value
입니다.[out] result
: 배열의 길이를 나타내는uint32
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 배열의 길이를 반환합니다.
Array
길이는 ECMAScript 언어 사양의 섹션 22.1.4.1에 설명되어 있습니다.
napi_get_arraybuffer_info
추가 버전: v8.0.0
N-API 버전: 1
napi_status napi_get_arraybuffer_info(napi_env env,
napi_value arraybuffer,
void** data,
size_t* byte_length)
[in] env
: API가 호출되는 환경입니다.[in] arraybuffer
: 조회할ArrayBuffer
를 나타내는napi_value
입니다.[out] data
:ArrayBuffer
의 기본 데이터 버퍼입니다. byte_length가0
이면NULL
또는 다른 포인터 값일 수 있습니다.[out] byte_length
: 기본 데이터 버퍼의 바이트 단위 길이입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 ArrayBuffer
의 기본 데이터 버퍼와 길이를 검색하는 데 사용됩니다.
경고: 이 API를 사용하는 동안 주의하십시오. 기본 데이터 버퍼의 수명은 반환된 후에도 ArrayBuffer
에 의해 관리됩니다. 이 API를 안전하게 사용할 수 있는 한 가지 방법은 ArrayBuffer
의 수명에 대한 제어를 보장하는 데 사용할 수 있는 napi_create_reference
와 함께 사용하는 것입니다. GC를 트리거할 수 있는 다른 API 호출이 없는 한 동일한 콜백 내에서 반환된 데이터 버퍼를 사용하는 것도 안전합니다.
napi_get_buffer_info
추가된 버전: v8.0.0
N-API 버전: 1
napi_status napi_get_buffer_info(napi_env env,
napi_value value,
void** data,
size_t* length)
[in] env
: API가 호출되는 환경입니다.[in] value
: 쿼리할node::Buffer
또는Uint8Array
를 나타내는napi_value
입니다.[out] data
:node::Buffer
또는Uint8Array
의 기본 데이터 버퍼입니다. 길이가0
이면NULL
이거나 다른 포인터 값일 수 있습니다.[out] length
: 기본 데이터 버퍼의 바이트 단위 길이입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 메서드는 napi_get_typedarray_info
와 동일한 data
및 byte_length
를 반환합니다. 또한 napi_get_typedarray_info
는 node::Buffer
(Uint8Array)를 값으로 허용합니다.
이 API는 node::Buffer
의 기본 데이터 버퍼와 길이를 검색하는 데 사용됩니다.
경고: 이 API를 사용할 때 기본 데이터 버퍼의 수명이 VM에 의해 관리되는 경우 보장되지 않으므로 주의하십시오.
napi_get_prototype
추가된 버전: v8.0.0
N-API 버전: 1
napi_status napi_get_prototype(napi_env env,
napi_value object,
napi_value* result)
[in] env
: API가 호출되는 환경입니다.[in] object
: 반환할 프로토타입을 가진 JavaScriptObject
를 나타내는napi_value
입니다. 이는Object.getPrototypeOf
와 동일한 값을 반환합니다(함수의prototype
속성과는 다름).[out] result
: 지정된 객체의 프로토타입을 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
napi_get_typedarray_info
추가된 버전: v8.0.0
N-API 버전: 1
napi_status napi_get_typedarray_info(napi_env env,
napi_value typedarray,
napi_typedarray_type* type,
size_t* length,
void** data,
napi_value* arraybuffer,
size_t* byte_offset)
[in] env
: API가 호출되는 환경입니다.[in] typedarray
: 쿼리할 속성을 가진TypedArray
를 나타내는napi_value
입니다.[out] type
:TypedArray
내의 요소의 스칼라 데이터 유형입니다.[out] length
:TypedArray
내의 요소 수입니다.[out] data
:TypedArray
의 첫 번째 요소를 가리키도록byte_offset
값으로 조정된TypedArray
의 기본 데이터 버퍼입니다. 배열의 길이가0
이면NULL
이거나 다른 포인터 값일 수 있습니다.[out] arraybuffer
:TypedArray
의 기본ArrayBuffer
입니다.[out] byte_offset
: 배열의 첫 번째 요소가 있는 기본 네이티브 배열 내의 바이트 오프셋입니다. 데이터 매개변수 값은 이미 조정되어 데이터가 배열의 첫 번째 요소를 가리키고 있습니다. 따라서 네이티브 배열의 첫 번째 바이트는data - byte_offset
에 있습니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 typed array의 다양한 속성을 반환합니다.
해당 속성이 필요하지 않으면 출력 매개변수 중 아무거나 NULL
이 될 수 있습니다.
경고: 기본 데이터 버퍼는 VM에 의해 관리되므로 이 API를 사용할 때 주의하십시오.
napi_get_dataview_info
추가 버전: v8.3.0
N-API 버전: 1
napi_status napi_get_dataview_info(napi_env env,
napi_value dataview,
size_t* byte_length,
void** data,
napi_value* arraybuffer,
size_t* byte_offset)
[in] env
: API가 호출되는 환경입니다.[in] dataview
: 속성을 조회할DataView
를 나타내는napi_value
입니다.[out] byte_length
:DataView
의 바이트 수입니다.[out] data
:DataView
의 기본 데이터 버퍼입니다. byte_length가0
인 경우,NULL
또는 다른 포인터 값일 수 있습니다.[out] arraybuffer
:DataView
의 기본ArrayBuffer
입니다.[out] byte_offset
:DataView
프로젝션을 시작할 데이터 버퍼 내 바이트 오프셋입니다.
API가 성공하면 napi_ok
를 반환합니다.
해당 속성이 필요하지 않으면 출력 매개변수 중 어느 것이든 NULL
이 될 수 있습니다.
이 API는 DataView
의 다양한 속성을 반환합니다.
napi_get_date_value
추가 버전: v11.11.0, v10.17.0
N-API 버전: 5
napi_status napi_get_date_value(napi_env env,
napi_value value,
double* result)
[in] env
: API가 호출되는 환경입니다.[in] value
: JavaScriptDate
를 나타내는napi_value
입니다.[out] result
: 1970년 1월 1일 0시 UTC를 기준으로 한 밀리초 단위의 시간 값(double)입니다.
이 API는 윤초를 고려하지 않습니다. ECMAScript는 POSIX 시간 사양에 맞춰 윤초를 무시합니다.
API가 성공하면 napi_ok
를 반환합니다. 날짜가 아닌 napi_value
가 전달되면 napi_date_expected
를 반환합니다.
이 API는 주어진 JavaScript Date
의 시간 값에 대한 C double 기본형을 반환합니다.
napi_get_value_bool
추가 버전: v8.0.0
N-API 버전: 1
napi_status napi_get_value_bool(napi_env env, napi_value value, bool* result)
[in] env
: API가 호출되는 환경입니다.[in] value
: JavaScriptBoolean
을 나타내는napi_value
입니다.[out] result
: 주어진 JavaScriptBoolean
과 동일한 C 부울 기본형입니다.
API가 성공하면 napi_ok
를 반환합니다. 부울이 아닌 napi_value
가 전달되면 napi_boolean_expected
를 반환합니다.
이 API는 주어진 JavaScript Boolean
과 동일한 C 부울 기본형을 반환합니다.
napi_get_value_double
추가됨: v8.0.0
N-API 버전: 1
napi_status napi_get_value_double(napi_env env,
napi_value value,
double* result)
[in] env
: API가 호출되는 환경입니다.[in] value
: JavaScriptnumber
를 나타내는napi_value
입니다.[out] result
: 주어진 JavaScriptnumber
와 동등한 C double 기본형입니다.
API가 성공하면 napi_ok
를 반환합니다. 숫자가 아닌 napi_value
가 전달되면 napi_number_expected
를 반환합니다.
이 API는 주어진 JavaScript number
와 동등한 C double 기본형을 반환합니다.
napi_get_value_bigint_int64
추가됨: v10.7.0
N-API 버전: 6
napi_status napi_get_value_bigint_int64(napi_env env,
napi_value value,
int64_t* result,
bool* lossless);
[in] env
: API가 호출되는 환경입니다.[in] value
: JavaScriptBigInt
를 나타내는napi_value
입니다.[out] result
: 주어진 JavaScriptBigInt
와 동등한 Cint64_t
기본형입니다.[out] lossless
:BigInt
값이 손실 없이 변환되었는지 여부를 나타냅니다.
API가 성공하면 napi_ok
를 반환합니다. BigInt
가 아닌 값이 전달되면 napi_bigint_expected
를 반환합니다.
이 API는 주어진 JavaScript BigInt
와 동등한 C int64_t
기본형을 반환합니다. 필요한 경우 값을 자르고 lossless
를 false
로 설정합니다.
napi_get_value_bigint_uint64
추가됨: v10.7.0
N-API 버전: 6
napi_status napi_get_value_bigint_uint64(napi_env env,
napi_value value,
uint64_t* result,
bool* lossless);
[in] env
: API가 호출되는 환경입니다.[in] value
: JavaScriptBigInt
를 나타내는napi_value
입니다.[out] result
: 주어진 JavaScriptBigInt
와 동등한 Cuint64_t
기본형입니다.[out] lossless
:BigInt
값이 손실 없이 변환되었는지 여부를 나타냅니다.
API가 성공하면 napi_ok
를 반환합니다. BigInt
가 아닌 값이 전달되면 napi_bigint_expected
를 반환합니다.
이 API는 주어진 JavaScript BigInt
와 동등한 C uint64_t
기본형을 반환합니다. 필요한 경우 값을 자르고 lossless
를 false
로 설정합니다.
napi_get_value_bigint_words
추가된 버전: v10.7.0
N-API 버전: 6
napi_status napi_get_value_bigint_words(napi_env env,
napi_value value,
int* sign_bit,
size_t* word_count,
uint64_t* words);
[in] env
: API가 호출되는 환경입니다.[in] value
: JavaScriptBigInt
를 나타내는napi_value
입니다.[out] sign_bit
: JavaScriptBigInt
가 양수인지 음수인지 나타내는 정수입니다.[in/out] word_count
:words
배열의 길이로 초기화해야 합니다. 반환 시 이BigInt
를 저장하는 데 필요한 실제 단어 수로 설정됩니다.[out] words
: 미리 할당된 64비트 단어 배열에 대한 포인터입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 단일 BigInt
값을 부호 비트, 64비트 리틀 엔디안 배열 및 배열의 요소 수로 변환합니다. word_count
만 얻기 위해 sign_bit
와 words
를 모두 NULL
로 설정할 수 있습니다.
napi_get_value_external
추가된 버전: v8.0.0
N-API 버전: 1
napi_status napi_get_value_external(napi_env env,
napi_value value,
void** result)
[in] env
: API가 호출되는 환경입니다.[in] value
: JavaScript 외부 값을 나타내는napi_value
입니다.[out] result
: JavaScript 외부 값으로 래핑된 데이터에 대한 포인터입니다.
API가 성공하면 napi_ok
를 반환합니다. 외부가 아닌 napi_value
가 전달되면 napi_invalid_arg
를 반환합니다.
이 API는 이전에 napi_create_external()
에 전달된 외부 데이터 포인터를 검색합니다.
napi_get_value_int32
추가된 버전: v8.0.0
N-API 버전: 1
napi_status napi_get_value_int32(napi_env env,
napi_value value,
int32_t* result)
[in] env
: API가 호출되는 환경입니다.[in] value
: JavaScriptnumber
를 나타내는napi_value
입니다.[out] result
: 주어진 JavaScriptnumber
에 해당하는 Cint32
기본형입니다.
API가 성공하면 napi_ok
를 반환합니다. 숫자가 아닌 napi_value
가 전달되면 napi_number_expected
가 반환됩니다.
이 API는 주어진 JavaScript number
에 해당하는 C int32
기본형을 반환합니다.
숫자가 32비트 정수 범위를 초과하면 결과는 하위 32비트에 해당하는 값으로 잘립니다. 이로 인해 값이 > 2 - 1인 경우 큰 양수가 음수가 될 수 있습니다.
비유한 숫자 값(NaN
, +Infinity
또는 -Infinity
)은 결과를 0으로 설정합니다.
napi_get_value_int64
추가 버전: v8.0.0
N-API 버전: 1
napi_status napi_get_value_int64(napi_env env,
napi_value value,
int64_t* result)
[in] env
: API가 호출되는 환경입니다.[in] value
: JavaScriptnumber
를 나타내는napi_value
입니다.[out] result
: 주어진 JavaScriptnumber
에 해당하는 Cint64
기본형입니다.
API가 성공하면 napi_ok
를 반환합니다. 숫자가 아닌 napi_value
가 전달되면 napi_number_expected
를 반환합니다.
이 API는 주어진 JavaScript number
에 해당하는 C int64
기본형을 반환합니다.
Number.MIN_SAFE_INTEGER
-(2**53 - 1)
- Number.MAX_SAFE_INTEGER
(2**53 - 1)
범위 밖의 number
값은 정밀도가 손실됩니다.
유한하지 않은 숫자 값(NaN
, +Infinity
또는 -Infinity
)은 결과를 0으로 설정합니다.
napi_get_value_string_latin1
추가 버전: v8.0.0
N-API 버전: 1
napi_status napi_get_value_string_latin1(napi_env env,
napi_value value,
char* buf,
size_t bufsize,
size_t* result)
[in] env
: API가 호출되는 환경입니다.[in] value
: JavaScript 문자열을 나타내는napi_value
입니다.[in] buf
: ISO-8859-1로 인코딩된 문자열을 쓸 버퍼입니다.NULL
이 전달되면 null 종결자를 제외한 바이트 단위 문자열의 길이가result
에 반환됩니다.[in] bufsize
: 대상 버퍼의 크기입니다. 이 값이 부족하면 반환된 문자열이 잘리고 null로 종료됩니다.[out] result
: null 종결자를 제외하고 버퍼에 복사된 바이트 수입니다.
API가 성공하면 napi_ok
를 반환합니다. string
이 아닌 napi_value
가 전달되면 napi_string_expected
를 반환합니다.
이 API는 전달된 값에 해당하는 ISO-8859-1로 인코딩된 문자열을 반환합니다.
napi_get_value_string_utf8
추가됨: v8.0.0
N-API 버전: 1
napi_status napi_get_value_string_utf8(napi_env env,
napi_value value,
char* buf,
size_t bufsize,
size_t* result)
[in] env
: API가 호출되는 환경입니다.[in] value
: JavaScript 문자열을 나타내는napi_value
입니다.[in] buf
: UTF8로 인코딩된 문자열을 쓸 버퍼입니다.NULL
이 전달되면, 널 종결자를 제외한 문자열의 바이트 길이가result
에 반환됩니다.[in] bufsize
: 대상 버퍼의 크기입니다. 이 값이 충분하지 않으면, 반환된 문자열은 잘리고 널로 끝납니다.[out] result
: 널 종결자를 제외하고 버퍼에 복사된 바이트 수입니다.
API가 성공하면 napi_ok
를 반환합니다. string
이 아닌 napi_value
가 전달되면 napi_string_expected
를 반환합니다.
이 API는 전달된 값에 해당하는 UTF8로 인코딩된 문자열을 반환합니다.
napi_get_value_string_utf16
추가됨: v8.0.0
N-API 버전: 1
napi_status napi_get_value_string_utf16(napi_env env,
napi_value value,
char16_t* buf,
size_t bufsize,
size_t* result)
[in] env
: API가 호출되는 환경입니다.[in] value
: JavaScript 문자열을 나타내는napi_value
입니다.[in] buf
: UTF16-LE로 인코딩된 문자열을 쓸 버퍼입니다.NULL
이 전달되면, 널 종결자를 제외한 문자열의 2바이트 코드 단위 길이가 반환됩니다.[in] bufsize
: 대상 버퍼의 크기입니다. 이 값이 충분하지 않으면, 반환된 문자열은 잘리고 널로 끝납니다.[out] result
: 널 종결자를 제외하고 버퍼에 복사된 2바이트 코드 단위 수입니다.
API가 성공하면 napi_ok
를 반환합니다. string
이 아닌 napi_value
가 전달되면 napi_string_expected
를 반환합니다.
이 API는 전달된 값에 해당하는 UTF16으로 인코딩된 문자열을 반환합니다.
napi_get_value_uint32
추가됨: v8.0.0
N-API 버전: 1
napi_status napi_get_value_uint32(napi_env env,
napi_value value,
uint32_t* result)
[in] env
: API가 호출되는 환경입니다.[in] value
: JavaScriptnumber
를 나타내는napi_value
입니다.[out] result
: 주어진napi_value
의 C 기본형과 동일한uint32_t
입니다.
API가 성공하면 napi_ok
를 반환합니다. 숫자가 아닌 napi_value
가 전달되면 napi_number_expected
를 반환합니다.
이 API는 주어진 napi_value
의 C 기본형과 동일한 값을 uint32_t
로 반환합니다.
전역 인스턴스를 가져오는 함수
napi_get_boolean
추가됨: v8.0.0
N-API 버전: 1
napi_status napi_get_boolean(napi_env env, bool value, napi_value* result)
[in] env
: API가 호출되는 환경입니다.[in] value
: 가져올 부울 값입니다.[out] result
: 가져올 JavaScriptBoolean
싱글톤을 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 주어진 부울 값을 나타내는 데 사용되는 JavaScript 싱글톤 객체를 반환하는 데 사용됩니다.
napi_get_global
추가됨: v8.0.0
N-API 버전: 1
napi_status napi_get_global(napi_env env, napi_value* result)
[in] env
: API가 호출되는 환경입니다.[out] result
: JavaScriptglobal
객체를 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 global
객체를 반환합니다.
napi_get_null
추가됨: v8.0.0
N-API 버전: 1
napi_status napi_get_null(napi_env env, napi_value* result)
[in] env
: API가 호출되는 환경입니다.[out] result
: JavaScriptnull
객체를 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 null
객체를 반환합니다.
napi_get_undefined
추가됨: v8.0.0
N-API 버전: 1
napi_status napi_get_undefined(napi_env env, napi_value* result)
[in] env
: API가 호출되는 환경입니다.[out] result
: JavaScript Undefined 값을 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 Undefined 객체를 반환합니다.
JavaScript 값 및 추상 연산 작업
Node-API는 JavaScript 값에 대한 일부 추상 연산을 수행하는 API 세트를 노출합니다. 이러한 연산 중 일부는 ECMAScript 언어 사양의 섹션 7에 문서화되어 있습니다.
이러한 API는 다음 중 하나를 수행하는 것을 지원합니다.
napi_coerce_to_bool
추가 버전: v8.0.0
N-API 버전: 1
napi_status napi_coerce_to_bool(napi_env env,
napi_value value,
napi_value* result)
[in] env
: API가 호출되는 환경입니다.[in] value
: 강제 변환할 JavaScript 값입니다.[out] result
: 강제 변환된 JavaScriptBoolean
을 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 ECMAScript 언어 사양의 섹션 7.1.2에 정의된 추상 연산 ToBoolean()
을 구현합니다.
napi_coerce_to_number
추가 버전: v8.0.0
N-API 버전: 1
napi_status napi_coerce_to_number(napi_env env,
napi_value value,
napi_value* result)
[in] env
: API가 호출되는 환경입니다.[in] value
: 강제 변환할 JavaScript 값입니다.[out] result
: 강제 변환된 JavaScriptnumber
를 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 ECMAScript 언어 사양의 섹션 7.1.3에 정의된 추상 연산 ToNumber()
를 구현합니다. 이 함수는 전달된 값이 객체인 경우 잠재적으로 JS 코드를 실행합니다.
napi_coerce_to_object
추가 버전: v8.0.0
N-API 버전: 1
napi_status napi_coerce_to_object(napi_env env,
napi_value value,
napi_value* result)
[in] env
: API가 호출되는 환경입니다.[in] value
: 강제 변환할 JavaScript 값입니다.[out] result
: 강제 변환된 JavaScriptObject
를 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 ECMAScript 언어 사양의 섹션 7.1.13에 정의된 추상 연산 ToObject()
를 구현합니다.
napi_coerce_to_string
추가됨: v8.0.0
N-API 버전: 1
napi_status napi_coerce_to_string(napi_env env,
napi_value value,
napi_value* result)
[in] env
: API가 호출되는 환경입니다.[in] value
: 강제 변환할 JavaScript 값입니다.[out] result
: 강제 변환된 JavaScriptstring
을 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 ECMAScript 언어 사양의 섹션 7.1.13에 정의된 추상 연산 ToString()
을 구현합니다. 이 함수는 전달된 값이 객체인 경우 JS 코드를 실행할 가능성이 있습니다.
napi_typeof
추가됨: v8.0.0
N-API 버전: 1
napi_status napi_typeof(napi_env env, napi_value value, napi_valuetype* result)
[in] env
: API가 호출되는 환경입니다.[in] value
: 형식을 쿼리할 JavaScript 값입니다.[out] result
: JavaScript 값의 형식입니다.
API가 성공하면 napi_ok
를 반환합니다.
value
의 형식이 알려진 ECMAScript 형식이 아니고value
가 외부 값이 아니면napi_invalid_arg
입니다.
이 API는 ECMAScript 언어 사양의 섹션 12.5.5에 정의된 객체에서 typeof
연산자를 호출하는 것과 유사한 동작을 나타냅니다. 그러나 몇 가지 차이점이 있습니다.
value
에 유효하지 않은 형식이 있으면 오류가 반환됩니다.
napi_instanceof
추가됨: v8.0.0
N-API 버전: 1
napi_status napi_instanceof(napi_env env,
napi_value object,
napi_value constructor,
bool* result)
[in] env
: API가 호출되는 환경입니다.[in] object
: 확인할 JavaScript 값입니다.[in] constructor
: 확인할 생성자 함수의 JavaScript 함수 객체입니다.[out] result
:object instanceof constructor
가 참이면 true로 설정되는 부울 값입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 ECMAScript 언어 사양의 섹션 12.10.4에 정의된 객체에서 instanceof
연산자를 호출하는 것을 나타냅니다.
napi_is_array
추가된 버전: v8.0.0
N-API 버전: 1
napi_status napi_is_array(napi_env env, napi_value value, bool* result)
[in] env
: API가 호출되는 환경입니다.[in] value
: 확인할 JavaScript 값입니다.[out] result
: 주어진 객체가 배열인지 여부입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 ECMAScript 언어 사양의 섹션 7.2.2에 정의된 대로 객체에서 IsArray
작업을 호출하는 것을 나타냅니다.
napi_is_arraybuffer
추가된 버전: v8.0.0
N-API 버전: 1
napi_status napi_is_arraybuffer(napi_env env, napi_value value, bool* result)
[in] env
: API가 호출되는 환경입니다.[in] value
: 확인할 JavaScript 값입니다.[out] result
: 주어진 객체가ArrayBuffer
인지 여부입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 전달된 Object
가 ArrayBuffer인지 확인합니다.
napi_is_buffer
추가된 버전: v8.0.0
N-API 버전: 1
napi_status napi_is_buffer(napi_env env, napi_value value, bool* result)
[in] env
: API가 호출되는 환경입니다.[in] value
: 확인할 JavaScript 값입니다.[out] result
: 주어진napi_value
가node::Buffer
또는Uint8Array
객체를 나타내는지 여부입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 전달된 Object
가 버퍼 또는 Uint8Array인지 확인합니다. 호출자가 값이 Uint8Array인지 확인해야 하는 경우 napi_is_typedarray
를 사용하는 것이 좋습니다.
napi_is_date
추가된 버전: v11.11.0, v10.17.0
N-API 버전: 5
napi_status napi_is_date(napi_env env, napi_value value, bool* result)
[in] env
: API가 호출되는 환경입니다.[in] value
: 확인할 JavaScript 값입니다.[out] result
: 주어진napi_value
가 JavaScriptDate
객체를 나타내는지 여부입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 전달된 Object
가 날짜인지 확인합니다.
napi_is_error
추가된 버전: v8.0.0
N-API 버전: 1
napi_status napi_is_error(napi_env env, napi_value value, bool* result)
[in] env
: API가 호출되는 환경입니다.[in] value
: 확인할 JavaScript 값입니다.[out] result
: 주어진napi_value
가Error
객체를 나타내는지 여부입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 전달된 Object
가 Error
인지 확인합니다.
napi_is_typedarray
추가된 버전: v8.0.0
N-API 버전: 1
napi_status napi_is_typedarray(napi_env env, napi_value value, bool* result)
[in] env
: API가 호출되는 환경입니다.[in] value
: 확인할 JavaScript 값입니다.[out] result
: 주어진napi_value
가TypedArray
를 나타내는지 여부입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 전달된 Object
가 타입 배열인지 확인합니다.
napi_is_dataview
추가된 버전: v8.3.0
N-API 버전: 1
napi_status napi_is_dataview(napi_env env, napi_value value, bool* result)
[in] env
: API가 호출되는 환경입니다.[in] value
: 확인할 JavaScript 값입니다.[out] result
: 주어진napi_value
가DataView
를 나타내는지 여부입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 전달된 Object
가 DataView
인지 확인합니다.
napi_strict_equals
추가된 버전: v8.0.0
N-API 버전: 1
napi_status napi_strict_equals(napi_env env,
napi_value lhs,
napi_value rhs,
bool* result)
[in] env
: API가 호출되는 환경입니다.[in] lhs
: 확인할 JavaScript 값입니다.[in] rhs
: 비교할 JavaScript 값입니다.[out] result
: 두napi_value
객체가 같은지 여부입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 ECMAScript 언어 사양의 섹션 7.2.14에 정의된 엄격한 동등성 알고리즘의 호출을 나타냅니다.
napi_detach_arraybuffer
추가된 버전: v13.0.0, v12.16.0, v10.22.0
N-API 버전: 7
napi_status napi_detach_arraybuffer(napi_env env,
napi_value arraybuffer)
[in] env
: API가 호출되는 환경입니다.[in] arraybuffer
: 분리할 JavaScriptArrayBuffer
입니다.
API가 성공하면 napi_ok
를 반환합니다. 분리할 수 없는 ArrayBuffer
가 전달되면 napi_detachable_arraybuffer_expected
를 반환합니다.
일반적으로 ArrayBuffer
는 이전에 분리된 경우 분리할 수 없습니다. 엔진은 ArrayBuffer
를 분리할 수 있는지 여부에 추가 조건을 적용할 수 있습니다. 예를 들어, V8은 ArrayBuffer
가 외부여야 합니다. 즉, napi_create_external_arraybuffer
로 생성해야 합니다.
이 API는 ECMAScript 언어 사양의 섹션 24.1.1.3에 정의된 ArrayBuffer
분리 작업의 호출을 나타냅니다.
napi_is_detached_arraybuffer
추가된 버전: v13.3.0, v12.16.0, v10.22.0
N-API 버전: 7
napi_status napi_is_detached_arraybuffer(napi_env env,
napi_value arraybuffer,
bool* result)
[in] env
: API가 호출되는 환경입니다.[in] arraybuffer
: 확인할 JavaScriptArrayBuffer
입니다.[out] result
:arraybuffer
가 분리되었는지 여부입니다.
API가 성공하면 napi_ok
를 반환합니다.
ArrayBuffer
의 내부 데이터가 null
이면 분리된 것으로 간주됩니다.
이 API는 ECMAScript 언어 사양의 섹션 24.1.1.2에 정의된 ArrayBuffer
IsDetachedBuffer
작업의 호출을 나타냅니다.
JavaScript 속성 작업
Node-API는 JavaScript 객체에서 속성을 가져오고 설정하는 API 세트를 제공합니다. 이러한 유형 중 일부는 ECMAScript 언어 사양의 섹션 7에 문서화되어 있습니다.
JavaScript의 속성은 키와 값의 튜플로 표현됩니다. 근본적으로 Node-API의 모든 속성 키는 다음 형식 중 하나로 표현할 수 있습니다.
- 이름 지정됨: 간단한 UTF8 인코딩 문자열
- 정수 인덱스:
uint32_t
로 표현되는 인덱스 값 - JavaScript 값: Node-API에서
napi_value
로 표현됩니다. 이는string
,number
또는symbol
을 나타내는napi_value
일 수 있습니다.
Node-API 값은 napi_value
유형으로 표현됩니다. JavaScript 값이 필요한 모든 Node-API 호출은 napi_value
를 사용합니다. 그러나 해당 napi_value
가 API에서 예상하는 JavaScript 유형인지 확인하는 것은 호출자의 책임입니다.
이 섹션에 문서화된 API는 napi_value
로 표현되는 임의의 JavaScript 객체에서 속성을 가져오고 설정하는 간단한 인터페이스를 제공합니다.
예를 들어 다음 JavaScript 코드 조각을 고려해 보세요.
const obj = {}
obj.myProp = 123
다음 코드 조각을 사용하여 Node-API 값으로 이와 동등한 작업을 수행할 수 있습니다.
napi_status status = napi_generic_failure;
// const obj = {}
napi_value obj, value;
status = napi_create_object(env, &obj);
if (status != napi_ok) return status;
// 123에 대한 napi_value 생성
status = napi_create_int32(env, 123, &value);
if (status != napi_ok) return status;
// obj.myProp = 123
status = napi_set_named_property(env, obj, "myProp", value);
if (status != napi_ok) return status;
인덱스된 속성은 비슷한 방식으로 설정할 수 있습니다. 다음 JavaScript 코드 조각을 고려해 보세요.
const arr = []
arr[123] = 'hello'
다음 코드 조각을 사용하여 Node-API 값으로 이와 동등한 작업을 수행할 수 있습니다.
napi_status status = napi_generic_failure;
// const arr = [];
napi_value arr, value;
status = napi_create_array(env, &arr);
if (status != napi_ok) return status;
// 'hello'에 대한 napi_value 생성
status = napi_create_string_utf8(env, "hello", NAPI_AUTO_LENGTH, &value);
if (status != napi_ok) return status;
// arr[123] = 'hello';
status = napi_set_element(env, arr, 123, value);
if (status != napi_ok) return status;
이 섹션에 설명된 API를 사용하여 속성을 검색할 수 있습니다. 다음 JavaScript 코드 조각을 고려해 보세요.
const arr = []
const value = arr[123]
다음은 Node-API 대응 항목과 대략적으로 동일합니다.
napi_status status = napi_generic_failure;
// const arr = []
napi_value arr, value;
status = napi_create_array(env, &arr);
if (status != napi_ok) return status;
// const value = arr[123]
status = napi_get_element(env, arr, 123, &value);
if (status != napi_ok) return status;
마지막으로 성능상의 이유로 객체에 여러 속성을 정의할 수도 있습니다. 다음 JavaScript를 고려해 보세요.
const obj = {}
Object.defineProperties(obj, {
foo: { value: 123, writable: true, configurable: true, enumerable: true },
bar: { value: 456, writable: true, configurable: true, enumerable: true },
})
다음은 Node-API 대응 항목과 대략적으로 동일합니다.
napi_status status = napi_status_generic_failure;
// const obj = {};
napi_value obj;
status = napi_create_object(env, &obj);
if (status != napi_ok) return status;
// 123 및 456에 대한 napi_value 생성
napi_value fooValue, barValue;
status = napi_create_int32(env, 123, &fooValue);
if (status != napi_ok) return status;
status = napi_create_int32(env, 456, &barValue);
if (status != napi_ok) return status;
// 속성 설정
napi_property_descriptor descriptors[] = {
{ "foo", NULL, NULL, NULL, NULL, fooValue, napi_writable | napi_configurable, NULL },
{ "bar", NULL, NULL, NULL, NULL, barValue, napi_writable | napi_configurable, NULL }
}
status = napi_define_properties(env,
obj,
sizeof(descriptors) / sizeof(descriptors[0]),
descriptors);
if (status != napi_ok) return status;
구조체
napi_property_attributes
[연혁]
버전 | 변경 사항 |
---|---|
v14.12.0 | napi_default_method 및 napi_default_property 추가 |
typedef enum {
napi_default = 0,
napi_writable = 1 << 0,
napi_enumerable = 1 << 1,
napi_configurable = 1 << 2,
// napi_define_class에서 정적 속성과
// 인스턴스 속성을 구별하는 데 사용됩니다. napi_define_properties에서는 무시됩니다.
napi_static = 1 << 10,
// 클래스 메서드의 기본값입니다.
napi_default_method = napi_writable | napi_configurable,
// JS obj[prop]과 같은 객체 속성의 기본값입니다.
napi_default_jsproperty = napi_writable |
napi_enumerable |
napi_configurable,
} napi_property_attributes;
napi_property_attributes
는 JavaScript 객체에 설정된 속성의 동작을 제어하는 데 사용되는 플래그입니다. napi_static
을 제외하고는 ECMAScript 언어 사양의 섹션 6.1.7.1에 나열된 속성에 해당합니다. 다음 비트 플래그 중 하나 이상일 수 있습니다.
napi_default
: 속성에 명시적 속성이 설정되지 않았습니다. 기본적으로 속성은 읽기 전용이고 열거할 수 없으며 구성할 수 없습니다.napi_writable
: 속성을 쓸 수 있습니다.napi_enumerable
: 속성을 열거할 수 있습니다.napi_configurable
: 속성은 ECMAScript 언어 사양의 섹션 6.1.7.1에 정의된 대로 구성할 수 있습니다.napi_static
: 속성은 기본값인 인스턴스 속성과 반대로 클래스에서 정적 속성으로 정의됩니다. 이는napi_define_class
에서만 사용됩니다.napi_define_properties
에서는 무시됩니다.napi_default_method
: JS 클래스의 메서드와 마찬가지로 속성을 구성하고 쓸 수 있지만 열거할 수는 없습니다.napi_default_jsproperty
: JavaScript에서 할당을 통해 설정된 속성과 마찬가지로 속성을 쓰고, 열거하고, 구성할 수 있습니다.
napi_property_descriptor
typedef struct {
// utf8name 또는 name 중 하나는 NULL이어야 합니다.
const char* utf8name;
napi_value name;
napi_callback method;
napi_callback getter;
napi_callback setter;
napi_value value;
napi_property_attributes attributes;
void* data;
} napi_property_descriptor;
utf8name
: 속성의 키를 설명하는 선택적 문자열로, UTF8로 인코딩됩니다. 속성에 대해utf8name
또는name
중 하나를 제공해야 합니다.name
: 속성의 키로 사용할 JavaScript 문자열 또는 심볼을 가리키는 선택적napi_value
입니다. 속성에 대해utf8name
또는name
중 하나를 제공해야 합니다.value
: 속성이 데이터 속성인 경우 속성의 get 액세스에 의해 검색되는 값입니다. 이것이 전달되면getter
,setter
,method
및data
를NULL
로 설정합니다(이러한 멤버는 사용되지 않으므로).getter
: 속성에 대한 get 액세스가 수행될 때 호출할 함수입니다. 이것이 전달되면value
및method
를NULL
로 설정합니다(이러한 멤버는 사용되지 않으므로). 주어진 함수는 JavaScript 코드에서 속성에 액세스하거나 Node-API 호출을 사용하여 속성에 대한 get이 수행될 때 런타임에 의해 암시적으로 호출됩니다.napi_callback
에서 자세한 내용을 제공합니다.setter
: 속성에 대한 set 액세스가 수행될 때 호출할 함수입니다. 이것이 전달되면value
및method
를NULL
로 설정합니다(이러한 멤버는 사용되지 않으므로). 주어진 함수는 JavaScript 코드에서 속성이 설정되거나 Node-API 호출을 사용하여 속성에 대한 set이 수행될 때 런타임에 의해 암시적으로 호출됩니다.napi_callback
에서 자세한 내용을 제공합니다.method
: 속성 설명자 객체의value
속성을method
로 표현되는 JavaScript 함수로 만들려면 이것을 설정합니다. 이것이 전달되면value
,getter
및setter
를NULL
로 설정합니다(이러한 멤버는 사용되지 않으므로).napi_callback
에서 자세한 내용을 제공합니다.attributes
: 특정 속성과 관련된 속성입니다.napi_property_attributes
를 참조하십시오.data
: 이 함수가 호출될 경우method
,getter
및setter
에 전달되는 콜백 데이터입니다.
함수
napi_get_property_names
추가된 버전: v8.0.0
N-API 버전: 1
napi_status napi_get_property_names(napi_env env,
napi_value object,
napi_value* result);
[in] env
: Node-API 호출이 실행되는 환경입니다.[in] object
: 속성을 검색할 객체입니다.[out] result
: 객체의 속성 이름을 나타내는 JavaScript 값의 배열을 나타내는napi_value
입니다. API는napi_get_array_length
및napi_get_element
를 사용하여result
를 반복하는 데 사용할 수 있습니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 object
의 열거 가능한 속성의 이름을 문자열 배열로 반환합니다. 키가 심볼인 object
의 속성은 포함되지 않습니다.
napi_get_all_property_names
추가된 버전: v13.7.0, v12.17.0, v10.20.0
N-API 버전: 6
napi_get_all_property_names(napi_env env,
napi_value object,
napi_key_collection_mode key_mode,
napi_key_filter key_filter,
napi_key_conversion key_conversion,
napi_value* result);
[in] env
: Node-API 호출이 실행되는 환경입니다.[in] object
: 속성을 검색할 객체입니다.[in] key_mode
: 프로토타입 속성도 검색할지 여부입니다.[in] key_filter
: 검색할 속성(열거 가능/읽기 가능/쓰기 가능)입니다.[in] key_conversion
: 번호가 매겨진 속성 키를 문자열로 변환할지 여부입니다.[out] result
: 객체의 속성 이름을 나타내는 JavaScript 값의 배열을 나타내는napi_value
입니다.napi_get_array_length
및napi_get_element
를 사용하여result
를 반복할 수 있습니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 이 객체에서 사용 가능한 속성의 이름을 포함하는 배열을 반환합니다.
napi_set_property
추가된 버전: v8.0.0
N-API 버전: 1
napi_status napi_set_property(napi_env env,
napi_value object,
napi_value key,
napi_value value);
[in] env
: Node-API 호출이 실행되는 환경입니다.[in] object
: 속성을 설정할 객체입니다.[in] key
: 설정할 속성의 이름입니다.[in] value
: 속성 값입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 전달된 Object
에 속성을 설정합니다.
napi_get_property
추가된 버전: v8.0.0
N-API 버전: 1
napi_status napi_get_property(napi_env env,
napi_value object,
napi_value key,
napi_value* result);
[in] env
: Node-API 호출이 실행되는 환경입니다.[in] object
: 속성을 가져올 객체입니다.[in] key
: 가져올 속성의 이름입니다.[out] result
: 속성의 값입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 전달된 Object
에서 요청된 속성을 가져옵니다.
napi_has_property
추가된 버전: v8.0.0
N-API 버전: 1
napi_status napi_has_property(napi_env env,
napi_value object,
napi_value key,
bool* result);
[in] env
: Node-API 호출이 실행되는 환경입니다.[in] object
: 쿼리할 객체입니다.[in] key
: 존재 여부를 확인할 속성의 이름입니다.[out] result
: 객체에 속성이 존재하는지 여부입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 전달된 Object
에 명명된 속성이 있는지 확인합니다.
napi_delete_property
추가된 버전: v8.2.0
N-API 버전: 1
napi_status napi_delete_property(napi_env env,
napi_value object,
napi_value key,
bool* result);
[in] env
: Node-API 호출이 실행되는 환경입니다.[in] object
: 쿼리할 객체입니다.[in] key
: 삭제할 속성의 이름입니다.[out] result
: 속성 삭제가 성공했는지 여부입니다.result
는NULL
을 전달하여 선택적으로 무시할 수 있습니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 object
에서 key
자체 속성을 삭제하려고 시도합니다.
napi_has_own_property
추가된 버전: v8.2.0
N-API 버전: 1
napi_status napi_has_own_property(napi_env env,
napi_value object,
napi_value key,
bool* result);
[in] env
: Node-API 호출이 호출된 환경입니다.[in] object
: 쿼리할 객체입니다.[in] key
: 존재하는지 확인할 고유 속성의 이름입니다.[out] result
: 객체에 고유 속성이 존재하는지 여부입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 전달된 Object
에 명명된 고유 속성이 있는지 확인합니다. key
는 string
또는 symbol
이어야 하며 그렇지 않으면 오류가 발생합니다. Node-API는 데이터 유형 간에 변환을 수행하지 않습니다.
napi_set_named_property
추가된 버전: v8.0.0
N-API 버전: 1
napi_status napi_set_named_property(napi_env env,
napi_value object,
const char* utf8Name,
napi_value value);
[in] env
: Node-API 호출이 호출된 환경입니다.[in] object
: 속성을 설정할 객체입니다.[in] utf8Name
: 설정할 속성의 이름입니다.[in] value
: 속성 값입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 메서드는 utf8Name
으로 전달된 문자열에서 생성된 napi_value
를 사용하여 napi_set_property
를 호출하는 것과 같습니다.
napi_get_named_property
추가된 버전: v8.0.0
N-API 버전: 1
napi_status napi_get_named_property(napi_env env,
napi_value object,
const char* utf8Name,
napi_value* result);
[in] env
: Node-API 호출이 호출된 환경입니다.[in] object
: 속성을 검색할 객체입니다.[in] utf8Name
: 가져올 속성의 이름입니다.[out] result
: 속성의 값입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 메서드는 utf8Name
으로 전달된 문자열에서 생성된 napi_value
를 사용하여 napi_get_property
를 호출하는 것과 같습니다.
napi_has_named_property
추가된 버전: v8.0.0
N-API 버전: 1
napi_status napi_has_named_property(napi_env env,
napi_value object,
const char* utf8Name,
bool* result);
[in] env
: Node-API 호출이 실행되는 환경입니다.[in] object
: 쿼리할 객체입니다.[in] utf8Name
: 확인하려는 속성의 이름입니다.[out] result
: 객체에 속성이 존재하는지 여부입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 메서드는 utf8Name
으로 전달된 문자열에서 생성된 napi_value
로 napi_has_property
를 호출하는 것과 같습니다.
napi_set_element
추가된 버전: v8.0.0
N-API 버전: 1
napi_status napi_set_element(napi_env env,
napi_value object,
uint32_t index,
napi_value value);
[in] env
: Node-API 호출이 실행되는 환경입니다.[in] object
: 속성을 설정할 객체입니다.[in] index
: 설정할 속성의 인덱스입니다.[in] value
: 속성 값입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 전달된 Object
에 요소를 설정합니다.
napi_get_element
추가된 버전: v8.0.0
N-API 버전: 1
napi_status napi_get_element(napi_env env,
napi_value object,
uint32_t index,
napi_value* result);
[in] env
: Node-API 호출이 실행되는 환경입니다.[in] object
: 속성을 검색할 객체입니다.[in] index
: 가져올 속성의 인덱스입니다.[out] result
: 속성 값입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 요청된 인덱스에서 요소를 가져옵니다.
napi_has_element
추가된 버전: v8.0.0
N-API 버전: 1
napi_status napi_has_element(napi_env env,
napi_value object,
uint32_t index,
bool* result);
[in] env
: Node-API 호출이 실행되는 환경입니다.[in] object
: 쿼리할 객체입니다.[in] index
: 확인하려는 속성의 인덱스입니다.[out] result
: 객체에 속성이 존재하는지 여부입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 전달된 Object
에 요청된 인덱스에 요소가 있는지 여부를 반환합니다.
napi_delete_element
추가된 버전: v8.2.0
N-API 버전: 1
napi_status napi_delete_element(napi_env env,
napi_value object,
uint32_t index,
bool* result);
[in] env
: Node-API 호출이 실행되는 환경입니다.[in] object
: 쿼리할 객체입니다.[in] index
: 삭제할 속성의 인덱스입니다.[out] result
: 요소 삭제 성공 여부입니다.result
는 선택적으로NULL
을 전달하여 무시할 수 있습니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 object
에서 지정된 index
를 삭제하려고 시도합니다.
napi_define_properties
추가된 버전: v8.0.0
N-API 버전: 1
napi_status napi_define_properties(napi_env env,
napi_value object,
size_t property_count,
const napi_property_descriptor* properties);
[in] env
: Node-API 호출이 실행되는 환경입니다.[in] object
: 속성을 검색할 객체입니다.[in] property_count
:properties
배열의 요소 수입니다.[in] properties
: 속성 설명자 배열입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 메서드를 사용하면 지정된 객체에 여러 속성을 효율적으로 정의할 수 있습니다. 속성은 속성 설명자를 사용하여 정의됩니다(napi_property_descriptor
참조). 이러한 속성 설명자의 배열이 주어지면 이 API는 DefineOwnProperty()
(ECMA-262 사양의 섹션 9.1.6에 설명됨)에 정의된 대로 한 번에 하나씩 객체에 속성을 설정합니다.
napi_object_freeze
추가된 버전: v14.14.0, v12.20.0
N-API 버전: 8
napi_status napi_object_freeze(napi_env env,
napi_value object);
[in] env
: Node-API 호출이 실행되는 환경입니다.[in] object
: 고정할 객체입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 메서드는 지정된 객체를 고정합니다. 이렇게 하면 새 속성이 추가되지 않고, 기존 속성이 제거되지 않으며, 기존 속성의 열거 가능성, 구성 가능성 또는 쓰기 가능성이 변경되지 않고, 기존 속성의 값이 변경되지 않습니다. 또한 객체의 프로토타입이 변경되는 것을 방지합니다. 이는 ECMA-262 사양의 섹션 19.1.2.6에 설명되어 있습니다.
napi_object_seal
추가된 버전: v14.14.0, v12.20.0
N-API 버전: 8
napi_status napi_object_seal(napi_env env,
napi_value object);
[in] env
: Node-API 호출이 호출되는 환경입니다.[in] object
: 봉인할 객체입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 메서드는 주어진 객체를 봉인합니다. 이렇게 하면 새 속성이 추가되는 것을 막고 모든 기존 속성을 구성 불가능으로 표시합니다. 이는 ECMA-262 사양의 섹션 19.1.2.20에 설명되어 있습니다.
JavaScript 함수 작업
Node-API는 JavaScript 코드가 네이티브 코드로 다시 호출될 수 있도록 하는 API 세트를 제공합니다. 네이티브 코드로 다시 호출하는 기능을 지원하는 Node-API는 napi_callback
유형으로 표현되는 콜백 함수를 사용합니다. JavaScript VM이 네이티브 코드로 다시 호출하면 제공된 napi_callback
함수가 호출됩니다. 이 섹션에 설명된 API를 통해 콜백 함수는 다음을 수행할 수 있습니다.
- 콜백이 호출된 컨텍스트에 대한 정보를 가져옵니다.
- 콜백에 전달된 인수를 가져옵니다.
- 콜백에서
napi_value
를 반환합니다.
또한 Node-API는 네이티브 코드에서 JavaScript 함수를 호출할 수 있도록 하는 함수 세트를 제공합니다. 함수를 일반 JavaScript 함수 호출처럼 호출하거나 생성자 함수처럼 호출할 수 있습니다.
napi_property_descriptor
항목의 data
필드를 통해 이 API에 전달되는 NULL
이 아닌 데이터는 object
와 연결될 수 있으며 object
와 데이터를 napi_add_finalizer
에 전달하여 object
가 가비지 수집될 때마다 해제할 수 있습니다.
napi_call_function
추가된 버전: v8.0.0
N-API 버전: 1
NAPI_EXTERN napi_status napi_call_function(napi_env env,
napi_value recv,
napi_value func,
size_t argc,
const napi_value* argv,
napi_value* result);
[in] env
: API가 호출되는 환경입니다.[in] recv
: 호출된 함수에 전달된this
값입니다.[in] func
: 호출할 JavaScript 함수를 나타내는napi_value
입니다.[in] argc
:argv
배열의 요소 수입니다.[in] argv
: 함수에 인수로 전달된 JavaScript 값을 나타내는napi_values
배열입니다.[out] result
: 반환된 JavaScript 객체를 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 메서드를 사용하면 네이티브 추가 기능에서 JavaScript 함수 객체를 호출할 수 있습니다. 이것은 추가 기능의 네이티브 코드 에서 JavaScript 로 다시 호출하는 기본 메커니즘입니다. 비동기 작업 후 JavaScript로 호출하는 특수한 경우에는 napi_make_callback
을 참조하십시오.
샘플 사용 사례는 다음과 같습니다. 다음 JavaScript 스니펫을 고려하십시오.
function AddTwo(num) {
return num + 2
}
global.AddTwo = AddTwo
그런 다음 위의 함수는 다음 코드를 사용하여 네이티브 추가 기능에서 호출할 수 있습니다.
// 전역 객체에서 "AddTwo"라는 함수를 가져옵니다.
napi_value global, add_two, arg;
napi_status status = napi_get_global(env, &global);
if (status != napi_ok) return;
status = napi_get_named_property(env, global, "AddTwo", &add_two);
if (status != napi_ok) return;
// const arg = 1337
status = napi_create_int32(env, 1337, &arg);
if (status != napi_ok) return;
napi_value* argv = &arg;
size_t argc = 1;
// AddTwo(arg);
napi_value return_val;
status = napi_call_function(env, global, add_two, argc, argv, &return_val);
if (status != napi_ok) return;
// 결과를 네이티브 유형으로 다시 변환합니다.
int32_t result;
status = napi_get_value_int32(env, return_val, &result);
if (status != napi_ok) return;
napi_create_function
추가된 버전: v8.0.0
N-API 버전: 1
napi_status napi_create_function(napi_env env,
const char* utf8name,
size_t length,
napi_callback cb,
void* data,
napi_value* result);
[in] env
: API가 호출되는 환경입니다.[in] utf8Name
: UTF8로 인코딩된 함수의 선택적 이름입니다. JavaScript 내에서 새 함수 객체의name
속성으로 표시됩니다.[in] length
:utf8name
의 바이트 길이이거나 null로 끝나는 경우NAPI_AUTO_LENGTH
입니다.[in] cb
: 이 함수 객체가 호출될 때 호출되어야 하는 네이티브 함수입니다.napi_callback
에서 자세한 내용을 제공합니다.[in] data
: 사용자 제공 데이터 컨텍스트입니다. 나중에 호출될 때 함수로 다시 전달됩니다.[out] result
: 새로 생성된 함수에 대한 JavaScript 함수 객체를 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API를 사용하면 애드온 작성자가 네이티브 코드에서 함수 객체를 만들 수 있습니다. 이것은 JavaScript 에서 애드온의 네이티브 코드로 호출을 허용하는 주요 메커니즘입니다.
새로 생성된 함수는 이 호출 후 스크립트에서 자동으로 표시되지 않습니다. 대신, 스크립트에서 함수에 접근할 수 있도록 JavaScript에 표시되는 모든 객체에 속성을 명시적으로 설정해야 합니다.
애드온의 모듈 내보내기의 일부로 함수를 노출하려면 내보내기 객체에 새로 생성된 함수를 설정합니다. 샘플 모듈은 다음과 같습니다.
napi_value SayHello(napi_env env, napi_callback_info info) {
printf("Hello\n");
return NULL;
}
napi_value Init(napi_env env, napi_value exports) {
napi_status status;
napi_value fn;
status = napi_create_function(env, NULL, 0, SayHello, NULL, &fn);
if (status != napi_ok) return NULL;
status = napi_set_named_property(env, exports, "sayHello", fn);
if (status != napi_ok) return NULL;
return exports;
}
NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)
위의 코드를 감안할 때, JavaScript에서 다음과 같이 애드온을 사용할 수 있습니다.
const myaddon = require('./addon')
myaddon.sayHello()
require()
에 전달된 문자열은 .node
파일을 만드는 데 사용되는 binding.gyp
의 대상 이름입니다.
data
매개변수를 통해 이 API에 전달되는 NULL
이 아닌 모든 데이터는 결과 JavaScript 함수( result
매개변수에서 반환됨)와 연결될 수 있으며, JavaScript 함수와 데이터를 napi_add_finalizer
에 전달하여 함수가 가비지 수집될 때마다 해제할 수 있습니다.
JavaScript Function
은 ECMAScript 언어 사양의 섹션 19.2에 설명되어 있습니다.
napi_get_cb_info
추가 버전: v8.0.0
N-API 버전: 1
napi_status napi_get_cb_info(napi_env env,
napi_callback_info cbinfo,
size_t* argc,
napi_value* argv,
napi_value* thisArg,
void** data)
[in] env
: API가 호출되는 환경입니다.[in] cbinfo
: 콜백 함수에 전달된 콜백 정보입니다.[in-out] argc
: 제공된argv
배열의 길이를 지정하고 실제 인수의 개수를 받습니다.NULL
을 전달하여argc
를 선택적으로 무시할 수 있습니다.[out] argv
: 인수가 복사될napi_value
의 C 배열입니다. 제공된 개수보다 많은 인수가 있는 경우 요청된 수의 인수만 복사됩니다. 주장된 것보다 적은 인수가 제공된 경우,argv
의 나머지는undefined
를 나타내는napi_value
값으로 채워집니다.NULL
을 전달하여argv
를 선택적으로 무시할 수 있습니다.[out] thisArg
: 호출에 대한 JavaScriptthis
인수를 받습니다.NULL
을 전달하여thisArg
를 선택적으로 무시할 수 있습니다.[out] data
: 콜백에 대한 데이터 포인터를 받습니다.NULL
을 전달하여data
를 선택적으로 무시할 수 있습니다.
API가 성공하면 napi_ok
를 반환합니다.
이 메서드는 콜백 함수 내에서 주어진 콜백 정보에서 인수 및 this
포인터와 같은 호출에 대한 세부 정보를 검색하는 데 사용됩니다.
napi_get_new_target
추가 버전: v8.6.0
N-API 버전: 1
napi_status napi_get_new_target(napi_env env,
napi_callback_info cbinfo,
napi_value* result)
[in] env
: API가 호출되는 환경입니다.[in] cbinfo
: 콜백 함수에 전달된 콜백 정보입니다.[out] result
: 생성자 호출의new.target
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 생성자 호출의 new.target
을 반환합니다. 현재 콜백이 생성자 호출이 아니면 결과는 NULL
입니다.
napi_new_instance
추가됨: v8.0.0
N-API 버전: 1
napi_status napi_new_instance(napi_env env,
napi_value cons,
size_t argc,
napi_value* argv,
napi_value* result)
[in] env
: API가 호출되는 환경입니다.[in] cons
: 생성자로 호출될 JavaScript 함수를 나타내는napi_value
입니다.[in] argc
:argv
배열의 요소 개수입니다.[in] argv
: 생성자에 대한 인수를 나타내는napi_value
형식의 JavaScript 값 배열입니다.argc
가 0인 경우 이 매개변수는NULL
을 전달하여 생략할 수 있습니다.[out] result
: 반환된 JavaScript 객체를 나타내는napi_value
입니다. 이 경우 생성된 객체입니다.
이 메서드는 객체의 생성자를 나타내는 주어진 napi_value
를 사용하여 새 JavaScript 값을 인스턴스화하는 데 사용됩니다. 예를 들어 다음 스니펫을 살펴보겠습니다.
function MyObject(param) {
this.param = param
}
const arg = 'hello'
const value = new MyObject(arg)
다음 스니펫을 사용하여 Node-API에서 근사화할 수 있습니다.
// 생성자 함수 MyObject 가져오기
napi_value global, constructor, arg, value;
napi_status status = napi_get_global(env, &global);
if (status != napi_ok) return;
status = napi_get_named_property(env, global, "MyObject", &constructor);
if (status != napi_ok) return;
// const arg = "hello"
status = napi_create_string_utf8(env, "hello", NAPI_AUTO_LENGTH, &arg);
if (status != napi_ok) return;
napi_value* argv = &arg;
size_t argc = 1;
// const value = new MyObject(arg)
status = napi_new_instance(env, constructor, argc, argv, &value);
API가 성공하면 napi_ok
를 반환합니다.
객체 래핑
Node-API는 C++ 클래스 및 인스턴스를 "래핑"하여 JavaScript에서 클래스 생성자 및 메서드를 호출할 수 있도록 하는 방법을 제공합니다.
래핑된 객체의 경우 클래스 프로토타입에서 호출되는 함수와 클래스 인스턴스에서 호출되는 함수를 구별하기 어려울 수 있습니다. 이 문제를 해결하는 데 사용되는 일반적인 패턴은 나중에 instanceof
검사를 위해 클래스 생성자에 대한 영구 참조를 저장하는 것입니다.
napi_value MyClass_constructor = NULL;
status = napi_get_reference_value(env, MyClass::es_constructor, &MyClass_constructor);
assert(napi_ok == status);
bool is_instance = false;
status = napi_instanceof(env, es_this, MyClass_constructor, &is_instance);
assert(napi_ok == status);
if (is_instance) {
// napi_unwrap() ...
} else {
// 그렇지 않으면...
}
더 이상 필요하지 않으면 참조를 해제해야 합니다.
JavaScript 객체가 특정 네이티브 유형에 대한 래퍼인지 확인하기에 napi_instanceof()
가 충분하지 않은 경우가 있습니다. 이는 특히 래핑된 JavaScript 객체가 프로토타입 메서드의 this
값으로가 아니라 정적 메서드를 통해 애드온으로 다시 전달될 때 그렇습니다. 이러한 경우 잘못 래핑 해제될 가능성이 있습니다.
const myAddon = require('./build/Release/my_addon.node')
// `openDatabase()`는 네이티브 데이터베이스를 래핑하는 JavaScript 객체를 반환합니다.
// 처리합니다.
const dbHandle = myAddon.openDatabase()
// `query()`는 네이티브 쿼리를 래핑하는 JavaScript 객체를 반환합니다.
// 처리합니다.
const queryHandle = myAddon.query(dbHandle, 'Gimme ALL the things!')
// 아래 줄에 의도하지 않은 오류가 있습니다. `myAddon.queryHasRecords()`의 첫 번째 매개변수는
// 쿼리 처리(`query`)가 아닌 데이터베이스 처리(`dbHandle`)여야 하므로 while 루프의 올바른 조건은
//
// myAddon.queryHasRecords(dbHandle, queryHandle)
//
while (myAddon.queryHasRecords(queryHandle, dbHandle)) {
// 레코드 검색
}
위의 예에서 myAddon.queryHasRecords()
는 두 개의 인수를 허용하는 메서드입니다. 첫 번째는 데이터베이스 처리이고 두 번째는 쿼리 처리입니다. 내부적으로는 첫 번째 인수를 래핑 해제하고 결과 포인터를 네이티브 데이터베이스 처리로 캐스팅합니다. 그런 다음 두 번째 인수를 래핑 해제하고 결과 포인터를 쿼리 처리로 캐스팅합니다. 인수가 잘못된 순서로 전달되면 캐스트가 작동하지만, 기본 데이터베이스 작업이 실패하거나 유효하지 않은 메모리 액세스를 유발할 가능성이 큽니다.
첫 번째 인수에서 검색된 포인터가 실제로 데이터베이스 처리에 대한 포인터이고 유사하게 두 번째 인수에서 검색된 포인터가 실제로 쿼리 처리에 대한 포인터인지 확인하려면 queryHasRecords()
의 구현이 유형 유효성 검사를 수행해야 합니다. 데이터베이스 처리가 인스턴스화된 JavaScript 클래스 생성자와 napi_ref
에 인스턴스화된 쿼리 처리의 생성자를 유지하면 napi_instanceof()
를 사용하여 queryHashRecords()
에 전달된 인스턴스가 실제로 올바른 유형인지 확인할 수 있으므로 도움이 됩니다.
불행히도 napi_instanceof()
는 프로토타입 조작에 대한 보호를 제공하지 않습니다. 예를 들어 데이터베이스 처리 인스턴스의 프로토타입을 쿼리 처리 인스턴스에 대한 생성자의 프로토타입으로 설정할 수 있습니다. 이 경우 데이터베이스 처리 인스턴스는 쿼리 처리 인스턴스로 나타날 수 있으며 쿼리 처리 인스턴스에 대한 napi_instanceof()
테스트를 통과하면서도 데이터베이스 처리 포인터를 포함합니다.
이를 위해 Node-API는 유형 태깅 기능을 제공합니다.
유형 태그는 애드온에 고유한 128비트 정수입니다. Node-API는 유형 태그를 저장하기 위한 napi_type_tag
구조를 제공합니다. 이러한 값이 JavaScript 객체 또는 napi_value
에 저장된 외부 값과 함께 napi_type_tag_object()
에 전달되면 JavaScript 객체는 유형 태그로 "표시"됩니다. "표시"는 JavaScript 측에서 보이지 않습니다. JavaScript 객체가 네이티브 바인딩에 도착하면 napi_check_object_type_tag()
를 원래 유형 태그와 함께 사용하여 JavaScript 객체가 이전에 유형 태그로 "표시"되었는지 확인할 수 있습니다. 이렇게 하면 프로토타입 조작 및 애드온 언로드/재로딩을 견딜 수 있으므로 napi_instanceof()
에서 제공할 수 있는 것보다 충실도가 높은 유형 검사 기능이 생성됩니다.
위의 예시를 계속해서, 다음 골격 애드온 구현은 napi_type_tag_object()
및 napi_check_object_type_tag()
의 사용법을 보여줍니다.
// 이 값은 데이터베이스 처리의 유형 태그입니다. 명령
//
// uuidgen | sed -r -e 's/-//g' -e 's/(.{16})(.*)/0x\1, 0x\2/'
//
// 구조체를 초기화하는 데 사용할 두 개의 값을 얻는 데 사용할 수 있습니다.
static const napi_type_tag DatabaseHandleTypeTag = {
0x1edf75a38336451d, 0xa5ed9ce2e4c00c38
};
// 이 값은 쿼리 처리의 유형 태그입니다.
static const napi_type_tag QueryHandleTypeTag = {
0x9c73317f9fad44a3, 0x93c3920bf3b0ad6a
};
static napi_value
openDatabase(napi_env env, napi_callback_info info) {
napi_status status;
napi_value result;
// 데이터베이스 처리로 이어지는 기본 작업을 수행합니다.
DatabaseHandle* dbHandle = open_database();
// 비어 있는 새 JS 객체를 만듭니다.
status = napi_create_object(env, &result);
if (status != napi_ok) return NULL;
// 객체에 `DatabaseHandle`에 대한 포인터가 있음을 나타내도록 객체를 태그합니다.
status = napi_type_tag_object(env, result, &DatabaseHandleTypeTag);
if (status != napi_ok) return NULL;
// JS 객체 내부에 `DatabaseHandle` 구조체에 대한 포인터를 저장합니다.
status = napi_wrap(env, result, dbHandle, NULL, NULL, NULL);
if (status != napi_ok) return NULL;
return result;
}
// 나중에 데이터베이스 처리인 JavaScript 객체를 수신하면
// `napi_check_object_type_tag()`를 사용하여 실제로 그러한 처리인지 확인할 수 있습니다.
static napi_value
query(napi_env env, napi_callback_info info) {
napi_status status;
size_t argc = 2;
napi_value argv[2];
bool is_db_handle;
status = napi_get_cb_info(env, info, &argc, argv, NULL, NULL);
if (status != napi_ok) return NULL;
// 첫 번째 매개변수로 전달된 객체에 이전에 적용된 태그가 있는지 확인합니다.
status = napi_check_object_type_tag(env,
argv[0],
&DatabaseHandleTypeTag,
&is_db_handle);
if (status != napi_ok) return NULL;
// 그렇지 않은 경우 `TypeError`를 발생시킵니다.
if (!is_db_handle) {
// TypeError를 발생시킵니다.
return NULL;
}
}
napi_define_class
추가 버전: v8.0.0
N-API 버전: 1
napi_status napi_define_class(napi_env env,
const char* utf8name,
size_t length,
napi_callback constructor,
void* data,
size_t property_count,
const napi_property_descriptor* properties,
napi_value* result);
[in] env
: API가 호출되는 환경입니다.[in] utf8name
: JavaScript 생성자 함수의 이름입니다. 명확성을 위해 C++ 클래스를 래핑할 때 C++ 클래스 이름을 사용하는 것이 좋습니다.[in] length
:utf8name
의 바이트 단위 길이입니다. null로 종료되는 경우NAPI_AUTO_LENGTH
입니다.[in] constructor
: 클래스 인스턴스 생성을 처리하는 콜백 함수입니다. C++ 클래스를 래핑할 때 이 메서드는napi_callback
서명이 있는 정적 멤버여야 합니다. C++ 클래스 생성자는 사용할 수 없습니다.napi_callback
에서 자세한 내용을 제공합니다.[in] data
: 콜백 정보의data
속성으로 생성자 콜백에 전달될 선택적 데이터입니다.[in] property_count
:properties
배열 인수의 항목 수입니다.[in] properties
: 클래스에 대한 정적 및 인스턴스 데이터 속성, 접근자 및 메서드를 설명하는 속성 설명자의 배열입니다.napi_property_descriptor
를 참조하십시오.[out] result
: 클래스에 대한 생성자 함수를 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
다음을 포함하는 JavaScript 클래스를 정의합니다.
- 클래스 이름이 있는 JavaScript 생성자 함수입니다. 해당 C++ 클래스를 래핑할 때
constructor
를 통해 전달된 콜백을 사용하여 새로운 C++ 클래스 인스턴스를 인스턴스화할 수 있습니다. 그런 다음napi_wrap
을 사용하여 생성되는 JavaScript 객체 인스턴스 내부에 배치할 수 있습니다. - 구현에서 해당 C++ 클래스의 정적 데이터 속성, 접근자 및 메서드를 호출할 수 있는 생성자 함수의 속성입니다(
napi_static
특성이 있는 속성 설명자로 정의됨). - 생성자 함수의
prototype
객체 속성입니다. C++ 클래스를 래핑할 때 C++ 클래스의 비정적 데이터 속성, 접근자 및 메서드는napi_unwrap
을 사용하여 JavaScript 객체 인스턴스 내부에 배치된 C++ 클래스 인스턴스를 검색한 후napi_static
특성 없이 속성 설명자에 제공된 정적 함수에서 호출할 수 있습니다.
C++ 클래스를 래핑할 때 constructor
를 통해 전달된 C++ 생성자 콜백은 실제 클래스 생성자를 호출한 다음 새로운 C++ 인스턴스를 JavaScript 객체로 래핑하고 래퍼 객체를 반환하는 클래스의 정적 메서드여야 합니다. 자세한 내용은 napi_wrap
을 참조하십시오.
napi_define_class
에서 반환된 JavaScript 생성자 함수는 종종 저장되고 나중에 네이티브 코드에서 클래스의 새 인스턴스를 생성하거나 제공된 값이 클래스의 인스턴스인지 확인하는 데 사용됩니다. 이 경우 함수 값이 가비지 수집되지 않도록 하려면 napi_create_reference
를 사용하여 강력한 영구 참조를 만들어 참조 수가 >= 1로 유지되도록 할 수 있습니다.
data
매개변수 또는 napi_property_descriptor
배열 항목의 data
필드를 통해 이 API에 전달되는 NULL
이 아닌 모든 데이터는 결과 JavaScript 생성자( result
매개변수로 반환됨)와 연결될 수 있으며 JavaScript 함수와 데이터를 모두 napi_add_finalizer
에 전달하여 클래스가 가비지 수집될 때마다 해제될 수 있습니다.
napi_wrap
추가된 버전: v8.0.0
N-API 버전: 1
napi_status napi_wrap(napi_env env,
napi_value js_object,
void* native_object,
napi_finalize finalize_cb,
void* finalize_hint,
napi_ref* result);
[in] env
: API가 호출되는 환경입니다.[in] js_object
: 네이티브 객체를 감쌀 JavaScript 객체입니다.[in] native_object
: JavaScript 객체로 감쌀 네이티브 인스턴스입니다.[in] finalize_cb
: JavaScript 객체가 가비지 수집될 때 네이티브 인스턴스를 해제하는 데 사용할 수 있는 선택적 네이티브 콜백입니다.napi_finalize
에서 더 자세한 내용을 제공합니다.[in] finalize_hint
: 최종화 콜백으로 전달되는 선택적 컨텍스트 힌트입니다.[out] result
: 래핑된 객체에 대한 선택적 참조입니다.
API가 성공하면 napi_ok
를 반환합니다.
JavaScript 객체에 네이티브 인스턴스를 래핑합니다. 네이티브 인스턴스는 나중에 napi_unwrap()
을 사용하여 검색할 수 있습니다.
JavaScript 코드가 napi_define_class()
를 사용하여 정의된 클래스의 생성자를 호출하면 생성자에 대한 napi_callback
이 호출됩니다. 네이티브 클래스의 인스턴스를 생성한 후 콜백은 생성자 콜백에 대한 this
인수 인 이미 생성된 JavaScript 객체에 새로 생성된 인스턴스를 래핑하기 위해 napi_wrap()
을 호출해야 합니다. (해당 this
객체는 생성자 함수의 prototype
에서 생성되었으므로 이미 모든 인스턴스 속성 및 메서드 정의를 가지고 있습니다.)
일반적으로 클래스 인스턴스를 래핑할 때 최종화 콜백은 최종화 콜백에 대한 data
인수로 수신되는 네이티브 인스턴스를 단순히 삭제하는 콜백을 제공해야 합니다.
선택적으로 반환되는 참조는 처음에 0의 참조 횟수를 갖는 약한 참조입니다. 일반적으로 이 참조 횟수는 인스턴스가 유효하게 유지되어야 하는 비동기 작업 중에 일시적으로 증가합니다.
주의: 선택적으로 반환되는 참조(획득된 경우)는 최종화 콜백 호출에 대한 응답으로만 napi_delete_reference
를 통해 삭제해야 합니다. 그 전에 삭제하면 최종화 콜백이 호출되지 않을 수 있습니다. 따라서 참조를 얻을 때 참조의 올바른 폐기를 활성화하려면 최종화 콜백도 필요합니다.
최종자 콜백은 지연될 수 있으며, 이로 인해 객체가 가비지 수집되었고(약한 참조가 유효하지 않음) 최종자가 아직 호출되지 않은 창이 남습니다. napi_wrap()
에서 반환된 약한 참조에 대해 napi_get_reference_value()
를 사용하는 경우에도 빈 결과를 처리해야 합니다.
객체에서 napi_wrap()
을 두 번째로 호출하면 오류가 반환됩니다. 객체와 다른 네이티브 인스턴스를 연결하려면 먼저 napi_remove_wrap()
을 사용하십시오.
napi_unwrap
추가됨: v8.0.0
N-API 버전: 1
napi_status napi_unwrap(napi_env env,
napi_value js_object,
void** result);
[in] env
: API가 호출되는 환경입니다.[in] js_object
: 네이티브 인스턴스와 연결된 객체입니다.[out] result
: 래핑된 네이티브 인스턴스에 대한 포인터입니다.
API가 성공하면 napi_ok
를 반환합니다.
napi_wrap()
을 사용하여 이전에 JavaScript 객체로 래핑된 네이티브 인스턴스를 검색합니다.
JavaScript 코드가 클래스에서 메서드 또는 속성 접근자를 호출하면 해당 napi_callback
이 호출됩니다. 콜백이 인스턴스 메서드 또는 접근자에 대한 것이면 콜백에 대한 this
인수는 래퍼 객체입니다. 호출 대상인 래핑된 C++ 인스턴스는 래퍼 객체에서 napi_unwrap()
을 호출하여 얻을 수 있습니다.
napi_remove_wrap
추가됨: v8.5.0
N-API 버전: 1
napi_status napi_remove_wrap(napi_env env,
napi_value js_object,
void** result);
[in] env
: API가 호출되는 환경입니다.[in] js_object
: 네이티브 인스턴스와 연결된 객체입니다.[out] result
: 래핑된 네이티브 인스턴스에 대한 포인터입니다.
API가 성공하면 napi_ok
를 반환합니다.
napi_wrap()
을 사용하여 이전에 JavaScript 객체 js_object
로 래핑된 네이티브 인스턴스를 검색하고 래핑을 제거합니다. finalize 콜백이 래핑과 연결된 경우 JavaScript 객체가 가비지 수집될 때 더 이상 호출되지 않습니다.
napi_type_tag_object
추가됨: v14.8.0, v12.19.0
N-API 버전: 8
napi_status napi_type_tag_object(napi_env env,
napi_value js_object,
const napi_type_tag* type_tag);
[in] env
: API가 호출되는 환경입니다.[in] js_object
: 표시할 JavaScript 객체 또는 외부입니다.[in] type_tag
: 객체가 표시될 태그입니다.
API가 성공하면 napi_ok
를 반환합니다.
type_tag
포인터의 값을 JavaScript 객체 또는 외부와 연결합니다. 그런 다음 napi_check_object_type_tag()
를 사용하여 객체에 첨부된 태그를 애드온이 소유한 태그와 비교하여 객체의 유형이 올바른지 확인할 수 있습니다.
객체에 이미 연결된 유형 태그가 있는 경우 이 API는 napi_invalid_arg
를 반환합니다.
napi_check_object_type_tag
추가된 버전: v14.8.0, v12.19.0
N-API 버전: 8
napi_status napi_check_object_type_tag(napi_env env,
napi_value js_object,
const napi_type_tag* type_tag,
bool* result);
[in] env
: API가 호출되는 환경입니다.[in] js_object
: 검사할 타입 태그가 있는 JavaScript 객체 또는 외부 객체입니다.[in] type_tag
: 객체에서 찾은 태그와 비교할 태그입니다.[out] result
: 주어진 타입 태그가 객체의 타입 태그와 일치하는지 여부입니다. 객체에서 타입 태그를 찾지 못한 경우에도false
가 반환됩니다.
API가 성공하면 napi_ok
를 반환합니다.
type_tag
로 주어진 포인터를 js_object
에서 찾을 수 있는 포인터와 비교합니다. js_object
에서 태그를 찾지 못하거나 태그가 발견되었지만 type_tag
와 일치하지 않으면 result
가 false
로 설정됩니다. 태그가 발견되고 type_tag
와 일치하면 result
가 true
로 설정됩니다.
napi_add_finalizer
추가된 버전: v8.0.0
N-API 버전: 5
napi_status napi_add_finalizer(napi_env env,
napi_value js_object,
void* finalize_data,
node_api_basic_finalize finalize_cb,
void* finalize_hint,
napi_ref* result);
[in] env
: API가 호출되는 환경입니다.[in] js_object
: 네이티브 데이터가 연결될 JavaScript 객체입니다.[in] finalize_data
:finalize_cb
에 전달할 선택적 데이터입니다.[in] finalize_cb
: JavaScript 객체가 가비지 수집될 때 네이티브 데이터를 해제하는 데 사용될 네이티브 콜백입니다.napi_finalize
에서 자세한 내용을 제공합니다.[in] finalize_hint
: finalize 콜백에 전달되는 선택적 컨텍스트 힌트입니다.[out] result
: JavaScript 객체에 대한 선택적 참조입니다.
API가 성공하면 napi_ok
를 반환합니다.
js_object
의 JavaScript 객체가 가비지 수집될 때 호출되는 napi_finalize
콜백을 추가합니다.
이 API는 단일 JavaScript 객체에서 여러 번 호출할 수 있습니다.
주의: 선택적으로 반환된 참조(얻은 경우)는 finalize 콜백 호출에 대한 응답으로만 napi_delete_reference
를 통해 삭제해야 합니다. 그 전에 삭제하면 finalize 콜백이 호출되지 않을 수 있습니다. 따라서 참조를 얻을 때 참조를 올바르게 처리하려면 finalize 콜백도 필요합니다.
node_api_post_finalizer
추가된 버전: v21.0.0, v20.10.0, v18.19.0
napi_status node_api_post_finalizer(node_api_basic_env env,
napi_finalize finalize_cb,
void* finalize_data,
void* finalize_hint);
[in] env
: API가 호출되는 환경입니다.[in] finalize_cb
: JavaScript 객체가 가비지 수집될 때 네이티브 데이터를 해제하는 데 사용될 네이티브 콜백입니다.napi_finalize
에서 자세한 내용을 확인할 수 있습니다.[in] finalize_data
:finalize_cb
에 전달될 선택적 데이터입니다.[in] finalize_hint
: finalize 콜백에 전달되는 선택적 컨텍스트 힌트입니다.
API가 성공하면 napi_ok
를 반환합니다.
이벤트 루프에서 비동기적으로 호출될 napi_finalize
콜백을 예약합니다.
일반적으로 finalizer는 GC(가비지 수집기)가 객체를 수집하는 동안 호출됩니다. 이 시점에서 GC 상태의 변경을 일으킬 수 있는 Node-API 호출은 비활성화되며 Node.js가 충돌합니다.
node_api_post_finalizer
는 애드온이 GC finalization 외부의 시점으로 이러한 Node-API 호출을 연기하도록 허용함으로써 이러한 제한을 해결하는 데 도움이 됩니다.
간단한 비동기 작업
애드온 모듈은 구현의 일부로 libuv에서 비동기 도우미를 활용해야 하는 경우가 많습니다. 이렇게 하면 작업을 비동기적으로 실행하도록 예약하여 메서드가 작업 완료 전에 반환될 수 있습니다. 이를 통해 Node.js 애플리케이션의 전체 실행을 차단하지 않도록 할 수 있습니다.
Node-API는 가장 일반적인 비동기 사용 사례를 다루는 이러한 지원 기능에 대한 ABI 안정적인 인터페이스를 제공합니다.
Node-API는 비동기 워커를 관리하는 데 사용되는 napi_async_work
구조를 정의합니다. 인스턴스는 napi_create_async_work
및 napi_delete_async_work
를 사용하여 생성/삭제됩니다.
execute
및 complete
콜백은 실행기가 실행할 준비가 되었을 때와 작업을 완료했을 때 각각 호출되는 함수입니다.
execute
함수는 JavaScript 실행 또는 JavaScript 객체와의 상호 작용을 초래할 수 있는 Node-API 호출을 피해야 합니다. 대부분의 경우 Node-API 호출을 해야 하는 코드는 complete
콜백에서 수행해야 합니다. JavaScript를 실행할 가능성이 높으므로 실행 콜백에서 napi_env
매개변수를 사용하지 마십시오.
이러한 함수는 다음 인터페이스를 구현합니다.
typedef void (*napi_async_execute_callback)(napi_env env,
void* data);
typedef void (*napi_async_complete_callback)(napi_env env,
napi_status status,
void* data);
이러한 메서드가 호출되면 전달되는 data
매개변수는 napi_create_async_work
호출에 전달된 애드온 제공 void*
데이터입니다.
생성된 비동기 워커는 napi_queue_async_work
함수를 사용하여 실행을 위해 대기열에 넣을 수 있습니다.
napi_status napi_queue_async_work(node_api_basic_env env,
napi_async_work work);
작업이 실행을 시작하기 전에 취소해야 하는 경우 napi_cancel_async_work
를 사용할 수 있습니다.
napi_cancel_async_work
를 호출한 후에는 complete
콜백이 napi_cancelled
상태 값으로 호출됩니다. 취소된 경우에도 complete
콜백 호출 전에 작업을 삭제해서는 안 됩니다.
napi_create_async_work
[기록]
버전 | 변경 사항 |
---|---|
v8.6.0 | async_resource 및 async_resource_name 매개변수 추가. |
v8.0.0 | 추가됨: v8.0.0 |
N-API 버전: 1
napi_status napi_create_async_work(napi_env env,
napi_value async_resource,
napi_value async_resource_name,
napi_async_execute_callback execute,
napi_async_complete_callback complete,
void* data,
napi_async_work* result);
[in] env
: API가 호출되는 환경입니다.[in] async_resource
:async_hooks
init
후크에 전달될 비동기 작업과 관련된 선택적 객체입니다.[in] async_resource_name
:async_hooks
API에서 노출되는 진단 정보에 제공되는 리소스 종류에 대한 식별자입니다.[in] execute
: 비동기적으로 로직을 실행하기 위해 호출해야 하는 네이티브 함수입니다. 주어진 함수는 워커 풀 스레드에서 호출되며 메인 이벤트 루프 스레드와 병렬로 실행할 수 있습니다.[in] complete
: 비동기 로직이 완료되거나 취소될 때 호출될 네이티브 함수입니다. 주어진 함수는 메인 이벤트 루프 스레드에서 호출됩니다.napi_async_complete_callback
에서 더 자세한 내용을 제공합니다.[in] data
: 사용자 제공 데이터 컨텍스트입니다. 이는 execute 및 complete 함수에 다시 전달됩니다.[out] result
: 새로 생성된 비동기 작업에 대한 핸들인napi_async_work*
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 비동기적으로 로직을 실행하는 데 사용되는 작업 객체를 할당합니다. 작업이 더 이상 필요하지 않으면 napi_delete_async_work
를 사용하여 해제해야 합니다.
async_resource_name
은 null로 끝나는 UTF-8 인코딩 문자열이어야 합니다.
async_resource_name
식별자는 사용자가 제공하며 수행 중인 비동기 작업 유형을 나타내야 합니다. 모듈 이름을 포함하는 등 식별자에 네임스페이스를 적용하는 것이 좋습니다. 자세한 내용은 async_hooks
문서를 참조하십시오.
napi_delete_async_work
추가된 버전: v8.0.0
N-API 버전: 1
napi_status napi_delete_async_work(napi_env env,
napi_async_work work);
[in] env
: API가 호출된 환경입니다.[in] work
:napi_create_async_work
호출에서 반환된 핸들입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 이전에 할당된 작업 객체를 해제합니다.
보류 중인 JavaScript 예외가 있는 경우에도 이 API를 호출할 수 있습니다.
napi_queue_async_work
추가된 버전: v8.0.0
N-API 버전: 1
napi_status napi_queue_async_work(node_api_basic_env env,
napi_async_work work);
[in] env
: API가 호출된 환경입니다.[in] work
:napi_create_async_work
호출에서 반환된 핸들입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 이전에 할당된 작업을 실행되도록 스케줄링할 것을 요청합니다. 성공적으로 반환되면 동일한 napi_async_work
항목으로 이 API를 다시 호출해서는 안 되며, 그렇지 않으면 결과가 정의되지 않습니다.
napi_cancel_async_work
추가된 버전: v8.0.0
N-API 버전: 1
napi_status napi_cancel_async_work(node_api_basic_env env,
napi_async_work work);
[in] env
: API가 호출된 환경입니다.[in] work
:napi_create_async_work
호출에서 반환된 핸들입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 아직 시작되지 않은 경우 대기 중인 작업을 취소합니다. 이미 실행이 시작된 경우에는 취소할 수 없으며 napi_generic_failure
가 반환됩니다. 성공하면 complete
콜백이 napi_cancelled
상태 값으로 호출됩니다. 작업이 성공적으로 취소된 경우에도 complete
콜백 호출 전에 삭제해서는 안 됩니다.
보류 중인 JavaScript 예외가 있는 경우에도 이 API를 호출할 수 있습니다.
사용자 지정 비동기 작업
위의 간단한 비동기 작업 API는 모든 시나리오에 적합하지 않을 수 있습니다. 다른 비동기 메커니즘을 사용하는 경우 비동기 작업이 런타임에서 적절하게 추적되도록 하기 위해 다음 API가 필요합니다.
napi_async_init
추가된 버전: v8.6.0
N-API 버전: 1
napi_status napi_async_init(napi_env env,
napi_value async_resource,
napi_value async_resource_name,
napi_async_context* result)
[in] env
: API가 호출되는 환경입니다.[in] async_resource
: 가능한async_hooks
init
훅에 전달되고async_hooks.executionAsyncResource()
로 접근할 수 있는 비동기 작업과 관련된 객체입니다.[in] async_resource_name
:async_hooks
API에서 노출되는 진단 정보에 제공되는 리소스 종류의 식별자입니다.[out] result
: 초기화된 비동기 컨텍스트입니다.
API가 성공하면 napi_ok
를 반환합니다.
async_hooks
관련 API가 올바르게 작동하도록 하려면 async_resource
객체를 napi_async_destroy
까지 유지해야 합니다. 이전 버전과의 ABI 호환성을 유지하기 위해 napi_async_context
는 메모리 누수를 방지하기 위해 async_resource
객체에 대한 강력한 참조를 유지하지 않습니다. 그러나 napi_async_context
가 napi_async_destroy
에 의해 파괴되기 전에 JavaScript 엔진에 의해 async_resource
가 가비지 컬렉션되는 경우, napi_open_callback_scope
및 napi_make_callback
과 같은 napi_async_context
관련 API를 호출하면 AsyncLocalStorage
API를 사용할 때 비동기 컨텍스트 손실과 같은 문제가 발생할 수 있습니다.
이전 버전과의 ABI 호환성을 유지하기 위해 async_resource
에 NULL
을 전달해도 오류가 발생하지 않습니다. 그러나 이는 async_hooks
init
훅 및 async_hooks.executionAsyncResource()
에서 바람직하지 않은 동작을 초래할 수 있으므로 권장되지 않습니다. 이제 리소스는 비동기 콜백 간의 연결을 제공하기 위해 기본 async_hooks
구현에 필요하기 때문입니다.
napi_async_destroy
추가된 버전: v8.6.0
N-API 버전: 1
napi_status napi_async_destroy(napi_env env,
napi_async_context async_context);
[in] env
: API가 호출되는 환경입니다.[in] async_context
: 제거할 비동기 컨텍스트입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 보류 중인 JavaScript 예외가 있는 경우에도 호출할 수 있습니다.
napi_make_callback
[기록]
버전 | 변경 사항 |
---|---|
v8.6.0 | async_context 매개변수가 추가되었습니다. |
v8.0.0 | 추가된 버전: v8.0.0 |
N-API 버전: 1
NAPI_EXTERN napi_status napi_make_callback(napi_env env,
napi_async_context async_context,
napi_value recv,
napi_value func,
size_t argc,
const napi_value* argv,
napi_value* result);
[in] env
: API가 호출되는 환경입니다.[in] async_context
: 콜백을 호출하는 비동기 작업의 컨텍스트입니다. 일반적으로napi_async_init
에서 이전에 얻은 값이어야 합니다. 이전 버전과의 ABI 호환성을 유지하기 위해async_context
에 대해NULL
을 전달해도 오류가 발생하지 않습니다. 그러나 이렇게 하면 비동기 후크가 잘못 작동합니다. 잠재적인 문제로는AsyncLocalStorage
API를 사용할 때 비동기 컨텍스트 손실이 있습니다.[in] recv
: 호출된 함수에 전달되는this
값입니다.[in] func
: 호출할 JavaScript 함수를 나타내는napi_value
입니다.[in] argc
:argv
배열의 요소 수입니다.[in] argv
: 함수의 인수를 나타내는napi_value
형식의 JavaScript 값 배열입니다.argc
가 0이면 이 매개변수는NULL
을 전달하여 생략할 수 있습니다.[out] result
: 반환된 JavaScript 객체를 나타내는napi_value
입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 메서드를 사용하면 네이티브 애드온에서 JavaScript 함수 객체를 호출할 수 있습니다. 이 API는 napi_call_function
과 유사합니다. 그러나 비동기 작업에서 반환된 후(스택에 다른 스크립트가 없는 경우) 네이티브 코드 에서 다시 JavaScript 로 호출하는 데 사용됩니다. 이는 node::MakeCallback
에 대한 매우 간단한 래퍼입니다.
napi_async_complete_callback
내에서 napi_make_callback
을 사용할 필요는 없습니다. 해당 상황에서는 콜백의 비동기 컨텍스트가 이미 설정되어 있으므로 napi_call_function
을 직접 호출하는 것으로 충분합니다. napi_make_callback
함수는 napi_create_async_work
를 사용하지 않는 사용자 정의 비동기 동작을 구현할 때 필요할 수 있습니다.
콜백 중에 JavaScript에서 마이크로태스크 큐에 예약된 모든 process.nextTick
또는 Promises는 C/C++로 다시 반환되기 전에 실행됩니다.
napi_open_callback_scope
Added in: v9.6.0
N-API version: 3
NAPI_EXTERN napi_status napi_open_callback_scope(napi_env env,
napi_value resource_object,
napi_async_context context,
napi_callback_scope* result)
[in] env
: API가 호출되는 환경입니다.[in] resource_object
: 가능한async_hooks
init
hooks에 전달될 비동기 작업과 관련된 객체입니다. 이 매개변수는 더 이상 사용되지 않으며 런타임에 무시됩니다. 대신napi_async_init
의async_resource
매개변수를 사용하십시오.[in] context
: 콜백을 호출하는 비동기 작업의 컨텍스트입니다. 이 값은 이전에napi_async_init
에서 얻어야 합니다.[out] result
: 새로 생성된 범위입니다.
특정 Node-API 호출을 할 때 콜백과 관련된 범위와 동등한 범위가 필요한 경우(예: 프로미스 해결)가 있습니다. 스택에 다른 스크립트가 없는 경우 napi_open_callback_scope
및 napi_close_callback_scope
함수를 사용하여 필요한 범위를 열고 닫을 수 있습니다.
napi_close_callback_scope
Added in: v9.6.0
N-API version: 3
NAPI_EXTERN napi_status napi_close_callback_scope(napi_env env,
napi_callback_scope scope)
[in] env
: API가 호출되는 환경입니다.[in] scope
: 닫을 범위입니다.
이 API는 보류 중인 JavaScript 예외가 있는 경우에도 호출할 수 있습니다.
버전 관리
napi_get_node_version
Added in: v8.4.0
N-API version: 1
typedef struct {
uint32_t major;
uint32_t minor;
uint32_t patch;
const char* release;
} napi_node_version;
napi_status napi_get_node_version(node_api_basic_env env,
const napi_node_version** version);
[in] env
: API가 호출되는 환경입니다.[out] version
: 현재 실행 중인 Node.js 자체의 버전 정보를 가리키는 포인터입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 함수는 현재 실행 중인 Node.js의 메이저, 마이너 및 패치 버전으로 version
구조체를 채우고 process.release.name
값으로 release
필드를 채웁니다.
반환된 버퍼는 정적으로 할당되며 해제할 필요가 없습니다.
napi_get_version
추가된 버전: v8.0.0
N-API 버전: 1
napi_status napi_get_version(node_api_basic_env env,
uint32_t* result);
[in] env
: API가 호출되는 환경입니다.[out] result
: 지원되는 Node-API의 최고 버전입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 Node.js 런타임에서 지원하는 최고 Node-API 버전을 반환합니다. Node-API는 새로운 Node.js 릴리스에서 추가적인 API 기능을 지원할 수 있도록 추가 방식으로 계획됩니다. 애드온이 Node.js에서 지원하는 버전으로 실행될 때 새로운 기능을 사용할 수 있도록 하면서도 지원하지 않는 Node.js 버전으로 실행할 때 대체 동작을 제공하기 위해 다음을 수행합니다.
napi_get_version()
을 호출하여 API가 사용 가능한지 확인합니다.- 사용 가능한 경우
uv_dlsym()
을 사용하여 함수의 포인터를 동적으로 로드합니다. - 동적으로 로드된 포인터를 사용하여 함수를 호출합니다.
- 함수를 사용할 수 없는 경우 함수를 사용하지 않는 대체 구현을 제공합니다.
메모리 관리
napi_adjust_external_memory
추가된 버전: v8.5.0
N-API 버전: 1
NAPI_EXTERN napi_status napi_adjust_external_memory(node_api_basic_env env,
int64_t change_in_bytes,
int64_t* result);
[in] env
: API가 호출되는 환경입니다.[in] change_in_bytes
: JavaScript 객체에 의해 유지되는 외부 할당 메모리의 변경 사항입니다.[out] result
: 조정된 값입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 함수는 V8에 JavaScript 객체에 의해 유지되는 외부 할당 메모리 양에 대한 정보를 제공합니다(예: 네이티브 애드온에서 할당한 자체 메모리를 가리키는 JavaScript 객체). 외부 할당 메모리를 등록하면 평소보다 더 자주 글로벌 가비지 컬렉션이 트리거됩니다.
프로미스
Node-API는 ECMA 사양의 섹션 25.4에 설명된 대로 Promise
객체를 생성하는 기능을 제공합니다. 프로미스를 한 쌍의 객체로 구현합니다. napi_create_promise()
에 의해 프로미스가 생성되면 "deferred" 객체가 생성되어 Promise
와 함께 반환됩니다. deferred 객체는 생성된 Promise
에 바인딩되며 napi_resolve_deferred()
또는 napi_reject_deferred()
를 사용하여 Promise
를 해결하거나 거부하는 유일한 수단입니다. napi_create_promise()
에서 생성된 deferred 객체는 napi_resolve_deferred()
또는 napi_reject_deferred()
에 의해 해제됩니다. Promise
객체는 일반적인 방식으로 사용할 수 있는 JavaScript로 반환될 수 있습니다.
예를 들어, 프로미스를 생성하여 비동기 작업자에 전달하려면:
napi_deferred deferred;
napi_value promise;
napi_status status;
// 프로미스를 생성합니다.
status = napi_create_promise(env, &deferred, &promise);
if (status != napi_ok) return NULL;
// 비동기 작업을 수행하는 함수에 deferred를 전달합니다.
do_something_asynchronous(deferred);
// JS에 프로미스를 반환합니다.
return promise;
위의 함수 do_something_asynchronous()
는 비동기 작업을 수행한 다음 deferred를 해결하거나 거부하여 프로미스를 완료하고 deferred를 해제합니다.
napi_deferred deferred;
napi_value undefined;
napi_status status;
// deferred를 완료할 값을 생성합니다.
status = napi_get_undefined(env, &undefined);
if (status != napi_ok) return NULL;
// 비동기 작업이 성공했는지 여부에 따라 deferred와 연결된 프로미스를 해결하거나 거부합니다.
if (asynchronous_action_succeeded) {
status = napi_resolve_deferred(env, deferred, undefined);
} else {
status = napi_reject_deferred(env, deferred, undefined);
}
if (status != napi_ok) return NULL;
// 이 시점에서 deferred가 해제되었으므로 NULL을 할당해야 합니다.
deferred = NULL;
napi_create_promise
추가된 버전: v8.5.0
N-API 버전: 1
napi_status napi_create_promise(napi_env env,
napi_deferred* deferred,
napi_value* promise);
[in] env
: API가 호출되는 환경입니다.[out] deferred
: 새로 생성된 지연 객체로, 나중에napi_resolve_deferred()
또는napi_reject_deferred()
에 전달하여 연결된 프로미스를 각각 해결하거나 거부할 수 있습니다.[out] promise
: 지연 객체와 연결된 JavaScript 프로미스입니다.
API가 성공하면 napi_ok
를 반환합니다.
이 API는 지연 객체와 JavaScript 프로미스를 생성합니다.
napi_resolve_deferred
추가된 버전: v8.5.0
N-API 버전: 1
napi_status napi_resolve_deferred(napi_env env,
napi_deferred deferred,
napi_value resolution);
[in] env
: API가 호출되는 환경입니다.[in] deferred
: 해결할 연결된 프로미스가 있는 지연 객체입니다.[in] resolution
: 프로미스를 해결할 값입니다.
이 API는 연결된 지연 객체를 통해 JavaScript 프로미스를 해결합니다. 따라서 해당 지연 객체를 사용할 수 있는 JavaScript 프로미스를 해결하는 데만 사용할 수 있습니다. 이는 프로미스가 napi_create_promise()
를 사용하여 생성되어야 하며, 이 호출에서 반환된 지연 객체가 이 API에 전달하기 위해 보관되어야 함을 의미합니다.
지연 객체는 성공적으로 완료되면 해제됩니다.
napi_reject_deferred
추가된 버전: v8.5.0
N-API 버전: 1
napi_status napi_reject_deferred(napi_env env,
napi_deferred deferred,
napi_value rejection);
[in] env
: API가 호출되는 환경입니다.[in] deferred
: 해결할 연결된 프로미스가 있는 지연 객체입니다.[in] rejection
: 프로미스를 거부할 값입니다.
이 API는 연결된 지연 객체를 통해 JavaScript 프로미스를 거부합니다. 따라서 해당 지연 객체를 사용할 수 있는 JavaScript 프로미스를 거부하는 데만 사용할 수 있습니다. 이는 프로미스가 napi_create_promise()
를 사용하여 생성되어야 하며, 이 호출에서 반환된 지연 객체가 이 API에 전달하기 위해 보관되어야 함을 의미합니다.
지연 객체는 성공적으로 완료되면 해제됩니다.
napi_is_promise
추가된 버전: v8.5.0
N-API 버전: 1
napi_status napi_is_promise(napi_env env,
napi_value value,
bool* is_promise);
[in] env
: API가 호출되는 환경입니다.[in] value
: 검사할 값입니다.[out] is_promise
:promise
가 네이티브 Promise 객체(즉, 기본 엔진에 의해 생성된 Promise 객체)인지 여부를 나타내는 플래그입니다.
스크립트 실행
Node-API는 기본 JavaScript 엔진을 사용하여 JavaScript가 포함된 문자열을 실행하기 위한 API를 제공합니다.
napi_run_script
추가된 버전: v8.5.0
N-API 버전: 1
NAPI_EXTERN napi_status napi_run_script(napi_env env,
napi_value script,
napi_value* result);
[in] env
: API가 호출되는 환경입니다.[in] script
: 실행할 스크립트를 포함하는 JavaScript 문자열입니다.[out] result
: 스크립트 실행 결과로 생성된 값입니다.
이 함수는 다음과 같은 주의 사항과 함께 JavaScript 코드 문자열을 실행하고 그 결과를 반환합니다.
eval
과 달리 이 함수는 스크립트가 현재 어휘 범위에 액세스하는 것을 허용하지 않으므로 모듈 범위에 액세스하는 것도 허용하지 않습니다. 즉,require
와 같은 의사 전역 변수를 사용할 수 없습니다.- 스크립트는 전역 범위에 액세스할 수 있습니다. 스크립트의 함수 및
var
선언은global
객체에 추가됩니다.let
및const
를 사용하여 만든 변수 선언은 전역적으로 표시되지만global
객체에 추가되지는 않습니다. this
값은 스크립트 내에서global
입니다.
libuv 이벤트 루프
Node-API는 특정 napi_env
와 연결된 현재 이벤트 루프를 가져오기 위한 함수를 제공합니다.
napi_get_uv_event_loop
추가된 버전: v9.3.0, v8.10.0
N-API 버전: 2
NAPI_EXTERN napi_status napi_get_uv_event_loop(node_api_basic_env env,
struct uv_loop_s** loop);
[in] env
: API가 호출되는 환경입니다.[out] loop
: 현재 libuv 루프 인스턴스입니다.
참고: libuv는 시간이 지남에 따라 비교적 안정적이지만 ABI 안정성을 보장하지 않습니다. 이 함수의 사용은 피해야 합니다. 이 함수를 사용하면 Node.js 버전에서 작동하지 않는 애드온이 생길 수 있습니다. 많은 사용 사례에서 비동기식 스레드 안전 함수 호출이 대안입니다.
비동기 스레드 안전 함수 호출
JavaScript 함수는 일반적으로 네이티브 애드온의 메인 스레드에서만 호출할 수 있습니다. 애드온이 추가 스레드를 생성하는 경우 napi_env
, napi_value
또는 napi_ref
가 필요한 Node-API 함수는 해당 스레드에서 호출해서는 안 됩니다.
애드온에 추가 스레드가 있고 해당 스레드에서 완료한 처리를 기반으로 JavaScript 함수를 호출해야 하는 경우 해당 스레드는 애드온의 메인 스레드와 통신하여 메인 스레드가 대신 JavaScript 함수를 호출할 수 있도록 해야 합니다. 스레드 안전 함수 API는 이를 쉽게 수행할 수 있는 방법을 제공합니다.
이러한 API는 napi_threadsafe_function
유형과 이 유형의 객체를 만들고 파괴하고 호출하는 API를 제공합니다. napi_create_threadsafe_function()
은 여러 스레드에서 호출할 수 있는 JavaScript 함수를 보유하는 napi_value
에 대한 영구 참조를 만듭니다. 호출은 비동기적으로 발생합니다. 즉, JavaScript 콜백을 호출하는 값은 큐에 배치되고 큐의 각 값에 대해 결국 JavaScript 함수가 호출됩니다.
napi_threadsafe_function
을 생성할 때 napi_finalize
콜백을 제공할 수 있습니다. 이 콜백은 스레드 안전 함수가 파괴되려고 할 때 메인 스레드에서 호출됩니다. 생성하는 동안 제공된 컨텍스트와 마무리 데이터를 수신하고 uv_thread_join()
을 호출하여 스레드 이후에 정리할 기회를 제공합니다. 메인 루프 스레드 외에 마무리 콜백이 완료된 후에는 어떤 스레드도 스레드 안전 함수를 사용해서는 안 됩니다.
napi_create_threadsafe_function()
호출 중에 주어진 context
는 napi_get_threadsafe_function_context()
를 호출하여 모든 스레드에서 검색할 수 있습니다.
스레드 안전 함수 호출
napi_call_threadsafe_function()
은 JavaScript로 호출을 시작하는 데 사용할 수 있습니다. napi_call_threadsafe_function()
은 API가 블로킹 방식으로 동작할지 여부를 제어하는 매개변수를 허용합니다. napi_tsfn_nonblocking
으로 설정되면 API는 비 블로킹 방식으로 동작하며 큐가 가득 차서 데이터를 큐에 성공적으로 추가할 수 없으면 napi_queue_full
을 반환합니다. napi_tsfn_blocking
으로 설정되면 API는 큐에 공간이 생길 때까지 차단됩니다. 스레드 안전 함수가 최대 큐 크기가 0으로 생성된 경우 napi_call_threadsafe_function()
은 차단되지 않습니다.
큐가 가득 찬 경우 JavaScript 스레드가 교착 상태에 빠질 수 있으므로 JavaScript 스레드에서 napi_tsfn_blocking
으로 napi_call_threadsafe_function()
을 호출해서는 안 됩니다.
JavaScript로의 실제 호출은 call_js_cb
매개변수를 통해 제공된 콜백에 의해 제어됩니다. call_js_cb
는 napi_call_threadsafe_function()
에 대한 성공적인 호출로 큐에 배치된 각 값에 대해 한 번씩 메인 스레드에서 호출됩니다. 이러한 콜백이 제공되지 않으면 기본 콜백이 사용되고 결과 JavaScript 호출에는 인수가 없습니다. call_js_cb
콜백은 해당 매개변수에서 호출할 JavaScript 함수를 napi_value
로 받습니다. 또한 napi_threadsafe_function
을 만들 때 사용한 void*
컨텍스트 포인터와 보조 스레드 중 하나에서 만든 다음 데이터 포인터를 받습니다. 그런 다음 콜백은 napi_call_function()
과 같은 API를 사용하여 JavaScript를 호출할 수 있습니다.
또한 콜백은 JavaScript 호출이 더 이상 가능하지 않다는 것을 나타내기 위해 env
및 call_js_cb
가 모두 NULL
로 설정되어 호출될 수 있으며, 이 경우 큐에 해제해야 할 항목이 남아 있을 수 있습니다. 일반적으로 Node.js 프로세스가 활성 상태인 스레드 안전 함수가 있는 동안 종료될 때 발생합니다.
Node-API가 콜백에 적합한 컨텍스트에서 call_js_cb
를 실행하므로 napi_make_callback()
을 통해 JavaScript를 호출할 필요는 없습니다.
이벤트 루프의 각 틱에서 0개 이상의 큐에 대기 중인 항목을 호출할 수 있습니다. 응용 프로그램은 콜백 호출 진행이 이루어지고 시간이 지남에 따라 이벤트가 호출된다는 것 외에 특정 동작에 의존해서는 안 됩니다.
스레드 안전 함수의 참조 카운팅
스레드는 존재하는 동안 napi_threadsafe_function
객체에 추가 및 제거될 수 있습니다. 따라서 생성 시 초기 스레드 수를 지정하는 것 외에도 napi_acquire_threadsafe_function
을 호출하여 새 스레드가 스레드 안전 함수를 사용하기 시작함을 나타낼 수 있습니다. 마찬가지로 napi_release_threadsafe_function
을 호출하여 기존 스레드가 스레드 안전 함수 사용을 중단함을 나타낼 수 있습니다.
napi_threadsafe_function
객체는 객체를 사용하는 모든 스레드가 napi_release_threadsafe_function()
을 호출하거나 napi_call_threadsafe_function
호출에 대한 응답으로 napi_closing
반환 상태를 받은 경우 소멸됩니다. napi_threadsafe_function
이 소멸되기 전에 큐가 비워집니다. napi_release_threadsafe_function()
은 주어진 napi_threadsafe_function
과 관련하여 수행되는 마지막 API 호출이어야 합니다. 호출이 완료된 후에는 napi_threadsafe_function
이 여전히 할당되어 있다고 보장할 수 없기 때문입니다. 같은 이유로 napi_call_threadsafe_function
호출에 대한 응답으로 napi_closing
반환 값을 받은 후에는 스레드 안전 함수를 사용하지 마십시오. napi_threadsafe_function
과 관련된 데이터는 napi_create_threadsafe_function()
에 전달된 napi_finalize
콜백에서 해제할 수 있습니다. napi_create_threadsafe_function
의 파라미터 initial_thread_count
는 생성 시 napi_acquire_threadsafe_function
을 여러 번 호출하는 대신 스레드 안전 함수의 초기 획득 횟수를 표시합니다.
napi_threadsafe_function
을 사용하는 스레드 수가 0에 도달하면 napi_acquire_threadsafe_function()
을 호출하여 더 이상 스레드를 사용할 수 없습니다. 실제로 napi_release_threadsafe_function()
을 제외한 모든 후속 API 호출은 napi_closing
오류 값을 반환합니다.
napi_release_threadsafe_function()
에 napi_tsfn_abort
값을 제공하여 스레드 안전 함수를 "중단"할 수 있습니다. 이렇게 하면 참조 카운트가 0에 도달하기 전에도 napi_release_threadsafe_function()
을 제외한 스레드 안전 함수와 관련된 모든 후속 API가 napi_closing
을 반환합니다. 특히 napi_call_threadsafe_function()
은 napi_closing
을 반환하므로 스레드 안전 함수에 대한 비동기 호출을 더 이상 할 수 없음을 스레드에 알립니다. 이는 스레드를 종료하기 위한 기준으로 사용할 수 있습니다. napi_call_threadsafe_function()
에서 napi_closing
반환 값을 받으면 스레드는 더 이상 스레드 안전 함수를 사용해서는 안됩니다. 스레드 안전 함수가 더 이상 할당되어 있다고 보장할 수 없기 때문입니다.
프로세스를 계속 실행할지 여부 결정
libuv 핸들과 유사하게, 스레드로부터 안전한 함수는 "참조"되고 "참조 해제"될 수 있습니다. "참조된" 스레드로부터 안전한 함수는 해당 함수가 생성된 스레드의 이벤트 루프가 스레드로부터 안전한 함수가 소멸될 때까지 살아있게 합니다. 반대로, "참조 해제된" 스레드로부터 안전한 함수는 이벤트 루프가 종료되는 것을 방지하지 않습니다. napi_ref_threadsafe_function
및 napi_unref_threadsafe_function
API는 이러한 목적을 위해 존재합니다.
napi_unref_threadsafe_function
은 스레드로부터 안전한 함수를 소멸될 수 있는 것으로 표시하지 않으며, napi_ref_threadsafe_function
은 소멸되는 것을 방지하지도 않습니다.
napi_create_threadsafe_function
[기록]
버전 | 변경 사항 |
---|---|
v12.6.0, v10.17.0 | 사용자 정의 call_js_cb 로 func 매개변수를 선택 사항으로 만듦. |
v10.6.0 | v10.6.0에 추가됨 |
N-API 버전: 4
NAPI_EXTERN napi_status
napi_create_threadsafe_function(napi_env env,
napi_value func,
napi_value async_resource,
napi_value async_resource_name,
size_t max_queue_size,
size_t initial_thread_count,
void* thread_finalize_data,
napi_finalize thread_finalize_cb,
void* context,
napi_threadsafe_function_call_js call_js_cb,
napi_threadsafe_function* result);
[in] env
: API가 호출되는 환경입니다.[in] func
: 다른 스레드에서 호출할 선택적 JavaScript 함수입니다.NULL
이call_js_cb
에 전달된 경우 반드시 제공해야 합니다.[in] async_resource
: 가능한async_hooks
init
후크에 전달될 비동기 작업과 관련된 선택적 객체입니다.[in] async_resource_name
:async_hooks
API에서 노출된 진단 정보를 위해 제공되는 리소스 종류에 대한 식별자를 제공하는 JavaScript 문자열입니다.[in] max_queue_size
: 큐의 최대 크기입니다. 제한이 없으면0
입니다.[in] initial_thread_count
: 초기 획득 수, 즉 이 함수를 사용하는 메인 스레드를 포함한 초기 스레드 수입니다.[in] thread_finalize_data
:thread_finalize_cb
에 전달할 선택적 데이터입니다.[in] thread_finalize_cb
:napi_threadsafe_function
이 소멸될 때 호출할 선택적 함수입니다.[in] context
: 결과napi_threadsafe_function
에 첨부할 선택적 데이터입니다.[in] call_js_cb
: 다른 스레드에서의 호출에 대한 응답으로 JavaScript 함수를 호출하는 선택적 콜백입니다. 이 콜백은 메인 스레드에서 호출됩니다. 제공되지 않으면 JavaScript 함수는 매개변수 없이,undefined
를this
값으로 사용하여 호출됩니다.napi_threadsafe_function_call_js
는 더 자세한 정보를 제공합니다.[out] result
: 비동기 스레드로부터 안전한 JavaScript 함수입니다.
변경 내역:
- 실험적 (
NAPI_EXPERIMENTAL
정의됨):call_js_cb
에서 던져진 포착되지 않은 예외는 무시되는 대신'uncaughtException'
이벤트로 처리됩니다.
napi_get_threadsafe_function_context
추가된 버전: v10.6.0
N-API 버전: 4
NAPI_EXTERN napi_status
napi_get_threadsafe_function_context(napi_threadsafe_function func,
void** result);
[in] func
: 컨텍스트를 검색할 스레드 안전 함수입니다.[out] result
: 컨텍스트를 저장할 위치입니다.
이 API는 func
를 사용하는 모든 스레드에서 호출할 수 있습니다.
napi_call_threadsafe_function
[기록]
버전 | 변경 사항 |
---|---|
v14.5.0 | napi_would_deadlock 에 대한 지원이 되돌려졌습니다. |
v14.1.0 | 메인 스레드 또는 워커 스레드에서 napi_tsfn_blocking 으로 호출하고 큐가 가득 찬 경우 napi_would_deadlock 을 반환합니다. |
v10.6.0 | 추가된 버전: v10.6.0 |
N-API 버전: 4
NAPI_EXTERN napi_status
napi_call_threadsafe_function(napi_threadsafe_function func,
void* data,
napi_threadsafe_function_call_mode is_blocking);
[in] func
: 호출할 비동기 스레드 안전 JavaScript 함수입니다.[in] data
: 스레드 안전 JavaScript 함수 생성 중에 제공된 콜백call_js_cb
를 통해 JavaScript로 보낼 데이터입니다.[in] is_blocking
: 큐가 가득 찬 경우 호출이 차단되어야 함을 나타내는napi_tsfn_blocking
또는 큐가 가득 찰 때마다napi_queue_full
상태로 즉시 반환해야 함을 나타내는napi_tsfn_nonblocking
중 하나의 값을 가질 수 있는 플래그입니다.
이 API는 큐가 가득 찬 경우 JavaScript 스레드가 교착 상태에 빠질 수 있으므로 JavaScript 스레드에서 napi_tsfn_blocking
으로 호출해서는 안 됩니다.
이 API는 napi_release_threadsafe_function()
이 모든 스레드에서 abort
를 napi_tsfn_abort
로 설정하여 호출된 경우 napi_closing
을 반환합니다. 이 값은 API가 napi_ok
를 반환하는 경우에만 큐에 추가됩니다.
이 API는 func
를 사용하는 모든 스레드에서 호출할 수 있습니다.
napi_acquire_threadsafe_function
추가된 버전: v10.6.0
N-API 버전: 4
NAPI_EXTERN napi_status
napi_acquire_threadsafe_function(napi_threadsafe_function func);
[in] func
: 사용을 시작할 비동기 스레드 안전 JavaScript 함수입니다.
스레드는 func
를 사용할 것임을 나타내기 위해 다른 스레드 안전 함수 API에 전달하기 전에 이 API를 호출해야 합니다. 이렇게 하면 다른 모든 스레드가 사용을 중지했을 때 func
가 소멸되는 것을 방지합니다.
이 API는 func
를 사용하기 시작할 모든 스레드에서 호출할 수 있습니다.
napi_release_threadsafe_function
추가됨: v10.6.0
N-API 버전: 4
NAPI_EXTERN napi_status
napi_release_threadsafe_function(napi_threadsafe_function func,
napi_threadsafe_function_release_mode mode);
[in] func
: 참조 횟수를 줄일 비동기 스레드 안전 JavaScript 함수입니다.[in] mode
: 현재 스레드가 스레드 안전 함수를 더 이상 호출하지 않음을 나타내기 위해napi_tsfn_release
로 설정하거나, 현재 스레드뿐만 아니라 다른 스레드도 스레드 안전 함수를 더 이상 호출하지 않아야 함을 나타내기 위해napi_tsfn_abort
로 설정할 수 있는 플래그입니다.napi_tsfn_abort
로 설정된 경우,napi_call_threadsafe_function()
을 추가로 호출하면napi_closing
이 반환되고 큐에 추가 값이 배치되지 않습니다.
스레드는 func
사용을 중지할 때 이 API를 호출해야 합니다. 이 API를 호출한 후 func
를 스레드 안전 API에 전달하면 func
가 삭제되었을 수 있으므로 정의되지 않은 결과가 발생합니다.
이 API는 func
사용을 중지하는 모든 스레드에서 호출할 수 있습니다.
napi_ref_threadsafe_function
추가됨: v10.6.0
N-API 버전: 4
NAPI_EXTERN napi_status
napi_ref_threadsafe_function(node_api_basic_env env, napi_threadsafe_function func);
[in] env
: API가 호출되는 환경입니다.[in] func
: 참조할 스레드 안전 함수입니다.
이 API는 func
가 삭제될 때까지 메인 스레드에서 실행 중인 이벤트 루프가 종료되지 않아야 함을 나타내는 데 사용됩니다. uv_ref
와 유사하게 멱등성입니다.
napi_unref_threadsafe_function
은 스레드 안전 함수를 삭제할 수 있는 것으로 표시하지 않으며 napi_ref_threadsafe_function
은 삭제되는 것을 방지하지 않습니다. napi_acquire_threadsafe_function
및 napi_release_threadsafe_function
을 해당 용도로 사용할 수 있습니다.
이 API는 메인 스레드에서만 호출할 수 있습니다.
napi_unref_threadsafe_function
추가됨: v10.6.0
N-API 버전: 4
NAPI_EXTERN napi_status
napi_unref_threadsafe_function(node_api_basic_env env, napi_threadsafe_function func);
[in] env
: API가 호출되는 환경입니다.[in] func
: 참조를 해제할 스레드 안전 함수입니다.
이 API는 func
가 삭제되기 전에 메인 스레드에서 실행 중인 이벤트 루프가 종료될 수 있음을 나타내는 데 사용됩니다. uv_unref
와 유사하게 멱등성입니다.
이 API는 메인 스레드에서만 호출할 수 있습니다.
기타 유틸리티
node_api_get_module_file_name
추가된 버전: v15.9.0, v14.18.0, v12.22.0
N-API 버전: 9
NAPI_EXTERN napi_status
node_api_get_module_file_name(node_api_basic_env env, const char** result);
[in] env
: API가 호출된 환경입니다.[out] result
: 애드온이 로드된 위치의 절대 경로를 포함하는 URL입니다. 로컬 파일 시스템의 파일의 경우file://
로 시작합니다. 문자열은 null로 종료되고env
가 소유하므로 수정하거나 해제해서는 안 됩니다.
애드온 로드 프로세스 중에 애드온의 파일 이름을 설정하는 데 실패한 경우 result
는 빈 문자열일 수 있습니다.