Node-API
Node-API (ранее N-API) — это API для создания нативных аддонов. Оно не зависит от используемой среды выполнения JavaScript (например, V8) и поддерживается в составе самого Node.js. Это API будет сохранять стабильность Application Binary Interface (ABI) в разных версиях Node.js. Оно призвано изолировать аддоны от изменений в используемом движке JavaScript и позволить модулям, скомпилированным для одной основной версии, работать в более поздних основных версиях Node.js без повторной компиляции. Более подробное объяснение приведено в руководстве по стабильности ABI.
Аддоны собираются и упаковываются с использованием тех же подходов и инструментов, что описаны в разделе «Аддоны на C++». Различается только набор API, используемых нативным кодом. Вместо API V8 или Native Abstractions for Node.js используются функции, доступные в Node-API.
API, предоставляемые Node-API, обычно используются для создания и обработки значений JavaScript. Концепции и операции, как правило, соответствуют понятиям, определённым в спецификации языка ECMA-262. У API есть следующие свойства:
- Все вызовы Node-API возвращают код состояния типа
napi_status. Этот код указывает, завершился ли вызов API успешно или с ошибкой. - Возвращаемое значение API передаётся через выходной параметр.
- Все значения JavaScript абстрагированы за непрозрачным типом с именем
napi_value. - При коде состояния, указывающем на ошибку, дополнительную информацию можно получить с помощью
napi_get_last_error_info. Подробнее см. в разделе об обработке ошибок «Обработка ошибок».
Написание аддонов на различных языках программирования
Node-API — это API на языке C, обеспечивающий стабильность ABI в разных версиях Node.js и для разных уровней компилятора. Благодаря этой гарантии стабильности можно писать аддоны на других языках программирования поверх Node-API. Сведения о поддержке других языков программирования и сред выполнения см. в разделе привязки языков и движков.
node-addon-api — официальная привязка для C++, предоставляющая более эффективный способ написания кода на C++, вызывающего Node-API. Эта обёртка представляет собой библиотеку, состоящую только из заголовочных файлов, и предоставляет встраиваемый API на C++. Двоичные файлы, собранные с помощью node-addon-api, зависят от символов функций на основе C из Node-API, экспортируемых Node.js. Ниже приведён пример node-addon-api:
Object obj = Object::New(env); obj["foo"] = String::New(env, "bar"); copy
Приведённый выше код на C++ для node-addon-api эквивалентен следующему коду Node-API на C:
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;
} copy В результате аддон использует только экспортируемые API на C. Хотя аддон написан на C++, он всё равно получает преимущества стабильности ABI, обеспечиваемой Node-API на C.
При использовании node-addon-api вместо API на C начните с документации по API для node-addon-api.
Ресурс Node-API содержит полезные вводные материалы и советы для разработчиков, которые только начинают работать с Node-API и node-addon-api. Дополнительные медиаматериалы доступны на странице «Медиаматериалы Node-API».
Последствия стабильности ABI
Хотя Node-API гарантирует стабильность ABI, другие компоненты Node.js такой гарантии не предоставляют, как и некоторые внешние библиотеки, используемые аддоном. В частности, для перечисленных ниже API не гарантируется стабильность ABI между основными версиями:
-
API Node.js на C++, доступные через любой из следующих способов
#include <node.h> #include <node_buffer.h> #include <node_version.h> #include <node_object_wrap.h> copy
-
API libuv, также входящие в состав Node.js и доступные через
#include <uv.h> copy
-
API V8, доступный через
#include <v8.h> copy
Таким образом, чтобы аддон сохранял совместимость ABI между основными версиями Node.js, он должен использовать исключительно Node-API, ограничиваясь
#include <node_api.h> copy
а также проверять, что каждая используемая им внешняя библиотека гарантирует стабильность ABI на уровне, сопоставимом с Node-API.
Значения перечислений при стабильности ABI
Все типы данных-перечисления, определённые в Node-API, следует считать значениями фиксированного размера типа int32_t. Для типов перечислений с битовыми флагами это должно быть явно указано в документации; они работают с побитовыми операторами, например побитовым OR (|), как с битовым значением. Если не указано иное, тип перечисления следует считать расширяемым.
Новое значение перечисления будет добавлено в конец его определения. Значения перечислений не удаляются и не переименовываются.
Для типа перечисления, возвращаемого функцией Node-API или передаваемого в качестве выходного параметра функции Node-API, значение является целым числом, и аддон должен обрабатывать неизвестные значения. Новые значения могут вводиться без проверки версии. Например, при проверке napi_status в инструкциях switch аддону следует включить ветвь default, поскольку в более новых версиях Node.js могут появиться новые коды состояния.
Для типа перечисления, используемого во входном параметре, результат передачи неизвестного целочисленного значения функциям Node-API не определён, если не указано иное. Новое значение добавляется с проверкой версии, указывающей версию Node-API, в которой оно появилось. Например, napi_get_all_property_names можно расширить новым значением перечисления napi_key_filter.
Для типа перечисления, используемого как во входных, так и в выходных параметрах, новые значения могут вводиться без проверки версии.
Сборка
В отличие от модулей, написанных на JavaScript, разработка и развёртывание нативных аддонов Node.js с использованием Node-API требуют дополнительного набора инструментов. Помимо базовых инструментов, необходимых для разработки под Node.js, разработчику нативных аддонов потребуется инструментальная цепочка, которая может компилировать код на C и C++ в двоичный файл. Кроме того, в зависимости от способа развёртывания нативного аддона, пользователю нативного аддона также потребуется установить инструментальную цепочку для C/C++.
Для разработчиков под Linux необходимые пакеты инструментальной цепочки C/C++ легко доступны. GCC широко используется в сообществе Node.js для сборки и тестирования на различных платформах. Для многих разработчиков хорошим выбором будет также инфраструктура компилятора LLVM.
Для разработчиков под Mac все необходимые инструменты компиляции предоставляет Xcode. Однако устанавливать всю среду разработки Xcode не обязательно. Следующая команда устанавливает необходимую инструментальную цепочку:
xcode-select --install copy
Для разработчиков под Windows все необходимые инструменты компиляции предоставляет Visual Studio. Однако устанавливать всю среду разработки Visual Studio не обязательно. Следующая команда устанавливает необходимую инструментальную цепочку:
npm install --global windows-build-tools copy
В разделах ниже описаны дополнительные инструменты для разработки и развёртывания нативных аддонов Node.js.
Инструменты сборки
Для успешной установки нативного аддона с помощью любого из перечисленных здесь инструментов пользователям потребуется установить инструментальную цепочку для C/C++.
node-gyp
node-gyp — это система сборки на основе форка gyp-next инструмента GYP от Google, которая входит в комплект npm. Для GYP и, следовательно, для node-gyp требуется установленный Python.
Исторически node-gyp был основным инструментом для сборки нативных аддонов. Он широко используется и хорошо документирован. Однако некоторые разработчики столкнулись с ограничениями node-gyp.
CMake.js
CMake.js — это альтернативная система сборки на основе CMake.
CMake.js хорошо подходит проектам, которые уже используют CMake, а также разработчикам, столкнувшимся с ограничениями node-gyp. build_with_cmake — пример проекта нативного аддона на основе CMake.
Загрузка предварительно скомпилированных двоичных файлов
Три перечисленных здесь инструмента позволяют разработчикам и сопровождающим нативных аддонов создавать двоичные файлы и загружать их на общедоступные или частные серверы. Эти инструменты обычно интегрируют с системами сборки CI/CD, такими как Travis CI и AppVeyor, чтобы собирать и загружать двоичные файлы для различных платформ и архитектур. Затем эти двоичные файлы становятся доступны для загрузки пользователям, которым не требуется устанавливать инструментальную цепочку 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 хорошо подходит для проектов на GitHub, использующих CMake.js.
prebuildify
prebuildify — это инструмент на основе node-gyp. Его преимущество в том, что при загрузке нативного аддона в npm собранные двоичные файлы включаются в его состав. Двоичные файлы загружаются из npm и сразу становятся доступны пользователю модуля при установке нативного аддона.
Использование
Чтобы использовать функции Node-API, включите файл node_api.h, расположенный в каталоге src дерева исходного кода Node.js:
#include <node_api.h> copy
Это позволит использовать значение NAPI_VERSION по умолчанию для данного выпуска Node.js. Чтобы обеспечить совместимость с определёнными версиями Node-API, версию можно явно указать при подключении заголовочного файла:
#define NAPI_VERSION 3 #include <node_api.h> copy
Это ограничивает набор Node-API только функциями, доступными в указанной версии и более ранних версиях.
Некоторые функции Node-API являются экспериментальными, и для их использования требуется явное согласие:
#define NAPI_EXPERIMENTAL #include <node_api.h> copy
В этом случае коду модуля будет доступен весь набор API, включая экспериментальные API.
Иногда вводятся экспериментальные функции, влияющие на уже выпущенные и стабильные API. Их можно отключить с помощью отказа от использования:
#define NAPI_EXPERIMENTAL #define NODE_API_EXPERIMENTAL_<FEATURE_NAME>_OPT_OUT #include <node_api.h> copy
где <FEATURE_NAME> — имя экспериментальной функции, влияющей как на экспериментальные, так и на стабильные API.
Матрица версий Node-API
До версии 9 версии Node-API были аддитивными и нумеровались независимо от Node.js. Это означало, что каждая версия расширяла предыдущую, включая все её API и некоторые дополнения. Каждая версия Node.js поддерживала только одну версию Node-API. Например, v18.15.0 поддерживает только Node-API версии 8. Стабильность ABI обеспечивалась тем, что версия 8 была строгим надмножеством всех предыдущих версий.
Начиная с версии 9, версии Node-API по-прежнему нумеруются независимо, однако для работы аддона с Node-API версии 9 в Node-API версии 10 могут потребоваться изменения кода. При этом стабильность ABI сохраняется, поскольку версии Node.js, поддерживающие Node-API выше версии 8, поддерживают все версии начиная с 8 и до самой старшей поддерживаемой версии и по умолчанию предоставляют API версии 8, если аддон не запрашивает более высокую версию Node-API. Такой подход позволяет эффективнее оптимизировать существующие функции Node-API, сохраняя стабильность ABI. Существующие аддоны могут продолжать работать без повторной компиляции, используя более раннюю версию Node-API. Если аддону требуются возможности новой версии Node-API, для использования этих новых функций всё равно понадобится изменить существующий код и повторно его скомпилировать.
В версиях Node.js, поддерживающих Node-API версии 9 и выше, определение NAPI_VERSION=X и использование существующих макросов инициализации аддона встраивают в аддон запрошенную версию Node-API, которая будет использоваться во время выполнения. Если NAPI_VERSION не задана, по умолчанию используется версия 8.
Эта таблица может быть неактуальна для старых веток; самая актуальная информация приведена в последней версии документации API: матрица версий Node-API
| Версия Node-API | Поддерживается в |
|---|---|
| 10 | v22.14.0+, 23.6.0+ и всех более поздних версиях |
| 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 или выше.
Для каждого API, документированного для Node-API, будет указан заголовочный файл added in:, а для стабильных API — также дополнительный заголовочный файл Node-API version:. API можно использовать напрямую в версиях Node.js, поддерживающих версию Node-API, указанную в Node-API version: или выше. Если используемая версия Node.js не поддерживает указанную в Node-API version: версию или если Node-API version: не указан, API будет доступен только в том случае, если перед подключением node_api.h или js_native_api.h указан #define NAPI_EXPERIMENTAL. Если API, по всей видимости, недоступен в версии Node.js более поздней, чем указанная в added in:, то, скорее всего, причина именно в этом.
API Node-API, предназначенные исключительно для доступа к возможностям ECMAScript из нативного кода, находятся отдельно в js_native_api.h и js_native_api_types.h. API, определённые в этих заголовочных файлах, включены в node_api.h и node_api_types.h. Такая структура заголовочных файлов позволяет реализовывать Node-API за пределами Node.js. Для таких реализаций API, специфичные для Node.js, могут быть неприменимы.
Части аддона, специфичные для Node.js, можно отделить от кода, предоставляющего фактическую функциональность среде JavaScript, чтобы последний можно было использовать с несколькими реализациями Node-API. В приведённом ниже примере addon.c и addon.h относятся только к js_native_api.h. Это позволяет повторно использовать addon.c для компиляции как с реализацией Node-API в Node.js, так и с любой реализацией Node-API за пределами Node.js.
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_ copy
// 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;
} copy // 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);
} copy API жизненного цикла среды
Раздел «Агенты» спецификации языка ECMAScript определяет понятие «агент» как автономную среду, в которой выполняется код JavaScript. Процесс может запускать и завершать несколько таких агентов одновременно или последовательно.
Среда Node.js соответствует агенту ECMAScript. В основном процессе среда создаётся при запуске, а дополнительные среды могут создаваться в отдельных потоках для работы в качестве рабочих потоков. Когда Node.js встроен в другое приложение, основной поток приложения также может многократно создавать и уничтожать среду Node.js в течение жизненного цикла процесса приложения. При этом каждая созданная приложением среда Node.js может, в свою очередь, в течение своего жизненного цикла создавать и уничтожать дополнительные среды в качестве рабочих потоков.
С точки зрения нативного аддона это означает, что предоставляемые им привязки могут вызываться многократно, из нескольких контекстов и даже одновременно из нескольких потоков.
Нативным аддонам может потребоваться выделять глобальное состояние, используемое ими на протяжении жизненного цикла среды Node.js, чтобы это состояние было уникальным для каждого экземпляра аддона.
Для этого Node-API предоставляет способ связывать данные с жизненным циклом среды Node.js.
napi_set_instance_data
napi_status napi_set_instance_data(node_api_basic_env env,
void* data,
napi_finalize finalize_cb,
void* finalize_hint); copy -
[in] env: Среда, в которой выполняется вызов Node-API. -
[in] data: Элемент данных, который необходимо предоставить привязкам этого экземпляра. -
[in] finalize_cb: Функция, вызываемая при завершении работы среды. Функция получаетdata, чтобы освободить его. Подробнее см. в разделеnapi_finalize. -
[in] finalize_hint: Необязательная подсказка, передаваемая функции обратного вызова финализации во время сборки мусора.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API связывает data с текущей выполняющейся средой Node.js. Позднее data можно получить с помощью napi_get_instance_data(). Все существующие данные, связанные с текущей выполняющейся средой Node.js предыдущим вызовом napi_set_instance_data(), будут перезаписаны. Если предыдущий вызов предоставил finalize_cb, она вызвана не будет.
napi_get_instance_data
napi_status napi_get_instance_data(node_api_basic_env env,
void** data); copy -
[in] env: Среда, в которой выполняется вызов Node-API. -
[out] data: Элемент данных, ранее связанный с текущей выполняющейся средой Node.js вызовомnapi_set_instance_data().
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API получает данные, ранее связанные с текущей выполняющейся средой Node.js с помощью napi_set_instance_data(). Если данные не заданы, вызов завершится успешно, а data будет установлено в NULL.
Основные типы данных Node-API
Node-API предоставляет следующие фундаментальные типы данных в виде абстракций, используемых различными API. Эти API следует считать непрозрачными; их можно исследовать только с помощью других вызовов Node-API.
napi_status
Целочисленный код состояния, указывающий на успешное выполнение или сбой вызова 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, /* unused */
napi_no_external_buffers_allowed,
napi_cannot_run_js
} napi_status; copy Если после возврата API кода состояния, указывающего на сбой, требуется дополнительная информация, ее можно получить, вызвав napi_get_last_error_info.
napi_extended_error_info
typedef struct {
const char* error_message;
void* engine_reserved;
uint32_t engine_error_code;
napi_status error_code;
} napi_extended_error_info; copy -
error_message: строка в кодировке UTF-8, содержащая не зависящее от виртуальной машины описание ошибки. -
engine_reserved: зарезервировано для сведений об ошибке, специфичных для виртуальной машины. В настоящее время эта возможность не реализована ни для одной виртуальной машины. -
engine_error_code: код ошибки, специфичный для виртуальной машины. В настоящее время эта возможность не реализована ни для одной виртуальной машины. -
error_code: код состояния Node-API, соответствующий последней ошибке.
Дополнительные сведения см. в разделе Обработка ошибок.
napi_env
napi_env используется для представления контекста, в котором реализация Node-API может сохранять состояние, специфичное для виртуальной машины. Эта структура передается нативным функциям при их вызове и должна передаваться обратно при вызове Node-API. В частности, в любых последующих вложенных вызовах Node-API необходимо передавать тот же napi_env, который был передан при первоначальном вызове нативной функции. Кэширование napi_env для общего повторного использования, а также передача napi_env между экземплярами одного и того же аддона, работающими в разных потоках Worker, запрещены. napi_env становится недействительным при выгрузке экземпляра нативного аддона. Уведомление об этом событии отправляется через обратные вызовы, переданные в napi_add_env_cleanup_hook и napi_set_instance_data.
node_api_basic_env
Этот вариант napi_env передается синхронным финализаторам (node_api_basic_finalize). Существует подмножество API Node-API, которые принимают параметр типа node_api_basic_env в качестве первого аргумента. Эти API не обращаются к состоянию движка JavaScript, поэтому их безопасно вызывать из синхронных финализаторов. Передавать параметр типа napi_env этим API разрешено, однако передавать параметр типа node_api_basic_env API, обращающимся к состоянию движка JavaScript, запрещено. Попытка сделать это без приведения типа приведет к предупреждению компилятора или ошибке, если аддоны компилируются с флагами, заставляющими выдавать предупреждения и/или ошибки при передаче в функцию указателей неверных типов. Вызов таких API из синхронного финализатора в конечном итоге приведет к завершению приложения.
napi_value
Это непрозрачный указатель, используемый для представления значения JavaScript.
napi_threadsafe_function
Это непрозрачный указатель, представляющий функцию JavaScript, которую можно асинхронно вызывать из нескольких потоков с помощью napi_call_threadsafe_function().
napi_threadsafe_function_release_mode
Значение, передаваемое в napi_release_threadsafe_function(), чтобы указать, следует ли немедленно закрыть потокобезопасную функцию (napi_tsfn_abort) или только освободить ее (napi_tsfn_release), оставив доступной для последующего использования через napi_acquire_threadsafe_function() и napi_call_threadsafe_function().
typedef enum {
napi_tsfn_release,
napi_tsfn_abort
} napi_threadsafe_function_release_mode; copy
napi_threadsafe_function_call_mode
Значение, передаваемое в napi_call_threadsafe_function(), чтобы указать, должен ли вызов блокироваться, когда очередь, связанная с потокобезопасной функцией, заполнена.
typedef enum {
napi_tsfn_nonblocking,
napi_tsfn_blocking
} napi_threadsafe_function_call_mode; copy Типы Node-API для управления памятью
napi_handle_scope
Это абстракция, используемая для управления и изменения времени жизни объектов, созданных в определенной области видимости. Как правило, значения Node-API создаются в контексте области дескрипторов. При вызове нативного метода из JavaScript существует область дескрипторов по умолчанию. Если пользователь явно не создает новую область дескрипторов, значения Node-API создаются в области дескрипторов по умолчанию. При любом выполнении кода вне вызова нативного метода (например, во время вызова обратного вызова libuv) модуль должен создать область видимости до вызова любых функций, которые могут привести к созданию значений JavaScript.
Области дескрипторов создаются с помощью napi_open_handle_scope и уничтожаются с помощью napi_close_handle_scope. Закрытие области видимости может сообщить сборщику мусора, что все napi_value, созданные за время существования области дескрипторов, больше не используются текущим кадром стека.
Подробнее см. в разделе Управление временем жизни объектов.
napi_escapable_handle_scope
Области дескрипторов с возможностью выхода — это особый тип областей дескрипторов, позволяющий возвращать значения, созданные в определенной области дескрипторов, в родительскую область.
napi_ref
Это абстракция для создания ссылки на napi_value. Она позволяет пользователям управлять временем жизни значений JavaScript, в том числе явно задавать минимальное время их существования.
Подробнее см. в разделе Управление временем жизни объектов.
napi_type_tag
128-битное значение, хранящееся в виде двух беззнаковых 64-битных целых чисел. Оно служит UUID, которым можно «помечать» объекты JavaScript или внешние объекты, чтобы гарантировать, что они относятся к определенному типу. Это более надежная проверка, чем napi_instanceof, поскольку последняя может дать ложноположительный результат, если прототип объекта был изменен. Пометка типа особенно полезна в сочетании с napi_wrap, поскольку она гарантирует, что указатель, полученный из обернутого объекта, можно безопасно привести к нативному типу, соответствующему метке типа, ранее примененной к объекту JavaScript.
typedef struct {
uint64_t lower;
uint64_t upper;
} napi_type_tag; copy
napi_async_cleanup_hook_handle
Непрозрачное значение, возвращаемое napi_add_async_cleanup_hook. После завершения цепочки событий асинхронной очистки его необходимо передать в napi_remove_async_cleanup_hook.
Типы обратных вызовов Node-API
napi_callback_info
Непрозрачный тип данных, передаваемый функции обратного вызова. Его можно использовать для получения дополнительных сведений о контексте, в котором был вызван обратный вызов.
napi_callback
Тип указателя на функцию для предоставляемых пользователем нативных функций, доступных из JavaScript через Node-API. Функции обратного вызова должны соответствовать следующей сигнатуре:
typedef napi_value (*napi_callback)(napi_env, napi_callback_info); copy
За исключением случаев, обсуждаемых в разделе Управление временем жизни объектов, создавать область дескрипторов и/или область обратного вызова внутри napi_callback не требуется.
node_api_basic_finalize
Тип указателя на функцию, предоставляемую аддоном и позволяющую уведомить пользователя о том, что принадлежащие внешнему коду данные готовы к очистке, поскольку связанный с ними объект был удален сборщиком мусора. Пользователь должен предоставить функцию, соответствующую следующей сигнатуре; она будет вызвана при сборе объекта. В настоящее время для определения момента сбора объектов с внешними данными можно использовать node_api_basic_finalize.
typedef void (*node_api_basic_finalize)(node_api_basic_env env,
void* finalize_data,
void* finalize_hint); copy За исключением случаев, обсуждаемых в разделе Управление временем жизни объектов, создавать область дескрипторов и/или область обратного вызова внутри тела функции не требуется.
Поскольку эти функции могут вызываться в состоянии, когда движок JavaScript не может выполнять код JavaScript, разрешено вызывать только API Node-API, принимающие node_api_basic_env в качестве первого параметра. С помощью node_api_post_finalizer можно запланировать выполнение вызовов Node-API, требующих доступа к состоянию движка JavaScript, после завершения текущего цикла сборки мусора.
В случае node_api_create_external_string_latin1 и node_api_create_external_string_utf16 параметр env может быть равен null, поскольку внешние строки могут быть собраны на заключительном этапе завершения работы окружения.
История изменений:
-
экспериментальная возможность (
NAPI_EXPERIMENTAL):Разрешено вызывать только функции Node-API, принимающие
node_api_basic_envв качестве первого параметра; в противном случае приложение будет завершено с соответствующим сообщением об ошибке. Эту возможность можно отключить, определивNODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT.
napi_finalize
Тип указателя на функцию, предоставляемую аддоном и позволяющую пользователю запланировать группу вызовов API Node-API в ответ на событие сборки мусора после завершения цикла сборки мусора. Эти указатели на функции можно использовать с node_api_post_finalizer.
typedef void (*napi_finalize)(napi_env env,
void* finalize_data,
void* finalize_hint); copy История изменений:
-
экспериментальная возможность (определен
NAPI_EXPERIMENTAL):Функцию этого типа больше нельзя использовать в качестве финализатора, за исключением случаев с
node_api_post_finalizer. Вместо нее необходимо использоватьnode_api_basic_finalize. Эту возможность можно отключить, определивNODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT.
napi_async_execute_callback
Указатель на функцию, используемый функциями, поддерживающими асинхронные операции. Функции обратного вызова должны соответствовать следующей сигнатуре:
typedef void (*napi_async_execute_callback)(napi_env env, void* data); copy
Реализациям этой функции следует избегать вызовов Node-API, которые выполняют код JavaScript или взаимодействуют с объектами JavaScript. Вызовы Node-API следует выполнять вместо этого в napi_async_complete_callback. Не используйте параметр napi_env, поскольку это, вероятно, приведет к выполнению JavaScript.
napi_async_complete_callback
Указатель на функцию, используемый функциями, поддерживающими асинхронные операции. Функции обратного вызова должны соответствовать следующей сигнатуре:
typedef void (*napi_async_complete_callback)(napi_env env,
napi_status status,
void* data); copy За исключением случаев, обсуждаемых в разделе Управление временем жизни объектов, создавать область дескрипторов и/или область обратного вызова внутри тела функции не требуется.
napi_threadsafe_function_call_js
Указатель на функцию, используемый при асинхронных вызовах потокобезопасной функции. Обратный вызов будет выполнен в основном потоке. Его назначение — использовать элемент данных, поступивший через очередь из одного из вторичных потоков, для создания параметров, необходимых для вызова JavaScript, обычно через napi_call_function, а затем выполнить вызов JavaScript.
Данные, поступившие из вторичного потока через очередь, передаются в параметре data, а вызываемая функция JavaScript — в параметре js_callback.
Node-API настраивает окружение перед вызовом этого обратного вызова, поэтому достаточно вызвать функцию JavaScript через napi_call_function, а не через napi_make_callback.
Функции обратного вызова должны соответствовать следующей сигнатуре:
typedef void (*napi_threadsafe_function_call_js)(napi_env env,
napi_value js_callback,
void* context,
void* data); copy -
[in] env: окружение, используемое для вызовов API, илиNULL, если потокобезопасная функция завершает работу и, возможно, потребуется освободитьdata. -
[in] js_callback: вызываемая функция JavaScript илиNULL, если потокобезопасная функция завершает работу и, возможно, потребуется освободитьdata. Значение также может бытьNULL, если потокобезопасная функция была создана безjs_callback. -
[in] context: необязательные данные, с которыми была создана потокобезопасная функция. -
[in] data: данные, созданные вторичным потоком. Обратный вызов должен преобразовать эти нативные данные в значения JavaScript (с помощью функций Node-API), которые можно передать в качестве параметров при вызовеjs_callback. Этот указатель полностью контролируется потоками и данным обратным вызовом. Поэтому обратный вызов должен освободить эти данные.
За исключением случаев, обсуждаемых в разделе Управление временем жизни объектов, создавать область дескрипторов и/или область обратного вызова внутри тела функции не требуется.
napi_cleanup_hook
Указатель на функцию, используемый с napi_add_env_cleanup_hook. Он будет вызван при завершении работы окружения.
Функции обратного вызова должны соответствовать следующей сигнатуре:
typedef void (*napi_cleanup_hook)(void* data); copy
-
[in] data: данные, переданные вnapi_add_env_cleanup_hook.
napi_async_cleanup_hook
Указатель на функцию, используемый с napi_add_async_cleanup_hook. Он будет вызван при завершении работы окружения.
Функции обратного вызова должны соответствовать следующей сигнатуре:
typedef void (*napi_async_cleanup_hook)(napi_async_cleanup_hook_handle handle,
void* data); copy -
[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.
Возвращаемым значением будет napi_ok, если запрос выполнен успешно и не было выброшено необработанное исключение JavaScript. Если произошла ошибка И было выброшено исключение, будет возвращено значение napi_status для этой ошибки. Если исключение было выброшено, но ошибки не произошло, будет возвращено napi_pending_exception.
Если возвращено значение, отличное от napi_ok или napi_pending_exception, необходимо вызвать napi_is_exception_pending, чтобы проверить, ожидает ли обработки исключение. Подробнее см. в разделе об исключениях.
Полный набор возможных значений napi_status определён в napi_api_types.h.
Возвращаемое значение napi_status предоставляет независимое от виртуальной машины представление возникшей ошибки. В некоторых случаях полезно получить более подробную информацию, в том числе строковое представление ошибки и сведения, специфичные для виртуальной машины (движка).
Для получения этой информации предусмотрена функция napi_get_last_error_info, которая возвращает структуру napi_extended_error_info. Формат структуры napi_extended_error_info:
typedef struct napi_extended_error_info {
const char* error_message;
void* engine_reserved;
uint32_t engine_error_code;
napi_status error_code;
}; copy -
error_message: Текстовое представление возникшей ошибки. -
engine_reserved: Непрозрачный дескриптор, зарезервированный исключительно для использования движком. -
engine_error_code: Код ошибки, специфичный для виртуальной машины. -
error_code: Код состояния Node-API для последней ошибки.
napi_get_last_error_info возвращает сведения о последнем вызове Node-API.
Не полагайтесь на содержимое или формат каких-либо дополнительных сведений: на них не распространяются правила SemVer, и они могут измениться в любой момент. Эти сведения предназначены только для ведения журналов.
napi_get_last_error_info
napi_status
napi_get_last_error_info(node_api_basic_env env,
const napi_extended_error_info** result); copy -
[in] env: Среда, в которой вызывается API. -
[out] result: Структураnapi_extended_error_infoс дополнительными сведениями об ошибке.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API извлекает структуру napi_extended_error_info со сведениями о последней возникшей ошибке.
Содержимое возвращённой структуры napi_extended_error_info действительно только до тех пор, пока для той же env не будет вызвана функция Node-API. Это относится и к вызову napi_is_exception_pending, поэтому часто необходимо скопировать сведения, чтобы использовать их позже. Указатель, возвращённый в error_message, указывает на статически определённую строку, поэтому его можно безопасно использовать, если перед вызовом другой функции Node-API скопировать её из поля error_message (которое будет перезаписано).
Не полагайтесь на содержимое или формат каких-либо дополнительных сведений: на них не распространяются правила SemVer, и они могут измениться в любой момент. Эти сведения предназначены только для ведения журналов.
Этот API можно вызывать, даже если ожидает обработки исключение JavaScript.
Исключения
Вызов любой функции Node-API может привести к появлению ожидающего обработки исключения JavaScript. Это относится ко всем функциям API, даже к тем, которые не могут вызвать выполнение JavaScript.
Если функция возвращает napi_status со значением napi_ok, исключение не ожидает обработки и дополнительных действий не требуется. Если возвращённое значение napi_status отличается от napi_ok и napi_pending_exception, для попытки восстановить выполнение и продолжить работу, а не просто немедленно вернуться, необходимо вызвать napi_is_exception_pending, чтобы определить, ожидает ли обработки исключение.
Во многих случаях при вызове функции Node-API, когда исключение уже ожидает обработки, функция немедленно возвращает значение napi_status, равное napi_pending_exception. Однако так происходит не со всеми функциями. Node-API допускает вызов некоторых функций, чтобы выполнить минимально необходимую очистку перед возвратом в JavaScript. В этом случае napi_status отражает состояние функции, а не предыдущих ожидающих обработки исключений. Во избежание путаницы проверяйте состояние ошибки после каждого вызова функции.
При наличии ожидающего обработки исключения можно использовать один из двух подходов.
Первый подход — выполнить необходимые действия по очистке, а затем вернуться, чтобы передать управление JavaScript. При возврате к JavaScript исключение будет выброшено в том месте кода JavaScript, где был вызван нативный метод. Поведение большинства вызовов Node-API при наличии ожидающего обработки исключения не определено, и многие из них просто возвращают napi_pending_exception, поэтому выполните как можно меньше действий, а затем вернитесь в JavaScript, где можно обработать исключение.
Второй подход — попытаться обработать исключение. В некоторых случаях нативный код может перехватить исключение, выполнить необходимые действия и продолжить работу. Это рекомендуется только в тех случаях, когда точно известно, что исключение можно безопасно обработать. Для этого можно использовать napi_get_and_clear_last_exception, чтобы получить исключение и очистить его. При успешном выполнении результат будет содержать дескриптор последнего выброшенного значения JavaScript Object. Если после получения исключения выяснится, что обработать его всё же невозможно, его можно выбросить повторно с помощью napi_throw, где error — значение JavaScript, которое нужно выбросить.
Также доступны следующие вспомогательные функции на случай, если нативному коду потребуется выбросить исключение или определить, является ли 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 — это napi_value, ссылающийся на только что созданный объект JavaScript Error.
Проект Node.js добавляет к каждой внутренне сгенерированной ошибке код ошибки. Цель состоит в том, чтобы приложения использовали эти коды для всех проверок ошибок. Связанные с ними сообщения об ошибках сохранятся, но будут предназначены только для ведения журналов и отображения; предполагается, что сообщение может измениться без применения правил SemVer. Для поддержки этой модели в Node-API — как во внутренней функциональности, так и в функциональности модулей (что считается хорошей практикой) — функции throw_ и create_ принимают необязательный параметр code — строку с кодом, который будет добавлен к объекту ошибки. Если необязательный параметр равен NULL, код не будет связан с ошибкой. Если код указан, имя, связанное с ошибкой, также будет изменено следующим образом:
originalName [code] copy
где originalName — исходное имя, связанное с ошибкой, а code — указанный код. Например, если код равен 'ERR_ERROR_1' и создаётся TypeError, имя будет таким:
TypeError [ERR_ERROR_1] copy
napi_throw
NAPI_EXTERN napi_status napi_throw(napi_env env, napi_value error); copy
-
[in] env: Среда, в которой вызывается API. -
[in] error: Значение JavaScript, которое нужно выбросить.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API выбрасывает указанное значение JavaScript.
napi_throw_error
NAPI_EXTERN napi_status napi_throw_error(napi_env env,
const char* code,
const char* msg); copy -
[in] env: Среда, в которой вызывается API. -
[in] code: Необязательный код ошибки, который будет задан для ошибки. -
[in] msg: Строка C, содержащая текст, который будет связан с ошибкой.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API выбрасывает ошибку JavaScript Error с указанным текстом.
napi_throw_type_error
NAPI_EXTERN napi_status napi_throw_type_error(napi_env env,
const char* code,
const char* msg); copy -
[in] env: Среда, в которой вызывается API. -
[in] code: Необязательный код ошибки, который будет задан для ошибки. -
[in] msg: Строка C, содержащая текст, который будет связан с ошибкой.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API выбрасывает ошибку JavaScript TypeError с указанным текстом.
napi_throw_range_error
NAPI_EXTERN napi_status napi_throw_range_error(napi_env env,
const char* code,
const char* msg); copy -
[in] env: Среда, в которой вызывается API. -
[in] code: Необязательный код ошибки, который будет задан для ошибки. -
[in] msg: Строка C, содержащая текст, который будет связан с ошибкой.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API выбрасывает ошибку JavaScript RangeError с указанным текстом.
node_api_throw_syntax_error
NAPI_EXTERN napi_status node_api_throw_syntax_error(napi_env env,
const char* code,
const char* msg); copy -
[in] env: Среда, в которой вызывается API. -
[in] code: Необязательный код ошибки, который будет задан для ошибки. -
[in] msg: Строка C, содержащая текст, который будет связан с ошибкой.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API выбрасывает ошибку JavaScript SyntaxError с указанным текстом.
napi_is_error
NAPI_EXTERN napi_status napi_is_error(napi_env env,
napi_value value,
bool* result); copy -
[in] env: Среда, в которой вызывается API. -
[in] value: Проверяемое значениеnapi_value. -
[out] result: Логическое значение, которому присваивается true, еслиnapi_valueпредставляет ошибку, и false в противном случае.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API проверяет napi_value, чтобы определить, представляет ли оно объект ошибки.
napi_create_error
NAPI_EXTERN napi_status napi_create_error(napi_env env,
napi_value code,
napi_value msg,
napi_value* result); copy -
[in] env: Среда, в которой вызывается API. -
[in] code: Необязательныйnapi_valueсо строкой кода ошибки, который будет связан с ошибкой. -
[in] msg:napi_value, ссылающийся на объект JavaScriptstring, который будет использоваться в качестве сообщения дляError. -
[out] result:napi_value, представляющий созданную ошибку.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API возвращает ошибку JavaScript Error с указанным текстом.
napi_create_type_error
NAPI_EXTERN napi_status napi_create_type_error(napi_env env,
napi_value code,
napi_value msg,
napi_value* result); copy -
[in] env: Среда, в которой вызывается API. -
[in] code: Необязательныйnapi_valueсо строкой кода ошибки, который будет связан с ошибкой. -
[in] msg:napi_value, ссылающийся на объект JavaScriptstring, который будет использоваться в качестве сообщения дляError. -
[out] result:napi_value, представляющий созданную ошибку.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API возвращает ошибку JavaScript TypeError с указанным текстом.
napi_create_range_error
NAPI_EXTERN napi_status napi_create_range_error(napi_env env,
napi_value code,
napi_value msg,
napi_value* result); copy -
[in] env: Среда, в которой вызывается API. -
[in] code: Необязательныйnapi_valueсо строкой кода ошибки, который будет связан с ошибкой. -
[in] msg:napi_value, ссылающийся на объект JavaScriptstring, который будет использоваться в качестве сообщения дляError. -
[out] result:napi_value, представляющий созданную ошибку.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API возвращает ошибку JavaScript RangeError с указанным текстом.
node_api_create_syntax_error
NAPI_EXTERN napi_status node_api_create_syntax_error(napi_env env,
napi_value code,
napi_value msg,
napi_value* result); copy -
[in] env: Среда, в которой вызывается API. -
[in] code: Необязательныйnapi_valueсо строкой кода ошибки, который будет связан с ошибкой. -
[in] msg:napi_value, ссылающийся на объект JavaScriptstring, который будет использоваться в качестве сообщения дляError. -
[out] result:napi_value, представляющий созданную ошибку.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API возвращает ошибку JavaScript SyntaxError с указанным текстом.
napi_get_and_clear_last_exception
napi_status napi_get_and_clear_last_exception(napi_env env,
napi_value* result); copy -
[in] env: Среда, в которой вызывается API. -
[out] result: Исключение, если оно ожидает обработки; в противном случае —NULL.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API можно вызывать, даже если ожидает обработки исключение JavaScript.
napi_is_exception_pending
napi_status napi_is_exception_pending(napi_env env, bool* result); copy
-
[in] env: Среда, в которой вызывается API. -
[out] result: Логическое значение, которому присваивается true, если ожидает обработки исключение.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API можно вызывать, даже если ожидает обработки исключение JavaScript.
napi_fatal_exception
napi_status napi_fatal_exception(napi_env env, napi_value err); copy
-
[in] env: Среда, в которой вызывается API. -
[in] err: Ошибка, передаваемая в'uncaughtException'.
Вызывает 'uncaughtException' в JavaScript. Полезно, если асинхронный обратный вызов выбрасывает исключение, которое невозможно обработать.
Критические ошибки
При возникновении невосстановимой ошибки в нативном дополнении можно выбросить критическую ошибку, чтобы немедленно завершить процесс.
napi_fatal_error
NAPI_NO_RETURN void napi_fatal_error(const char* location,
size_t location_len,
const char* message,
size_t message_len); copy -
[in] location: Необязательное место возникновения ошибки. -
[in] location_len: Длина места в байтах илиNAPI_AUTO_LENGTH, если строка завершается нулевым символом. -
[in] message: Сообщение, связанное с ошибкой. -
[in] message_len: Длина сообщения в байтах илиNAPI_AUTO_LENGTH, если строка завершается нулевым символом.
Вызов функции не возвращает управление, процесс будет завершён.
Этот API можно вызывать, даже если ожидает обработки исключение JavaScript.
Управление временем жизни объектов
При вызове функций Node-API могут возвращаться дескрипторы объектов в куче базовой виртуальной машины в виде 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;
}
// do something with element
} copy Это приведёт к созданию большого числа дескрипторов, что потребует значительных ресурсов. Кроме того, хотя нативный код может использовать только последний дескриптор, все связанные с ними объекты также будут оставаться живыми, поскольку они относятся к одной области.
Для решения этой проблемы 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;
}
// do something with element
status = napi_close_handle_scope(env, scope);
if (status != napi_ok) {
break;
}
} copy При вложении областей может возникнуть ситуация, когда дескриптор из внутренней области должен оставаться действительным дольше, чем существует эта область. Для поддержки такого сценария в Node-API предусмотрена «область с возможностью выхода». Она позволяет «повысить» один дескриптор, чтобы он «вышел» из текущей области; время его жизни при этом изменится с времени жизни текущей области на время жизни внешней области.
Для открытия и закрытия областей с возможностью выхода доступны методы napi_open_escapable_handle_scope и napi_close_escapable_handle_scope.
Запрос на повышение дескриптора выполняется с помощью napi_escape_handle, который можно вызвать только один раз.
napi_open_handle_scope
NAPI_EXTERN napi_status napi_open_handle_scope(napi_env env,
napi_handle_scope* result); copy -
[in] env: среда, в которой вызывается API. -
[out] result:napi_value, представляющий новую область.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API открывает новую область.
napi_close_handle_scope
NAPI_EXTERN napi_status napi_close_handle_scope(napi_env env,
napi_handle_scope scope); copy -
[in] env: среда, в которой вызывается API. -
[in] scope:napi_value, представляющий область, которую нужно закрыть.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API закрывает переданную область. Области необходимо закрывать в порядке, обратном порядку их создания.
Этот API можно вызвать, даже если ожидает обработки исключение JavaScript.
napi_open_escapable_handle_scope
NAPI_EXTERN napi_status
napi_open_escapable_handle_scope(napi_env env,
napi_handle_scope* result); copy -
[in] env: среда, в которой вызывается API. -
[out] result:napi_value, представляющий новую область.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API открывает новую область, из которой один объект можно перенести во внешнюю область.
napi_close_escapable_handle_scope
NAPI_EXTERN napi_status
napi_close_escapable_handle_scope(napi_env env,
napi_handle_scope scope); copy -
[in] env: среда, в которой вызывается API. -
[in] scope:napi_value, представляющий область, которую нужно закрыть.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API закрывает переданную область. Области необходимо закрывать в порядке, обратном порядку их создания.
Этот API можно вызвать, даже если ожидает обработки исключение JavaScript.
napi_escape_handle
napi_status napi_escape_handle(napi_env env,
napi_escapable_handle_scope scope,
napi_value escapee,
napi_value* result); copy -
[in] env: среда, в которой вызывается API. -
[in] scope:napi_value, представляющий текущую область. -
[in] escapee:napi_value, представляющий JavaScript-Object, который нужно вывести из области. -
[out] result:napi_value, представляющий дескриптор выведенногоObjectво внешней области.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API повышает дескриптор объекта JavaScript, благодаря чему он остаётся действительным в течение времени жизни внешней области. Его можно вызвать только один раз для каждой области. При повторном вызове будет возвращена ошибка.
Этот API можно вызвать, даже если ожидает обработки исключение JavaScript.
Ссылки на значения, время жизни которых превышает время жизни нативного метода
В некоторых случаях дополнению необходимо создавать значения и ссылаться на них в течение времени, превышающего время одного вызова нативного метода. Например, чтобы создать конструктор и позднее использовать его для создания экземпляров, необходимо иметь возможность ссылаться на объект конструктора в нескольких запросах на создание экземпляров. Это было бы невозможно с обычным дескриптором, возвращаемым в виде napi_value, как описано в предыдущем разделе. Время жизни обычного дескриптора управляется областями, и все области должны быть закрыты до завершения нативного метода.
Node-API предоставляет методы для создания постоянных ссылок на значения. В настоящее время Node-API позволяет создавать ссылки только на ограниченный набор типов значений, включая object, external, function и symbol.
Каждая ссылка имеет счётчик со значением 0 или выше, определяющий, будет ли ссылка удерживать соответствующее значение от удаления. Ссылки со счётчиком 0 не препятствуют сборке значений. Значения типов object (object, function, external) и symbol становятся «слабыми» ссылками, и к ним по-прежнему можно обращаться, пока они не собраны. Любое значение счётчика больше 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, вернут NULL в качестве возвращаемого napi_value. Попытка вызвать napi_reference_ref для ссылки, объект которой уже собран, приведёт к ошибке.
Ссылки необходимо удалять, когда дополнение больше не нуждается в них. После удаления ссылка больше не будет препятствовать сборке соответствующего объекта. Если не удалить постоянную ссылку, возникнет «утечка памяти»: нативная память, занятая постоянной ссылкой, и соответствующий объект в куче будут удерживаться навсегда.
На один и тот же объект можно создать несколько постоянных ссылок; каждая из них будет удерживать объект живым или нет в зависимости от собственного счётчика. Несколько постоянных ссылок на один объект могут привести к неожиданному удержанию нативной памяти. Нативные структуры постоянной ссылки необходимо сохранять до выполнения финализаторов для объекта, на который она ссылается. Если для того же объекта создать новую постоянную ссылку, финализаторы этого объекта не будут запущены, а нативная память, на которую указывала предыдущая постоянная ссылка, не будет освобождена. В таких случаях этого можно избежать, вызывая napi_delete_reference вместе с napi_reference_unref.
История изменений:
-
Версия 10 (
NAPI_VERSIONопределён как10или выше):Ссылки можно создавать для всех типов значений. Новые поддерживаемые типы значений не поддерживают семантику слабых ссылок; значения этих типов освобождаются, когда счётчик ссылок становится равным 0, и после этого к ним нельзя обратиться через ссылку.
napi_create_reference
NAPI_EXTERN napi_status napi_create_reference(napi_env env,
napi_value value,
uint32_t initial_refcount,
napi_ref* result); copy -
[in] env: среда, в которой вызывается API. -
[in] value:napi_value, для которого создаётся ссылка. -
[in] initial_refcount: начальное значение счётчика новой ссылки. -
[out] result:napi_ref, указывающий на новую ссылку.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API создаёт новую ссылку на переданное значение с указанным счётчиком ссылок.
napi_delete_reference
NAPI_EXTERN napi_status napi_delete_reference(napi_env env, napi_ref ref); copy
-
[in] env: среда, в которой вызывается API. -
[in] ref:napi_ref, которую нужно удалить.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API удаляет переданную ссылку.
Этот API можно вызвать, даже если ожидает обработки исключение JavaScript.
napi_reference_ref
NAPI_EXTERN napi_status napi_reference_ref(napi_env env,
napi_ref ref,
uint32_t* result); copy -
[in] env: среда, в которой вызывается API. -
[in] ref:napi_ref, счётчик ссылок которой будет увеличен. -
[out] result: новое значение счётчика ссылок.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API увеличивает счётчик ссылок переданной ссылки и возвращает полученное значение счётчика.
napi_reference_unref
NAPI_EXTERN napi_status napi_reference_unref(napi_env env,
napi_ref ref,
uint32_t* result); copy -
[in] env: среда, в которой вызывается API. -
[in] ref:napi_ref, счётчик ссылок которой будет уменьшен. -
[out] result: новое значение счётчика ссылок.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API уменьшает счётчик ссылок переданной ссылки и возвращает полученное значение счётчика.
napi_get_reference_value
NAPI_EXTERN napi_status napi_get_reference_value(napi_env env,
napi_ref ref,
napi_value* result); copy -
[in] env: среда, в которой вызывается API. -
[in] ref:napi_ref, для которого запрашивается соответствующее значение. -
[out] result:napi_value, на которую ссылаетсяnapi_ref.
Возвращает napi_ok, если вызов API выполнен успешно.
Если ссылка всё ещё действительна, этот API возвращает napi_value, представляющий связанное с napi_ref значение JavaScript. В противном случае результатом будет NULL.
Очистка при завершении текущей среды Node.js
Хотя процесс Node.js обычно освобождает все свои ресурсы при завершении, для встраиваемых сред Node.js или будущей поддержки Worker может потребоваться, чтобы дополнения регистрировали обработчики очистки, запускаемые при завершении текущей среды Node.js.
Node-API предоставляет функции для регистрации и отмены регистрации таких обратных вызовов. При их вызове необходимо освободить все ресурсы, удерживаемые дополнением.
napi_add_env_cleanup_hook
NODE_EXTERN napi_status napi_add_env_cleanup_hook(node_api_basic_env env,
napi_cleanup_hook fun,
void* arg); copy Регистрирует fun как функцию, которую нужно вызвать с параметром arg при завершении текущей среды Node.js.
Одну и ту же функцию можно безопасно указать несколько раз с разными значениями arg. В этом случае она также будет вызвана несколько раз. Указывать несколько раз одинаковые значения fun и arg нельзя — это приведёт к аварийному завершению процесса.
Обработчики будут вызваны в обратном порядке: последним будет вызван тот, который был добавлен последним.
Удалить этот обработчик можно с помощью napi_remove_env_cleanup_hook. Обычно это происходит при освобождении ресурса, для которого был добавлен данный обработчик.
Для асинхронной очистки доступен метод napi_add_async_cleanup_hook.
napi_remove_env_cleanup_hook
NAPI_EXTERN napi_status napi_remove_env_cleanup_hook(node_api_basic_env env,
void (*fun)(void* arg),
void* arg); copy Отменяет регистрацию fun как функции, которую нужно вызвать с параметром arg при завершении текущей среды Node.js. Аргумент и значение функции должны точно совпадать.
Функция должна быть предварительно зарегистрирована с помощью napi_add_env_cleanup_hook, иначе процесс завершится аварийно.
napi_add_async_cleanup_hook
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); copy -
[in] env: среда, в которой вызывается API. -
[in] hook: указатель на функцию, вызываемую при завершении работы среды. -
[in] arg: указатель, передаваемый вhookпри её вызове. -
[out] remove_handle: необязательный дескриптор, ссылающийся на асинхронный обработчик очистки.
Регистрирует hook — функцию типа napi_async_cleanup_hook, которую нужно вызвать с параметрами remove_handle и arg при завершении текущей среды Node.js.
В отличие от napi_add_env_cleanup_hook, этот обработчик может выполняться асинхронно.
В остальном поведение в целом совпадает с поведением napi_add_env_cleanup_hook.
Если remove_handle не равен NULL, в него будет записано непрозрачное значение, которое позднее необходимо передать в napi_remove_async_cleanup_hook, независимо от того, был ли обработчик уже вызван. Обычно это происходит при освобождении ресурса, для которого был добавлен данный обработчик.
napi_remove_async_cleanup_hook
NAPI_EXTERN napi_status napi_remove_async_cleanup_hook(
napi_async_cleanup_hook_handle remove_handle); copy -
[in] remove_handle: дескриптор асинхронного обработчика очистки, созданного с помощьюnapi_add_async_cleanup_hook.
Отменяет регистрацию обработчика очистки, соответствующего remove_handle. Это предотвратит выполнение обработчика, если он ещё не начал выполняться. Это необходимо сделать для любого значения napi_async_cleanup_hook_handle, полученного из napi_add_async_cleanup_hook.
Финализация при завершении среды Node.js
Среда Node.js может быть уничтожена в любой момент при первой возможности, причём выполнение JavaScript будет запрещено, например, по запросу worker.terminate(). При уничтожении среды сразу и независимо друг от друга вызываются зарегистрированные обратные вызовы napi_finalize для объектов JavaScript, потокобезопасных функций и данных экземпляра среды.
Вызов обратных вызовов napi_finalize планируется после вручную зарегистрированных обработчиков очистки. Чтобы обеспечить правильный порядок финализации дополнений при завершении среды и избежать обращения к уже освобождённой памяти в обратном вызове napi_finalize, дополнениям следует зарегистрировать обработчик очистки с помощью napi_add_env_cleanup_hook и napi_add_async_cleanup_hook, чтобы вручную освободить выделенный ресурс в надлежащем порядке.
Регистрация модуля
Модули Node-API регистрируются способом, аналогичным другим модулям, но вместо макроса NODE_MODULE используется следующее:
NAPI_MODULE(NODE_GYP_MODULE_NAME, Init) copy
Следующее отличие — сигнатура метода Init. Для модуля Node-API она выглядит так:
napi_value Init(napi_env env, napi_value exports); copy
Возвращаемое значение 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;
} copy Чтобы задать функцию, возвращаемую методом 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;
} copy Чтобы определить класс, экземпляры которого можно создавать (часто используется вместе с обёрткой объекта):
// NOTE: partial example, not all referenced code is included
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;
} copy Можно также использовать макрос 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;
} copy Параметры env и exports доступны в теле макроса NAPI_MODULE_INIT.
Все дополнения Node-API учитывают контекст, то есть могут загружаться несколько раз. При объявлении такого модуля следует учитывать несколько особенностей проектирования. Подробнее см. в документации о дополнениях, учитывающих контекст.
Переменные env и exports будут доступны внутри тела функции после вызова макроса.
Подробнее о настройке свойств объектов см. в разделе Работа со свойствами JavaScript.
Общие сведения о сборке модулей дополнений см. в существующей документации API.
Работа со значениями JavaScript
Node-API предоставляет набор API для создания всех типов значений JavaScript. Некоторые из этих типов описаны в разделе «Типы языка» спецификации языка ECMAScript.
В основном эти API используются для выполнения одного из следующих действий:
- Создание нового объекта JavaScript
- Преобразование примитивного типа C в значение Node-API
- Преобразование значения Node-API в примитивный тип C
- Получение глобальных экземпляров, включая
undefinedиnull
Значения Node-API представлены типом napi_value. Любой вызов Node-API, которому требуется значение JavaScript, принимает napi_value. В некоторых случаях API заранее проверяет тип napi_value. Однако для повышения производительности вызывающей стороне лучше убедиться, что рассматриваемое napi_value имеет ожидаемый для API тип JavaScript.
Типы перечислений
napi_key_collection_mode
typedef enum {
napi_key_include_prototypes,
napi_key_own_only
} napi_key_collection_mode; copy Описывает перечисления фильтров Keys/Properties:
napi_key_collection_mode ограничивает диапазон собираемых свойств.
napi_key_own_only ограничивает собираемые свойства только указанным объектом. napi_key_include_prototypes также включает все ключи цепочки прототипов объекта.
napi_key_filter
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; copy Битовый флаг фильтра свойств. Он используется с побитовыми операторами для создания составного фильтра.
napi_key_conversion
typedef enum {
napi_key_keep_numbers,
napi_key_numbers_to_strings
} napi_key_conversion; copy napi_key_numbers_to_strings преобразует целочисленные индексы в строки. napi_key_keep_numbers возвращает числа для целочисленных индексов.
napi_valuetype
typedef enum {
// ES6 types (corresponds to typeof)
napi_undefined,
napi_null,
napi_boolean,
napi_number,
napi_string,
napi_symbol,
napi_object,
napi_function,
napi_external,
napi_bigint,
} napi_valuetype; copy Описывает тип napi_value. Обычно он соответствует типам, описанным в разделе «Типы языка» спецификации языка ECMAScript. Помимо типов из этого раздела, napi_valuetype может также представлять Function и Object с внешними данными.
Значение JavaScript типа napi_external представляется в 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_float16_array,
} napi_typedarray_type; copy Представляет базовый скалярный двоичный тип данных TypedArray. Элементы этого перечисления соответствуют объектам из раздела «Объекты TypedArray» спецификации языка ECMAScript.
Функции создания объектов
napi_create_array
napi_status napi_create_array(napi_env env, napi_value* result) copy
-
[in] env: среда, в которой вызывается Node-API. -
[out] result:napi_value, представляющий массив JavaScriptArray.
Возвращает napi_ok в случае успешного выполнения API.
Этот API возвращает значение Node-API, соответствующее типу массива JavaScript Array. Массивы JavaScript описаны в разделе «Объекты Array» спецификации языка ECMAScript.
napi_create_array_with_length
napi_status napi_create_array_with_length(napi_env env,
size_t length,
napi_value* result) copy -
[in] env: среда, в которой вызывается API. -
[in] length: начальная длинаArray. -
[out] result:napi_value, представляющий массив JavaScriptArray.
Возвращает napi_ok в случае успешного выполнения API.
Этот API возвращает значение Node-API, соответствующее типу массива JavaScript Array. Свойству length массива Array присваивается переданный параметр длины. Однако виртуальная машина не гарантирует предварительное выделение базового буфера при создании массива. Это поведение зависит от реализации виртуальной машины. Если буфер должен быть непрерывным блоком памяти, который можно непосредственно читать и/или изменять из C, рассмотрите возможность использования napi_create_external_arraybuffer.
Массивы JavaScript описаны в разделе «Объекты Array» спецификации языка ECMAScript.
napi_create_arraybuffer
napi_status napi_create_arraybuffer(napi_env env,
size_t byte_length,
void** data,
napi_value* result) copy -
[in] env: среда, в которой вызывается API. -
[in] length: длина создаваемого буфера массива в байтах. -
[out] data: указатель на базовый байтовый буферArrayBuffer.dataможно не использовать, передавNULL. -
[out] result:napi_value, представляющий объект JavaScriptArrayBuffer.
Возвращает napi_ok в случае успешного выполнения API.
Этот API возвращает значение Node-API, соответствующее объекту JavaScript ArrayBuffer. ArrayBuffer используются для представления двоичных буферов фиксированной длины. Обычно они служат базовым буфером для объектов TypedArray. Выделенный объект ArrayBuffer будет иметь базовый байтовый буфер размером, определяемым переданным параметром length. Базовый буфер при необходимости возвращается вызывающей стороне, если она хочет напрямую манипулировать им. Записывать данные в этот буфер напрямую можно только из собственного кода. Для записи в него из JavaScript необходимо создать типизированный массив или объект DataView.
Объекты JavaScript ArrayBuffer описаны в разделе «Объекты ArrayBuffer» спецификации языка ECMAScript.
napi_create_buffer
napi_status napi_create_buffer(napi_env env,
size_t size,
void** data,
napi_value* result) copy -
[in] env: среда, в которой вызывается API. -
[in] size: размер базового буфера в байтах. -
[out] data: указатель на базовый буфер.dataможно не использовать, передавNULL. -
[out] result:napi_value, представляющийnode::Buffer.
Возвращает napi_ok в случае успешного выполнения API.
Этот API выделяет объект node::Buffer. Хотя эта структура данных по-прежнему полностью поддерживается, в большинстве случаев достаточно использовать TypedArray.
napi_create_buffer_copy
napi_status napi_create_buffer_copy(napi_env env,
size_t length,
const void* data,
void** result_data,
napi_value* result) copy -
[in] env: среда, в которой вызывается API. -
[in] size: размер входного буфера в байтах (должен совпадать с размером нового буфера). -
[in] data: указатель на исходный базовый буфер для копирования. -
[out] result_data: указатель на базовый буфер данных новогоBuffer.result_dataможно не использовать, передавNULL. -
[out] result:napi_value, представляющийnode::Buffer.
Возвращает napi_ok в случае успешного выполнения API.
Этот API выделяет объект node::Buffer и инициализирует его данными, скопированными из переданного буфера. Хотя эта структура данных по-прежнему полностью поддерживается, в большинстве случаев достаточно использовать TypedArray.
napi_create_date
napi_status napi_create_date(napi_env env,
double time,
napi_value* result); copy -
[in] env: среда, в которой вызывается API. -
[in] time: значение времени ECMAScript в миллисекундах с 1 января 1970 года по UTC. -
[out] result:napi_value, представляющий объект JavaScriptDate.
Возвращает napi_ok в случае успешного выполнения API.
Этот API не учитывает високосные секунды: они игнорируются, поскольку ECMAScript следует спецификации времени POSIX.
Этот API выделяет объект JavaScript Date.
Объекты JavaScript Date описаны в разделе «Объекты Date» спецификации языка ECMAScript.
napi_create_external
napi_status napi_create_external(napi_env env,
void* data,
napi_finalize finalize_cb,
void* finalize_hint,
napi_value* result) copy -
[in] env: среда, в которой вызывается API. -
[in] data: указатель на внешние данные. -
[in] finalize_cb: необязательный callback, вызываемый при сборке внешнего значения. Дополнительные сведения см. в разделеnapi_finalize. -
[in] finalize_hint: необязательная подсказка, передаваемая callback финализации при сборке мусора. -
[out] result:napi_value, представляющий внешнее значение.
Возвращает napi_ok в случае успешного выполнения API.
Этот API выделяет значение JavaScript, связанное с внешними данными. Это позволяет передавать внешние данные через код JavaScript, чтобы позднее собственный код мог получить их с помощью napi_get_value_external.
API добавляет callback napi_finalize, который вызывается после сборки сборщиком мусора только что созданного объекта JavaScript.
Созданное значение не является объектом и поэтому не поддерживает дополнительные свойства. Оно считается отдельным типом значений: вызов napi_typeof() с внешним значением возвращает napi_external.
napi_create_external_arraybuffer
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) copy -
[in] env: среда, в которой вызывается API. -
[in] external_data: указатель на базовый байтовый буферArrayBuffer. -
[in] byte_length: длина базового буфера в байтах. -
[in] finalize_cb: необязательный callback, вызываемый при сборкеArrayBuffer. Дополнительные сведения см. в разделеnapi_finalize. -
[in] finalize_hint: необязательная подсказка, передаваемая callback финализации при сборке мусора. -
[out] result:napi_value, представляющий объект JavaScriptArrayBuffer.
Возвращает napi_ok в случае успешного выполнения API.
В некоторых средах выполнения, отличных от Node.js, прекращена поддержка внешних буферов. В таких средах этот метод может вернуть napi_no_external_buffers_allowed, указывая на то, что внешние буферы не поддерживаются. Одним из примеров является Electron, как описано в этой задаче electron/issues/35801.
Чтобы обеспечить максимальную совместимость со всеми средами выполнения, можно определить NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED в дополнении до подключения заголовков node-api. Это скроет две функции создания внешних буферов и позволит получить ошибку компиляции при случайном использовании одного из этих методов.
Этот API возвращает значение Node-API, соответствующее объекту JavaScript ArrayBuffer. Базовый байтовый буфер ArrayBuffer выделяется и управляется извне. Вызывающая сторона должна обеспечить его действительность до вызова callback финализации.
API добавляет callback napi_finalize, который вызывается после сборки сборщиком мусора только что созданного объекта JavaScript.
Объекты JavaScript ArrayBuffer описаны в разделе «Объекты ArrayBuffer» спецификации языка ECMAScript.
napi_create_external_buffer
napi_status napi_create_external_buffer(napi_env env,
size_t length,
void* data,
napi_finalize finalize_cb,
void* finalize_hint,
napi_value* result) copy -
[in] env: среда, в которой вызывается API. -
[in] length: размер входного буфера в байтах (должен совпадать с размером нового буфера). -
[in] data: указатель на базовый буфер, предоставляемый JavaScript. -
[in] finalize_cb: необязательный callback, вызываемый при сборкеArrayBuffer. Дополнительные сведения см. в разделеnapi_finalize. -
[in] finalize_hint: необязательная подсказка, передаваемая callback финализации при сборке мусора. -
[out] result:napi_value, представляющийnode::Buffer.
Возвращает napi_ok в случае успешного выполнения API.
В некоторых средах выполнения, отличных от Node.js, прекращена поддержка внешних буферов. В таких средах этот метод может вернуть napi_no_external_buffers_allowed, указывая на то, что внешние буферы не поддерживаются. Одним из примеров является Electron, как описано в этой задаче electron/issues/35801.
Чтобы обеспечить максимальную совместимость со всеми средами выполнения, можно определить NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED в дополнении до подключения заголовков node-api. Это скроет две функции создания внешних буферов и позволит получить ошибку компиляции при случайном использовании одного из этих методов.
Этот API выделяет объект node::Buffer и инициализирует его данными из переданного буфера. Хотя эта структура данных по-прежнему полностью поддерживается, в большинстве случаев достаточно использовать TypedArray.
API добавляет callback napi_finalize, который вызывается после сборки сборщиком мусора только что созданного объекта JavaScript.
В Node.js версии >=4 Buffers являются Uint8Array.
napi_create_object
napi_status napi_create_object(napi_env env, napi_value* result) copy
-
[in] env: среда, в которой вызывается API. -
[out] result:napi_value, представляющий объект JavaScriptObject.
Возвращает napi_ok в случае успешного выполнения API.
Этот API выделяет стандартный объект JavaScript Object. Это эквивалентно выполнению new Object() в JavaScript.
Тип JavaScript Object описан в разделе «Тип Object» спецификации языка ECMAScript.
node_api_create_object_with_properties
napi_status node_api_create_object_with_properties(napi_env env,
napi_value prototype_or_null,
const napi_value* property_names,
const napi_value* property_values,
size_t property_count,
napi_value* result) copy -
[in] env: среда, в которой вызывается API. -
[in] prototype_or_null: объект-прототип нового объекта. Может бытьnapi_value, представляющим объект JavaScript, используемый в качестве прототипа,napi_value, представляющим JavaScriptnull, илиnullptr, который будет преобразован вnull. -
[in] property_names: массивnapi_value, представляющих имена свойств. -
[in] property_values: массивnapi_value, представляющих значения свойств. -
[in] property_count: количество свойств в массивах. -
[out] result:napi_value, представляющий объект JavaScriptObject.
Возвращает napi_ok в случае успешного выполнения API.
Этот API создает объект JavaScript Object с указанным прототипом и свойствами. Это эффективнее, чем вызов napi_create_object с последующими несколькими вызовами napi_set_property, поскольку объект можно создать сразу со всеми свойствами, избежав потенциальных переходов карт V8.
Массивы property_names и property_values должны иметь одинаковую длину, заданную параметром property_count. Свойства добавляются к объекту в том порядке, в котором они указаны в массивах.
napi_create_symbol
napi_status napi_create_symbol(napi_env env,
napi_value description,
napi_value* result) copy -
[in] env: среда, в которой вызывается API. -
[in] description: необязательныйnapi_value, представляющий значение JavaScriptstring, которое будет задано в качестве описания символа. -
[out] result:napi_value, представляющий символ JavaScriptsymbol.
Возвращает napi_ok в случае успешного выполнения API.
Этот API создает значение JavaScript symbol из строки C в кодировке UTF-8.
Тип JavaScript symbol описан в разделе «Тип Symbol» спецификации языка ECMAScript.
node_api_symbol_for
napi_status node_api_symbol_for(napi_env env,
const char* utf8description,
size_t length,
napi_value* result) copy -
[in] env: среда, в которой вызывается API. -
[in] utf8description: строка C в кодировке UTF-8, представляющая текст описания символа. -
[in] length: длина строки описания в байтах илиNAPI_AUTO_LENGTH, если строка завершается нулевым символом. -
[out] result:napi_value, представляющий символ JavaScriptsymbol.
Возвращает napi_ok в случае успешного выполнения API.
Этот API выполняет поиск в глобальном реестре символа с указанным описанием. Если символ уже существует, он будет возвращен; в противном случае в реестре будет создан новый символ.
Тип JavaScript symbol описан в разделе «Тип Symbol» спецификации языка ECMAScript.
napi_create_typedarray
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) copy -
[in] env: среда, в которой вызывается API. -
[in] type: скалярный тип данных элементовTypedArray. -
[in] length: количество элементов вTypedArray. -
[in] arraybuffer:ArrayBuffer, лежащий в основе типизированного массива. -
[in] byte_offset: смещение в байтах внутриArrayBuffer, с которого начинается представлениеTypedArray. -
[out] result:napi_value, представляющий типизированный массив JavaScriptTypedArray.
Возвращает napi_ok в случае успешного выполнения API.
Этот API создает объект JavaScript TypedArray поверх существующего ArrayBuffer. Объекты TypedArray предоставляют похожее на массив представление базового буфера данных, в котором все элементы имеют одинаковый базовый скалярный двоичный тип данных.
Необходимо, чтобы (length * size_of_element) + byte_offset было меньше или равно размеру переданного массива в байтах. В противном случае возникает исключение RangeError.
Объекты JavaScript TypedArray описаны в разделе «Объекты TypedArray» спецификации языка ECMAScript.
node_api_create_buffer_from_arraybuffer
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) copy -
[in] env: среда, в которой вызывается API. -
[in] arraybuffer:ArrayBuffer, из которого будет создан буфер. -
[in] byte_offset: смещение в байтах внутриArrayBuffer, с которого начинается создание буфера. -
[in] byte_length: длина создаваемого изArrayBufferбуфера в байтах. -
[out] result:napi_value, представляющий созданный объект JavaScriptBuffer.
Возвращает napi_ok в случае успешного выполнения API.
Этот API создает объект JavaScript Buffer из существующего ArrayBuffer. Объект Buffer — это специфичный для Node.js класс, позволяющий работать с двоичными данными непосредственно в JavaScript.
Диапазон байтов [byte_offset, byte_offset + byte_length) должен находиться в пределах ArrayBuffer. Если byte_offset + byte_length превышает размер ArrayBuffer, возникает исключение RangeError.
napi_create_dataview
napi_status napi_create_dataview(napi_env env,
size_t byte_length,
napi_value arraybuffer,
size_t byte_offset,
napi_value* result) copy -
[in] env: среда, в которой вызывается API. -
[in] length: количество элементов вDataView. -
[in] arraybuffer:ArrayBufferилиSharedArrayBuffer, лежащий в основеDataView. -
[in] byte_offset: смещение в байтах внутриArrayBuffer, с которого начинается представлениеDataView. -
[out] result:napi_value, представляющий объект JavaScriptDataView.
Возвращает napi_ok в случае успешного выполнения API.
Этот API создает объект JavaScript DataView поверх существующего ArrayBuffer или SharedArrayBuffer. Объекты DataView предоставляют похожее на массив представление базового буфера данных, позволяя при этом использовать элементы разных размеров и типов в ArrayBuffer или SharedArrayBuffer.
Необходимо, чтобы byte_length + byte_offset было меньше или равно размеру переданного массива в байтах. В противном случае возникает исключение RangeError.
Объекты JavaScript DataView описаны в разделе «Объекты DataView» спецификации языка ECMAScript.
Функции преобразования типов C в Node-API
napi_create_int32
napi_status napi_create_int32(napi_env env, int32_t value, napi_value* result) copy
-
[in] env: Среда, в которой вызывается API. -
[in] value: Целочисленное значение, которое нужно представить в JavaScript. -
[out] result:napi_value, представляющий JavaScriptnumber.
Возвращает napi_ok, если API выполнен успешно.
Этот API используется для преобразования типа C int32_t в тип JavaScript number.
Тип JavaScript number описан в разделе «Тип number» Спецификации языка ECMAScript.
napi_create_uint32
napi_status napi_create_uint32(napi_env env, uint32_t value, napi_value* result) copy
-
[in] env: Среда, в которой вызывается API. -
[in] value: Беззнаковое целочисленное значение, которое нужно представить в JavaScript. -
[out] result:napi_value, представляющий JavaScriptnumber.
Возвращает napi_ok, если API выполнен успешно.
Этот API используется для преобразования типа C uint32_t в тип JavaScript number.
Тип JavaScript number описан в разделе «Тип number» Спецификации языка ECMAScript.
napi_create_int64
napi_status napi_create_int64(napi_env env, int64_t value, napi_value* result) copy
-
[in] env: Среда, в которой вызывается API. -
[in] value: Целочисленное значение, которое нужно представить в JavaScript. -
[out] result:napi_value, представляющий JavaScriptnumber.
Возвращает napi_ok, если API выполнен успешно.
Этот API используется для преобразования типа C int64_t в тип JavaScript number.
Тип JavaScript number описан в разделе «Тип number» Спецификации языка ECMAScript. Обратите внимание, что весь диапазон int64_t невозможно точно представить в JavaScript. Целочисленные значения за пределами диапазона от Number.MIN_SAFE_INTEGER -(2**53 - 1) до Number.MAX_SAFE_INTEGER (2**53 - 1) будут терять точность.
napi_create_double
napi_status napi_create_double(napi_env env, double value, napi_value* result) copy
-
[in] env: Среда, в которой вызывается API. -
[in] value: Значение двойной точности, которое нужно представить в JavaScript. -
[out] result:napi_value, представляющий JavaScriptnumber.
Возвращает napi_ok, если API выполнен успешно.
Этот API используется для преобразования типа C double в тип JavaScript number.
Тип JavaScript number описан в разделе «Тип number» Спецификации языка ECMAScript.
napi_create_bigint_int64
napi_status napi_create_bigint_int64(napi_env env,
int64_t value,
napi_value* result); copy -
[in] env: Среда, в которой вызывается API. -
[in] value: Целочисленное значение, которое нужно представить в JavaScript. -
[out] result:napi_value, представляющий JavaScriptBigInt.
Возвращает napi_ok, если API выполнен успешно.
Этот API преобразует тип C int64_t в тип JavaScript BigInt.
napi_create_bigint_uint64
napi_status napi_create_bigint_uint64(napi_env env,
uint64_t value,
napi_value* result); copy -
[in] env: Среда, в которой вызывается API. -
[in] value: Беззнаковое целочисленное значение, которое нужно представить в JavaScript. -
[out] result:napi_value, представляющий JavaScriptBigInt.
Возвращает napi_ok, если API выполнен успешно.
Этот API преобразует тип C uint64_t в тип JavaScript BigInt.
napi_create_bigint_words
napi_status napi_create_bigint_words(napi_env env,
int sign_bit,
size_t word_count,
const uint64_t* words,
napi_value* result); copy -
[in] env: Среда, в которой вызывается API. -
[in] sign_bit: Определяет, будет ли результирующее значениеBigIntположительным или отрицательным. -
[in] word_count: Длина массиваwords. -
[in] words: Массив 64-битных словuint64_tв порядке от младшего к старшему. -
[out] result:napi_value, представляющий JavaScriptBigInt.
Возвращает napi_ok, если API выполнен успешно.
Этот API преобразует массив беззнаковых 64-битных слов в одно значение BigInt.
Результирующее значение BigInt вычисляется по формуле: (–1)sign_bit (words[0] × (264)0 + words[1] × (264)1 + …)
napi_create_string_latin1
napi_status napi_create_string_latin1(napi_env env,
const char* str,
size_t length,
napi_value* result); copy -
[in] env: Среда, в которой вызывается API. -
[in] str: Буфер символов, содержащий строку в кодировке ISO-8859-1. -
[in] length: Длина строки в байтах илиNAPI_AUTO_LENGTH, если строка завершается нулевым символом. -
[out] result:napi_value, представляющий JavaScriptstring.
Возвращает napi_ok, если API выполнен успешно.
Этот API создает значение JavaScript string из строки C в кодировке ISO-8859-1. Строка копируется.
Тип JavaScript string описан в разделе «Тип string» Спецификации языка ECMAScript.
node_api_create_external_string_latin1
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); copy -
[in] env: Среда, в которой вызывается API. -
[in] str: Буфер символов, содержащий строку в кодировке ISO-8859-1. -
[in] length: Длина строки в байтах илиNAPI_AUTO_LENGTH, если строка завершается нулевым символом. -
[in] finalize_callback: Функция, вызываемая при сборке строки. Функция будет вызвана со следующими параметрами:-
[in] env: Среда, в которой выполняется дополнение. Это значение может быть null, если строка собирается при завершении работы рабочего потока или основного экземпляра Node.js. -
[in] data: Это значениеstrв виде указателяvoid*. -
[in] finalize_hint: Это значениеfinalize_hint, переданное API. Подробнее см. в разделеnapi_finalize. Этот параметр необязателен. Передача значения null означает, что дополнению не нужно получать уведомление о сборке соответствующей строки JavaScript.
-
-
[in] finalize_hint: Необязательная подсказка, передаваемая функции обратного вызова финализации при сборке. -
[out] result:napi_value, представляющий JavaScriptstring. -
[out] copied: Была ли строка скопирована. Если да, финализатор уже был вызван для уничтоженияstr.
Возвращает napi_ok, если API выполнен успешно.
Этот API создает значение JavaScript string из строки C в кодировке ISO-8859-1. Нативная строка может не копироваться, поэтому она должна существовать на протяжении всего жизненного цикла значения JavaScript.
Тип JavaScript string описан в разделе «Тип string» Спецификации языка ECMAScript.
napi_create_string_utf16
napi_status napi_create_string_utf16(napi_env env,
const char16_t* str,
size_t length,
napi_value* result) copy -
[in] env: Среда, в которой вызывается API. -
[in] str: Буфер символов, содержащий строку в кодировке UTF16-LE. -
[in] length: Длина строки в двухбайтовых кодовых единицах илиNAPI_AUTO_LENGTH, если строка завершается нулевым символом. -
[out] result:napi_value, представляющий JavaScriptstring.
Возвращает napi_ok, если API выполнен успешно.
Этот API создает значение JavaScript string из строки C в кодировке UTF16-LE. Строка копируется.
Тип JavaScript string описан в разделе «Тип string» Спецификации языка ECMAScript.
node_api_create_external_string_utf16
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); copy -
[in] env: Среда, в которой вызывается API. -
[in] str: Буфер символов, содержащий строку в кодировке UTF16-LE. -
[in] length: Длина строки в двухбайтовых кодовых единицах илиNAPI_AUTO_LENGTH, если строка завершается нулевым символом. -
[in] finalize_callback: Функция, вызываемая при сборке строки. Функция будет вызвана со следующими параметрами:-
[in] env: Среда, в которой выполняется дополнение. Это значение может быть null, если строка собирается при завершении работы рабочего потока или основного экземпляра Node.js. -
[in] data: Это значениеstrв виде указателяvoid*. -
[in] finalize_hint: Это значениеfinalize_hint, переданное API. Подробнее см. в разделеnapi_finalize. Этот параметр необязателен. Передача значения null означает, что дополнению не нужно получать уведомление о сборке соответствующей строки JavaScript.
-
-
[in] finalize_hint: Необязательная подсказка, передаваемая функции обратного вызова финализации при сборке. -
[out] result:napi_value, представляющий JavaScriptstring. -
[out] copied: Была ли строка скопирована. Если да, финализатор уже был вызван для уничтоженияstr.
Возвращает napi_ok, если API выполнен успешно.
Этот API создает значение JavaScript string из строки C в кодировке UTF16-LE. Нативная строка может не копироваться, поэтому она должна существовать на протяжении всего жизненного цикла значения JavaScript.
Тип JavaScript string описан в разделе «Тип string» Спецификации языка ECMAScript.
napi_create_string_utf8
napi_status napi_create_string_utf8(napi_env env,
const char* str,
size_t length,
napi_value* result) copy -
[in] env: Среда, в которой вызывается API. -
[in] str: Буфер символов, содержащий строку в кодировке UTF8. -
[in] length: Длина строки в байтах илиNAPI_AUTO_LENGTH, если строка завершается нулевым символом. -
[out] result:napi_value, представляющий JavaScriptstring.
Возвращает napi_ok, если API выполнен успешно.
Этот API создает значение JavaScript string из строки C в кодировке UTF8. Строка копируется.
Тип JavaScript string описан в разделе «Тип string» Спецификации языка ECMAScript.
Функции создания оптимизированных ключей свойств
Многие движки JavaScript, включая V8, используют интернированные строки в качестве ключей для записи и получения значений свойств. Обычно для создания и поиска таких строк используется хеш-таблица. Хотя создание каждого ключа требует дополнительных затрат, впоследствии это повышает производительность, позволяя сравнивать указатели на строки вместо сравнения строк целиком.
Если новую строку JavaScript предполагается использовать как ключ свойства, то в некоторых движках JavaScript эффективнее использовать функции из этого раздела. В противном случае используйте функции серий napi_create_string_utf8 или node_api_create_external_string_utf8, поскольку методы создания ключей свойств могут приводить к дополнительным затратам на создание и хранение строк.
node_api_create_property_key_latin1
napi_status NAPI_CDECL node_api_create_property_key_latin1(napi_env env,
const char* str,
size_t length,
napi_value* result); copy -
[in] env: Среда, в которой вызывается API. -
[in] str: Буфер символов, содержащий строку в кодировке ISO-8859-1. -
[in] length: Длина строки в байтах илиNAPI_AUTO_LENGTH, если строка завершается нулевым символом. -
[out] result:napi_value, представляющий оптимизированный JavaScriptstring, используемый в качестве ключа свойства объекта.
Возвращает napi_ok, если API выполнен успешно.
Этот API создает оптимизированное значение JavaScript string из строки C в кодировке ISO-8859-1 для использования в качестве ключа свойства объекта. Нативная строка копируется. В отличие от napi_create_string_latin1, повторные вызовы этой функции с тем же указателем str могут ускорить создание запрошенного значения napi_value в зависимости от движка.
Тип JavaScript string описан в разделе «Тип string» Спецификации языка ECMAScript.
node_api_create_property_key_utf16
napi_status NAPI_CDECL node_api_create_property_key_utf16(napi_env env,
const char16_t* str,
size_t length,
napi_value* result); copy -
[in] env: Среда, в которой вызывается API. -
[in] str: Буфер символов, содержащий строку в кодировке UTF16-LE. -
[in] length: Длина строки в двухбайтовых кодовых единицах илиNAPI_AUTO_LENGTH, если строка завершается нулевым символом. -
[out] result:napi_value, представляющий оптимизированный JavaScriptstring, используемый в качестве ключа свойства объекта.
Возвращает napi_ok, если API выполнен успешно.
Этот API создает оптимизированное значение JavaScript string из строки C в кодировке UTF16-LE для использования в качестве ключа свойства объекта. Нативная строка копируется.
Тип JavaScript string описан в разделе «Тип string» Спецификации языка ECMAScript.
node_api_create_property_key_utf8
napi_status NAPI_CDECL node_api_create_property_key_utf8(napi_env env,
const char* str,
size_t length,
napi_value* result); copy -
[in] env: Среда, в которой вызывается API. -
[in] str: Буфер символов, содержащий строку в кодировке UTF8. -
[in] length: Длина строки в двухбайтовых кодовых единицах илиNAPI_AUTO_LENGTH, если строка завершается нулевым символом. -
[out] result:napi_value, представляющий оптимизированный JavaScriptstring, используемый в качестве ключа свойства объекта.
Возвращает napi_ok, если API выполнен успешно.
Этот API создает оптимизированное значение JavaScript string из строки C в кодировке UTF8 для использования в качестве ключа свойства объекта. Нативная строка копируется.
Тип JavaScript string описан в разделе «Тип string» Спецификации языка ECMAScript.
Функции для преобразования из Node-API в типы C
napi_get_array_length
napi_status napi_get_array_length(napi_env env,
napi_value value,
uint32_t* result) copy -
[in] env: Среда, в которой вызывается API. -
[in] value:napi_value, представляющий массив JavaScriptArray, длина которого запрашивается. -
[out] result:uint32, представляющий длину массива.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API возвращает длину массива.
Длина Array описана в разделе «Длина экземпляра Array» спецификации языка ECMAScript.
napi_get_arraybuffer_info
napi_status napi_get_arraybuffer_info(napi_env env,
napi_value arraybuffer,
void** data,
size_t* byte_length) copy -
[in] env: Среда, в которой вызывается API. -
[in] arraybuffer:napi_value, представляющий запрашиваемыйArrayBufferилиSharedArrayBuffer. -
[out] data: Базовый буфер данныхArrayBufferилиSharedArrayBufferравен0; это может бытьNULLили любое другое значение указателя. -
[out] byte_length: Длина базового буфера данных в байтах.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API используется для получения базового буфера данных ArrayBuffer или SharedArrayBuffer и его длины.
ПРЕДУПРЕЖДЕНИЕ: Соблюдайте осторожность при использовании этого API. Срок жизни базового буфера данных управляется ArrayBuffer или SharedArrayBuffer даже после его возврата. Один из безопасных способов использования этого API — совместно с napi_create_reference, который позволяет гарантировать контроль над временем жизни ArrayBuffer или SharedArrayBuffer. Возвращённый буфер данных также безопасно использовать в рамках того же обратного вызова, если не вызываются другие API, которые могут запустить сборку мусора.
napi_get_buffer_info
napi_status napi_get_buffer_info(napi_env env,
napi_value value,
void** data,
size_t* length) copy -
[in] env: Среда, в которой вызывается API. -
[in] value:napi_value, представляющий запрашиваемыйnode::BufferилиUint8Array. -
[out] data: Базовый буфер данныхnode::BufferилиUint8Array. Если длина равна0, это может бытьNULLили любое другое значение указателя. -
[out] length: Длина базового буфера данных в байтах.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот метод возвращает те же data и byte_length, что и napi_get_typedarray_info. Кроме того, napi_get_typedarray_info принимает в качестве значения также node::Buffer (Uint8Array).
Этот API используется для получения базового буфера данных node::Buffer и его длины.
Предупреждение: Соблюдайте осторожность при использовании этого API, поскольку время жизни базового буфера данных не гарантируется, если им управляет виртуальная машина.
napi_get_prototype
napi_status napi_get_prototype(napi_env env,
napi_value object,
napi_value* result) copy -
[in] env: Среда, в которой вызывается API. -
[in] object:napi_value, представляющий объект JavaScriptObject, прототип которого нужно вернуть. Возвращается эквивалентObject.getPrototypeOf(это не то же самое, что свойствоprototypeфункции). -
[out] result:napi_value, представляющий прототип заданного объекта.
Возвращает napi_ok, если вызов API выполнен успешно.
napi_get_typedarray_info
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) copy -
[in] env: Среда, в которой вызывается API. -
[in] typedarray:napi_value, представляющийTypedArray, свойства которого запрашиваются. -
[out] type: Скалярный тип данных элементовTypedArray. -
[out] length: Количество элементов вTypedArray. -
[out] data: Буфер данных, лежащий в основеTypedArray, скорректированный с учётом значенияbyte_offsetтак, чтобы он указывал на первый элемент вTypedArray. Если длина массива равна0, это может бытьNULLили любое другое значение указателя. -
[out] arraybuffer:ArrayBuffer, лежащий в основеTypedArray. -
[out] byte_offset: Смещение в байтах внутри базового нативного массива, где расположен первый элемент массивов. Значение параметра data уже скорректировано таким образом, что data указывает на первый элемент массива. Поэтому первый байт нативного массива находился бы по адресуdata - byte_offset.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API возвращает различные свойства типизированного массива.
Любой из выходных параметров может быть NULL, если соответствующее свойство не требуется.
Предупреждение: Соблюдайте осторожность при использовании этого API, поскольку базовым буфером данных управляет виртуальная машина.
napi_get_dataview_info
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) copy -
[in] env: Среда, в которой вызывается API. -
[in] dataview:napi_value, представляющийDataView, свойства которого запрашиваются. -
[out] byte_length: Количество байтов вDataView. -
[out] data: Буфер данных, лежащий в основеDataView. Если byte_length равен0, это может бытьNULLили любое другое значение указателя. -
[out] arraybuffer:ArrayBuffer, лежащий в основеDataView. -
[out] byte_offset: Смещение в байтах внутри буфера данных, с которого начинается проекцияDataView.
Возвращает napi_ok, если вызов API выполнен успешно.
Любой из выходных параметров может быть NULL, если соответствующее свойство не требуется.
Этот API возвращает различные свойства DataView.
napi_get_date_value
napi_status napi_get_date_value(napi_env env,
napi_value value,
double* result) copy -
[in] env: Среда, в которой вызывается API. -
[in] value:napi_value, представляющий объект JavaScriptDate. -
[out] result: Значение времени в видеdouble, представленное количеством миллисекунд, прошедших с полуночи 1 января 1970 года по UTC.
Этот API не учитывает високосные секунды; они игнорируются, поскольку ECMAScript соответствует спецификации времени POSIX.
Возвращает napi_ok, если вызов API выполнен успешно. Если передано значение napi_value, не являющееся датой, возвращается napi_date_expected.
Этот API возвращает примитив C double, соответствующий значению времени заданного объекта JavaScript Date.
napi_get_value_bool
napi_status napi_get_value_bool(napi_env env, napi_value value, bool* result) copy
-
[in] env: Среда, в которой вызывается API. -
[in] value:napi_value, представляющий значение JavaScriptBoolean. -
[out] result: Примитив C boolean, эквивалентный заданному значению JavaScriptBoolean.
Возвращает napi_ok, если вызов API выполнен успешно. Если передано значение napi_value, не являющееся логическим, возвращается napi_boolean_expected.
Этот API возвращает примитив C boolean, эквивалентный заданному значению JavaScript Boolean.
napi_get_value_double
napi_status napi_get_value_double(napi_env env,
napi_value value,
double* result) copy -
[in] env: Среда, в которой вызывается API. -
[in] value:napi_value, представляющий значение JavaScriptnumber. -
[out] result: Примитив C double, эквивалентный заданному значению JavaScriptnumber.
Возвращает napi_ok, если вызов API выполнен успешно. Если передано значение napi_value, не являющееся числом, возвращается napi_number_expected.
Этот API возвращает примитив C double, эквивалентный заданному значению JavaScript number.
napi_get_value_bigint_int64
napi_status napi_get_value_bigint_int64(napi_env env,
napi_value value,
int64_t* result,
bool* lossless); copy -
[in] env: Среда, в которой вызывается API -
[in] value:napi_value, представляющий значение JavaScriptBigInt. -
[out] result: Примитив Cint64_t, эквивалентный заданному значению JavaScriptBigInt. -
[out] lossless: Указывает, было ли значениеBigIntпреобразовано без потерь.
Возвращает napi_ok, если вызов API выполнен успешно. Если передано значение, не являющееся BigInt, возвращается napi_bigint_expected.
Этот API возвращает примитив C int64_t, эквивалентный заданному значению JavaScript BigInt. При необходимости значение будет усечено, а lossless будет установлено в false.
napi_get_value_bigint_uint64
napi_status napi_get_value_bigint_uint64(napi_env env,
napi_value value,
uint64_t* result,
bool* lossless); copy -
[in] env: Среда, в которой вызывается API. -
[in] value:napi_value, представляющий значение JavaScriptBigInt. -
[out] result: Примитив Cuint64_t, эквивалентный заданному значению JavaScriptBigInt. -
[out] lossless: Указывает, было ли значениеBigIntпреобразовано без потерь.
Возвращает napi_ok, если вызов API выполнен успешно. Если передано значение, не являющееся BigInt, возвращается napi_bigint_expected.
Этот API возвращает примитив C uint64_t, эквивалентный заданному значению JavaScript BigInt. При необходимости значение будет усечено, а lossless будет установлено в false.
napi_get_value_bigint_words
napi_status napi_get_value_bigint_words(napi_env env,
napi_value value,
int* sign_bit,
size_t* word_count,
uint64_t* words); copy -
[in] env: Среда, в которой вызывается API. -
[in] value:napi_value, представляющий значение JavaScriptBigInt. -
[out] sign_bit: Целое число, указывающее, является ли значение JavaScriptBigIntположительным или отрицательным. -
[in/out] word_count: Должно быть инициализировано длиной массиваwords. При возврате ему будет присвоено фактическое количество слов, необходимое для хранения этогоBigInt. -
[out] words: Указатель на предварительно выделенный массив 64-битных слов.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API преобразует одно значение BigInt в бит знака, массив 64-битных слов в порядке от младшего к старшему байту и количество элементов в массиве. Для получения только word_count значения sign_bit и words могут быть одновременно установлены в NULL.
napi_get_value_external
napi_status napi_get_value_external(napi_env env,
napi_value value,
void** result) copy -
[in] env: Среда, в которой вызывается API. -
[in] value:napi_value, представляющий внешнее значение JavaScript. -
[out] result: Указатель на данные, обёрнутые во внешнее значение JavaScript.
Возвращает napi_ok, если вызов API выполнен успешно. Если передано значение napi_value, не являющееся внешним, возвращается napi_invalid_arg.
Этот API извлекает указатель на внешние данные, ранее переданный в napi_create_external().
napi_get_value_int32
napi_status napi_get_value_int32(napi_env env,
napi_value value,
int32_t* result) copy -
[in] env: Среда, в которой вызывается API. -
[in] value:napi_value, представляющий значение JavaScriptnumber. -
[out] result: Примитив Cint32, эквивалентный заданному значению JavaScriptnumber.
Возвращает napi_ok, если вызов API выполнен успешно. Если передано значение napi_value, не являющееся числом, возвращается napi_number_expected.
Этот API возвращает примитив C int32, эквивалентный заданному значению JavaScript number.
Если число выходит за пределы диапазона 32-разрядного целого числа, результат усекается до младших 32 бит. Это может привести к тому, что большое положительное число станет отрицательным, если значение > 231 - 1.
Для не конечных числовых значений (NaN, +Infinity или -Infinity) результат устанавливается равным нулю.
napi_get_value_int64
napi_status napi_get_value_int64(napi_env env,
napi_value value,
int64_t* result) copy -
[in] env: Среда, в которой вызывается API. -
[in] value:napi_value, представляющий значение JavaScriptnumber. -
[out] result: Примитив Cint64, эквивалентный заданному значению JavaScriptnumber.
Возвращает napi_ok, если вызов API выполнен успешно. Если передано значение napi_value, не являющееся числом, возвращается napi_number_expected.
Этот API возвращает примитив C int64, эквивалентный заданному значению JavaScript number.
Значения number за пределами диапазона от Number.MIN_SAFE_INTEGER -(2**53 - 1) до Number.MAX_SAFE_INTEGER (2**53 - 1) теряют точность.
Для не конечных числовых значений (NaN, +Infinity или -Infinity) результат устанавливается равным нулю.
napi_get_value_string_latin1
napi_status napi_get_value_string_latin1(napi_env env,
napi_value value,
char* buf,
size_t bufsize,
size_t* result) copy -
[in] env: Среда, в которой вызывается API. -
[in] value:napi_value, представляющий строку JavaScript. -
[in] buf: Буфер, в который записывается строка в кодировке ISO-8859-1. Если переданоNULL, длина строки в байтах без завершающего нулевого символа возвращается вresult. -
[in] bufsize: Размер буфера назначения. Если этого значения недостаточно, возвращаемая строка усекается и завершается нулевым символом. Если значение равно нулю, строка не возвращается, а буфер не изменяется. -
[out] result: Количество байтов, скопированных в буфер, без завершающего нулевого символа.
Возвращает napi_ok, если вызов API выполнен успешно. Если передано значение string, не являющееся napi_value, возвращается napi_string_expected.
Этот API возвращает строку в кодировке ISO-8859-1, соответствующую переданному значению.
napi_get_value_string_utf8
napi_status napi_get_value_string_utf8(napi_env env,
napi_value value,
char* buf,
size_t bufsize,
size_t* result) copy -
[in] env: Среда, в которой вызывается API. -
[in] value:napi_value, представляющий строку JavaScript. -
[in] buf: Буфер, в который записывается строка в кодировке UTF-8. Если переданоNULL, длина строки в байтах без завершающего нулевого символа возвращается вresult. -
[in] bufsize: Размер буфера назначения. Если этого значения недостаточно, возвращаемая строка усекается и завершается нулевым символом. Если значение равно нулю, строка не возвращается, а буфер не изменяется. -
[out] result: Количество байтов, скопированных в буфер, без завершающего нулевого символа.
Возвращает napi_ok, если вызов API выполнен успешно. Если передано значение string, не являющееся napi_value, возвращается napi_string_expected.
Этот API возвращает строку в кодировке UTF-8, соответствующую переданному значению.
napi_get_value_string_utf16
napi_status napi_get_value_string_utf16(napi_env env,
napi_value value,
char16_t* buf,
size_t bufsize,
size_t* result) copy -
[in] env: Среда, в которой вызывается API. -
[in] value:napi_value, представляющий строку JavaScript. -
[in] buf: Буфер, в который записывается строка в кодировке UTF-16LE. Если переданоNULL, возвращается длина строки в 2-байтовых кодовых единицах без завершающего нулевого символа. -
[in] bufsize: Размер буфера назначения. Если этого значения недостаточно, возвращаемая строка усекается и завершается нулевым символом. Если значение равно нулю, строка не возвращается, а буфер не изменяется. -
[out] result: Количество 2-байтовых кодовых единиц, скопированных в буфер, без завершающего нулевого символа.
Возвращает napi_ok, если вызов API выполнен успешно. Если передано значение string, не являющееся napi_value, возвращается napi_string_expected.
Этот API возвращает строку в кодировке UTF-16, соответствующую переданному значению.
napi_get_value_uint32
napi_status napi_get_value_uint32(napi_env env,
napi_value value,
uint32_t* result) copy -
[in] env: Среда, в которой вызывается API. -
[in] value:napi_value, представляющий значение JavaScriptnumber. -
[out] result: Примитив C, эквивалентный заданномуnapi_valueкакuint32_t.
Возвращает napi_ok, если вызов API выполнен успешно. Если передано значение napi_value, не являющееся числом, возвращается napi_number_expected.
Этот API возвращает примитив C, эквивалентный заданному napi_value как uint32_t.
Функции для получения глобальных экземпляров
napi_get_boolean
napi_status napi_get_boolean(napi_env env, bool value, napi_value* result) copy
-
[in] env: Среда, в которой вызывается API. -
[in] value: Значение логического типа, которое нужно получить. -
[out] result:napi_value, представляющий одиночный объект JavaScriptBoolean, который нужно получить.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API возвращает одиночный объект JavaScript, используемый для представления заданного логического значения.
napi_get_global
napi_status napi_get_global(napi_env env, napi_value* result) copy
-
[in] env: Среда, в которой вызывается API. -
[out] result:napi_value, представляющий глобальный объект JavaScriptglobal.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API возвращает объект global.
napi_get_null
napi_status napi_get_null(napi_env env, napi_value* result) copy
-
[in] env: Среда, в которой вызывается API. -
[out] result:napi_value, представляющий объект JavaScriptnull.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API возвращает объект null.
napi_get_undefined
napi_status napi_get_undefined(napi_env env, napi_value* result) copy
-
[in] env: Среда, в которой вызывается API. -
[out] result:napi_value, представляющий значение JavaScript Undefined.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API возвращает объект Undefined.
Работа со значениями JavaScript и абстрактными операциями
Node-API предоставляет набор API для выполнения некоторых абстрактных операций над значениями JavaScript.
Эти API позволяют выполнять одно из следующих действий:
- Преобразовывать значения JavaScript в определённые типы JavaScript (например,
numberилиstring). - Проверять тип значения JavaScript.
- Проверять равенство двух значений JavaScript.
napi_coerce_to_bool
napi_status napi_coerce_to_bool(napi_env env,
napi_value value,
napi_value* result) copy -
[in] env: среда, в которой вызывается API. -
[in] value: значение JavaScript для преобразования. -
[out] result:napi_value, представляющий преобразованное значение JavaScriptBoolean.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API реализует абстрактную операцию ToBoolean(), определённую в разделе ToBoolean спецификации языка ECMAScript.
napi_coerce_to_number
napi_status napi_coerce_to_number(napi_env env,
napi_value value,
napi_value* result) copy -
[in] env: среда, в которой вызывается API. -
[in] value: значение JavaScript для преобразования. -
[out] result:napi_value, представляющий преобразованное значение JavaScriptnumber.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API реализует абстрактную операцию ToNumber(), определённую в разделе ToNumber спецификации языка ECMAScript. Эта функция может выполнять код JS, если переданное значение является объектом.
napi_coerce_to_object
napi_status napi_coerce_to_object(napi_env env,
napi_value value,
napi_value* result) copy -
[in] env: среда, в которой вызывается API. -
[in] value: значение JavaScript для преобразования. -
[out] result:napi_value, представляющий преобразованное значение JavaScriptObject.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API реализует абстрактную операцию ToObject(), определённую в разделе ToObject спецификации языка ECMAScript.
napi_coerce_to_string
napi_status napi_coerce_to_string(napi_env env,
napi_value value,
napi_value* result) copy -
[in] env: среда, в которой вызывается API. -
[in] value: значение JavaScript для преобразования. -
[out] result:napi_value, представляющий преобразованное значение JavaScriptstring.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API реализует абстрактную операцию ToString(), определённую в разделе ToString спецификации языка ECMAScript. Эта функция может выполнять код JS, если переданное значение является объектом.
napi_typeof
napi_status napi_typeof(napi_env env, napi_value value, napi_valuetype* result) copy
-
[in] env: среда, в которой вызывается API. -
[in] value: значение JavaScript, тип которого нужно определить. -
[out] result: тип значения JavaScript.
Возвращает napi_ok, если вызов API выполнен успешно.
-
napi_invalid_arg, если типvalueне является известным типом ECMAScript, аvalueне является внешним значением.
Этот API реализует поведение, аналогичное вызову оператора typeof для объекта, как определено в разделе «Оператор typeof» спецификации языка ECMAScript. Однако есть несколько отличий:
- Поддерживается обнаружение внешнего значения.
nullопределяется как отдельный тип, тогда как ECMAScripttypeofопределил быobject.
Если value имеет недопустимый тип, возвращается ошибка.
napi_instanceof
napi_status napi_instanceof(napi_env env,
napi_value object,
napi_value constructor,
bool* result) copy -
[in] env: среда, в которой вызывается API. -
[in] object: проверяемое значение JavaScript. -
[in] constructor: объект функции JavaScript — функции-конструктора, с которой выполняется сравнение. -
[out] result: логическое значение, которому присваивается true, еслиobject instanceof constructorимеет значение true.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API реализует вызов оператора instanceof для объекта, как определено в разделе «Оператор instanceof» спецификации языка ECMAScript.
napi_is_array
napi_status napi_is_array(napi_env env, napi_value value, bool* result) copy
-
[in] env: среда, в которой вызывается API. -
[in] value: проверяемое значение JavaScript. -
[out] result: является ли указанный объект массивом.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API реализует вызов операции IsArray для объекта, как определено в разделе IsArray спецификации языка ECMAScript.
napi_is_arraybuffer
napi_status napi_is_arraybuffer(napi_env env, napi_value value, bool* result) copy
-
[in] env: среда, в которой вызывается API. -
[in] value: проверяемое значение JavaScript. -
[out] result: является ли указанный объектArrayBuffer.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API проверяет, является ли переданный Object буфером массива.
napi_is_buffer
napi_status napi_is_buffer(napi_env env, napi_value value, bool* result) copy
-
[in] env: среда, в которой вызывается API. -
[in] value: проверяемое значение JavaScript. -
[out] result: является ли указанныйnapi_valueобъектомnode::BufferилиUint8Array.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API проверяет, является ли переданный Object буфером или Uint8Array. Если вызывающей стороне нужно проверить, является ли значение Uint8Array, следует предпочесть napi_is_typedarray.
napi_is_date
napi_status napi_is_date(napi_env env, napi_value value, bool* result) copy
-
[in] env: среда, в которой вызывается API. -
[in] value: проверяемое значение JavaScript. -
[out] result: представляет ли указанныйnapi_valueобъект JavaScriptDate.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API проверяет, является ли переданный Object датой.
napi_is_error
napi_status napi_is_error(napi_env env, napi_value value, bool* result) copy
-
[in] env: среда, в которой вызывается API. -
[in] value: проверяемое значение JavaScript. -
[out] result: представляет ли указанныйnapi_valueобъектError.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API проверяет, является ли переданный Object объектом Error.
napi_is_typedarray
napi_status napi_is_typedarray(napi_env env, napi_value value, bool* result) copy
-
[in] env: среда, в которой вызывается API. -
[in] value: проверяемое значение JavaScript. -
[out] result: представляет ли указанныйnapi_valueобъектTypedArray.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API проверяет, является ли переданный Object типизированным массивом.
napi_is_dataview
napi_status napi_is_dataview(napi_env env, napi_value value, bool* result) copy
-
[in] env: среда, в которой вызывается API. -
[in] value: проверяемое значение JavaScript. -
[out] result: представляет ли указанныйnapi_valueобъектDataView.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API проверяет, является ли переданный Object объектом DataView.
napi_strict_equals
napi_status napi_strict_equals(napi_env env,
napi_value lhs,
napi_value rhs,
bool* result) copy -
[in] env: среда, в которой вызывается API. -
[in] lhs: проверяемое значение JavaScript. -
[in] rhs: значение JavaScript, с которым выполняется сравнение. -
[out] result: равны ли два объектаnapi_value.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API реализует вызов алгоритма строгого равенства, определённого в разделе IsStrctEqual спецификации языка ECMAScript.
napi_detach_arraybuffer
napi_status napi_detach_arraybuffer(napi_env env,
napi_value arraybuffer) copy -
[in] env: среда, в которой вызывается API. -
[in] arraybuffer: JavaScriptArrayBuffer, который нужно отсоединить.
Возвращает napi_ok, если вызов API выполнен успешно. Если передан ArrayBuffer, который нельзя отсоединить, возвращается napi_detachable_arraybuffer_expected.
Как правило, ArrayBuffer нельзя отсоединить, если он уже был отсоединён. Движок может накладывать дополнительные условия на возможность отсоединения ArrayBuffer. Например, V8 требует, чтобы ArrayBuffer был внешним, то есть созданным с помощью napi_create_external_arraybuffer.
Этот API реализует вызов операции отсоединения ArrayBuffer, определённой в разделе detachArrayBuffer спецификации языка ECMAScript.
napi_is_detached_arraybuffer
napi_status napi_is_detached_arraybuffer(napi_env env,
napi_value arraybuffer,
bool* result) copy -
[in] env: среда, в которой вызывается API. -
[in] arraybuffer: проверяемый JavaScriptArrayBuffer. -
[out] result: отсоединён лиarraybuffer.
Возвращает napi_ok, если вызов API выполнен успешно.
Считается, что ArrayBuffer отсоединён, если его внутренние данные имеют значение null.
Этот API реализует вызов операции ArrayBuffer IsDetachedBuffer, определённой в разделе isDetachedBuffer спецификации языка ECMAScript.
node_api_is_sharedarraybuffer
napi_status node_api_is_sharedarraybuffer(napi_env env, napi_value value, bool* result) copy
-
[in] env: среда, в которой вызывается API. -
[in] value: проверяемое значение JavaScript. -
[out] result: представляет ли указанныйnapi_valueобъектSharedArrayBuffer.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API проверяет, является ли переданный объект SharedArrayBuffer.
node_api_create_sharedarraybuffer
napi_status node_api_create_sharedarraybuffer(napi_env env,
size_t byte_length,
void** data,
napi_value* result) copy -
[in] env: среда, в которой вызывается API. -
[in] byte_length: размер создаваемого разделяемого буфера массива в байтах. -
[out] data: указатель на базовый байтовый буферSharedArrayBuffer. Параметрdataможно не использовать, передавNULL. -
[out] result:napi_value, представляющий JavaScriptSharedArrayBuffer.
Возвращает napi_ok, если вызов API выполнен успешно.
Этот API возвращает значение Node-API, соответствующее JavaScript SharedArrayBuffer. Объекты SharedArrayBuffer используются для представления буферов двоичных данных фиксированной длины, которыми могут совместно пользоваться несколько рабочих потоков.
Выделенный SharedArrayBuffer будет иметь базовый байтовый буфер размером, определяемым переданным параметром byte_length. При необходимости базовый буфер возвращается вызывающей стороне, чтобы она могла напрямую управлять им. Записывать данные в этот буфер напрямую можно только из собственного кода. Чтобы записать данные в этот буфер из JavaScript, необходимо создать типизированный массив или объект DataView.
Объекты JavaScript SharedArrayBuffer описаны в разделе «Объекты SharedArrayBuffer» спецификации языка ECMAScript.
Работа со свойствами JavaScript
Node-API предоставляет набор API для получения и установки свойств объектов JavaScript.
Свойства в JavaScript представлены парой, состоящей из ключа и значения. В основе своей все ключи свойств в Node-API могут быть представлены в одной из следующих форм:
- Именованные: простая строка в кодировке UTF-8
- С целочисленным индексом: значение индекса, представленное как
uint32_t - Значение JavaScript: в Node-API они представлены как
napi_value. Это может бытьnapi_value, представляющийstring,numberилиsymbol.
Значения Node-API представлены типом napi_value. Любой вызов Node-API, требующий значение JavaScript, принимает napi_value. Однако вызывающий код отвечает за то, чтобы убедиться, что рассматриваемый napi_value имеет ожидаемый API тип JavaScript.
API, описанные в этом разделе, предоставляют простой интерфейс для получения и установки свойств произвольных объектов JavaScript, представленных как napi_value.
Например, рассмотрим следующий фрагмент кода JavaScript:
const obj = {};
obj.myProp = 123; copy Эквивалентную операцию можно выполнить со значениями 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;
// Create a napi_value for 123
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; copy Индексированные свойства можно устанавливать аналогичным образом. Рассмотрим следующий фрагмент кода JavaScript:
const arr = []; arr[123] = 'hello'; copy
Эквивалентную операцию можно выполнить со значениями 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; // Create a napi_value for 'hello' 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; copy
Свойства можно получать с помощью API, описанных в этом разделе. Рассмотрим следующий фрагмент кода JavaScript:
const arr = []; const value = arr[123]; copy
Ниже приведён приблизительный эквивалент для 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; copy
Наконец, для повышения производительности объекту можно также назначить несколько свойств. Рассмотрим следующий код JavaScript:
const obj = {};
Object.defineProperties(obj, {
'foo': { value: 123, writable: true, configurable: true, enumerable: true },
'bar': { value: 456, writable: true, configurable: true, enumerable: true },
}); copy Ниже приведён приблизительный эквивалент для 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;
// Create napi_values for 123 and 456
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;
// Set the properties
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; copy Структуры
napi_property_attributes
typedef enum {
napi_default = 0,
napi_writable = 1 << 0,
napi_enumerable = 1 << 1,
napi_configurable = 1 << 2,
// Used with napi_define_class to distinguish static properties
// from instance properties. Ignored by napi_define_properties.
napi_static = 1 << 10,
// Default for class methods.
napi_default_method = napi_writable | napi_configurable,
// Default for object properties, like in JS obj[prop].
napi_default_jsproperty = napi_writable |
napi_enumerable |
napi_configurable,
} napi_property_attributes; copy napi_property_attributes — это битовые флаги, используемые для управления поведением свойств, устанавливаемых для объекта JavaScript. За исключением napi_static, они соответствуют атрибутам, перечисленным в разделе «Атрибуты свойств» спецификации языка ECMAScript. Можно указать один или несколько следующих битовых флагов:
-
napi_default: явные атрибуты для свойства не заданы. По умолчанию свойство доступно только для чтения, не перечисляется и не настраивается. -
napi_writable: свойство доступно для записи. -
napi_enumerable: свойство перечисляется. -
napi_configurable: свойство можно настроить, как определено в разделе «Атрибуты свойств» спецификации языка ECMAScript. -
napi_static: свойство будет определено как статическое свойство класса, а не как свойство экземпляра, которое используется по умолчанию. Используется только вnapi_define_class. Игнорируется вnapi_define_properties. -
napi_default_method: как и метод класса JS, свойство можно настроить и записать, но оно не перечисляется. -
napi_default_jsproperty: как и свойство, заданное присваиванием в JavaScript, свойство доступно для записи, перечисляется и настраивается.
napi_property_descriptor
typedef struct {
// One of utf8name or name should be 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; copy -
utf8name: необязательная строка, описывающая ключ свойства и закодированная в UTF-8. Для свойства необходимо указать либоutf8name, либоname. -
name: необязательныйnapi_value, указывающий на строку или символ JavaScript, которые будут использоваться в качестве ключа свойства. Для свойства необходимо указать либоutf8name, либоname. -
value: значение, получаемое при чтении свойства, если оно является свойством данных. Если этот параметр передан, установитеgetter,setter,methodиdataвNULL(эти члены использоваться не будут). -
getter: функция, вызываемая при чтении свойства. Если этот параметр передан, установитеvalueиmethodвNULL(эти члены использоваться не будут). Среда выполнения неявно вызывает указанную функцию при обращении к свойству из кода JavaScript (или при чтении свойства с помощью вызова Node-API). Дополнительные сведения см. в разделеnapi_callback. -
setter: функция, вызываемая при записи свойства. Если этот параметр передан, установитеvalueиmethodвNULL(эти члены использоваться не будут). Среда выполнения неявно вызывает указанную функцию при установке свойства из кода JavaScript (или при установке свойства с помощью вызова Node-API). Дополнительные сведения см. в разделеnapi_callback. -
method: установите этот параметр, чтобы свойствоvalueобъекта дескриптора свойства было функцией JavaScript, представленной какmethod. Если этот параметр передан, установитеvalue,getterиsetterвNULL(эти члены использоваться не будут). Дополнительные сведения см. в разделеnapi_callback. -
attributes: атрибуты, связанные с конкретным свойством. См.napi_property_attributes. -
data: данные обратного вызова, передаваемые вmethod,getterиsetterпри вызове этой функции.
Функции
napi_get_property_names
napi_status napi_get_property_names(napi_env env,
napi_value object,
napi_value* result); copy -
[in] env: среда, в которой вызывается Node-API. -
[in] object: объект, свойства которого требуется получить. -
[out] result:napi_value, представляющий массив значений JavaScript, содержащих имена свойств объекта. API можно использовать для перебораresultс помощьюnapi_get_array_lengthиnapi_get_element.
Возвращает napi_ok, если API выполнен успешно.
Этот API возвращает имена перечисляемых свойств object в виде массива строк. Свойства object с ключом-символом не включаются.
napi_get_all_property_names
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); copy -
[in] env: среда, в которой вызывается Node-API. -
[in] object: объект, свойства которого требуется получить. -
[in] key_mode: следует ли также получать свойства прототипа. -
[in] key_filter: свойства, которые требуется получить (перечисляемые/читаемые/доступные для записи). -
[in] key_conversion: следует ли преобразовывать числовые ключи свойств в строки. -
[out] result:napi_value, представляющий массив значений JavaScript, содержащих имена свойств объекта. Для перебораresultможно использоватьnapi_get_array_lengthиnapi_get_element.
Возвращает napi_ok, если API выполнен успешно.
Этот API возвращает массив с именами доступных свойств объекта.
napi_set_property
napi_status napi_set_property(napi_env env,
napi_value object,
napi_value key,
napi_value value); copy -
[in] env: среда, в которой вызывается Node-API. -
[in] object: объект, для которого требуется установить свойство. -
[in] key: имя устанавливаемого свойства. -
[in] value: значение свойства.
Возвращает napi_ok, если API выполнен успешно.
Этот API устанавливает свойство для переданного Object.
napi_get_property
napi_status napi_get_property(napi_env env,
napi_value object,
napi_value key,
napi_value* result); copy -
[in] env: среда, в которой вызывается Node-API. -
[in] object: объект, из которого требуется получить свойство. -
[in] key: имя получаемого свойства. -
[out] result: значение свойства.
Возвращает napi_ok, если API выполнен успешно.
Этот API получает запрошенное свойство из переданного Object.
napi_has_property
napi_status napi_has_property(napi_env env,
napi_value object,
napi_value key,
bool* result); copy -
[in] env: среда, в которой вызывается Node-API. -
[in] object: проверяемый объект. -
[in] key: имя свойства, наличие которого требуется проверить. -
[out] result: наличие или отсутствие свойства у объекта.
Возвращает napi_ok, если API выполнен успешно.
Этот API проверяет, содержит ли переданный Object свойство с указанным именем.
napi_delete_property
napi_status napi_delete_property(napi_env env,
napi_value object,
napi_value key,
bool* result); copy -
[in] env: среда, в которой вызывается Node-API. -
[in] object: проверяемый объект. -
[in] key: имя удаляемого свойства. -
[out] result: удалось ли удалить свойство. При необходимостиresultможно игнорировать, передавNULL.
Возвращает napi_ok, если API выполнен успешно.
Этот API пытается удалить собственное свойство key объекта object.
napi_has_own_property
napi_status napi_has_own_property(napi_env env,
napi_value object,
napi_value key,
bool* result); copy -
[in] env: среда, в которой вызывается Node-API. -
[in] object: проверяемый объект. -
[in] key: имя собственного свойства, наличие которого требуется проверить. -
[out] result: наличие или отсутствие собственного свойства у объекта.
Возвращает napi_ok, если API выполнен успешно.
Этот API проверяет, содержит ли переданный Object собственное свойство с указанным именем. key должен быть string или symbol, иначе будет выброшена ошибка. Node-API не выполняет преобразование типов данных.
napi_set_named_property
napi_status napi_set_named_property(napi_env env,
napi_value object,
const char* utf8Name,
napi_value value); copy -
[in] env: среда, в которой вызывается Node-API. -
[in] object: объект, для которого требуется установить свойство. -
[in] utf8Name: имя устанавливаемого свойства. -
[in] value: значение свойства.
Возвращает napi_ok, если API выполнен успешно.
Этот метод эквивалентен вызову napi_set_property с napi_value, созданным из строки, переданной в качестве utf8Name.
napi_get_named_property
napi_status napi_get_named_property(napi_env env,
napi_value object,
const char* utf8Name,
napi_value* result); copy -
[in] env: среда, в которой вызывается Node-API. -
[in] object: объект, из которого требуется получить свойство. -
[in] utf8Name: имя получаемого свойства. -
[out] result: значение свойства.
Возвращает napi_ok, если API выполнен успешно.
Этот метод эквивалентен вызову napi_get_property с napi_value, созданным из строки, переданной в качестве utf8Name.
napi_has_named_property
napi_status napi_has_named_property(napi_env env,
napi_value object,
const char* utf8Name,
bool* result); copy -
[in] env: среда, в которой вызывается Node-API. -
[in] object: проверяемый объект. -
[in] utf8Name: имя свойства, наличие которого требуется проверить. -
[out] result: наличие или отсутствие свойства у объекта.
Возвращает napi_ok, если API выполнен успешно.
Этот метод эквивалентен вызову napi_has_property с napi_value, созданным из строки, переданной в качестве utf8Name.
napi_set_element
napi_status napi_set_element(napi_env env,
napi_value object,
uint32_t index,
napi_value value); copy -
[in] env: среда, в которой вызывается Node-API. -
[in] object: объект, для которого требуется установить свойства. -
[in] index: индекс устанавливаемого свойства. -
[in] value: значение свойства.
Возвращает napi_ok, если API выполнен успешно.
Этот API устанавливает элемент переданного Object.
napi_get_element
napi_status napi_get_element(napi_env env,
napi_value object,
uint32_t index,
napi_value* result); copy -
[in] env: среда, в которой вызывается Node-API. -
[in] object: объект, из которого требуется получить свойство. -
[in] index: индекс получаемого свойства. -
[out] result: значение свойства.
Возвращает napi_ok, если API выполнен успешно.
Этот API получает элемент по запрошенному индексу.
napi_has_element
napi_status napi_has_element(napi_env env,
napi_value object,
uint32_t index,
bool* result); copy -
[in] env: среда, в которой вызывается Node-API. -
[in] object: проверяемый объект. -
[in] index: индекс свойства, наличие которого требуется проверить. -
[out] result: наличие или отсутствие свойства у объекта.
Возвращает napi_ok, если API выполнен успешно.
Этот API сообщает, содержит ли переданный Object элемент по запрошенному индексу.
napi_delete_element
napi_status napi_delete_element(napi_env env,
napi_value object,
uint32_t index,
bool* result); copy -
[in] env: среда, в которой вызывается Node-API. -
[in] object: проверяемый объект. -
[in] index: индекс удаляемого свойства. -
[out] result: удалось ли удалить элемент. При необходимостиresultможно игнорировать, передавNULL.
Возвращает napi_ok, если API выполнен успешно.
Этот API пытается удалить указанный index из object.
napi_define_properties
napi_status napi_define_properties(napi_env env,
napi_value object,
size_t property_count,
const napi_property_descriptor* properties); copy -
[in] env: среда, в которой вызывается Node-API. -
[in] object: объект, для которого требуется определить свойства. -
[in] property_count: число элементов в массивеproperties. -
[in] properties: массив дескрипторов свойств.
Возвращает napi_ok, если API выполнен успешно.
Этот метод позволяет эффективно определять несколько свойств заданного объекта. Свойства определяются с помощью дескрипторов свойств (см. napi_property_descriptor). Получив массив таких дескрипторов свойств, этот API устанавливает свойства объекта по одному, согласно DefineOwnProperty() (описанному в разделе «DefineOwnProperty» спецификации ECMA-262).
napi_object_freeze
napi_status napi_object_freeze(napi_env env,
napi_value object); copy -
[in] env: среда, в которой вызывается Node-API. -
[in] object: объект, который требуется заморозить.
Возвращает napi_ok, если API выполнен успешно.
Этот метод замораживает заданный объект. Это не позволяет добавлять в него новые свойства и удалять существующие, изменять перечисляемость, настраиваемость или возможность записи существующих свойств, а также изменять значения существующих свойств. Кроме того, он запрещает изменять прототип объекта. Это описано в разделе 19.1.2.6 спецификации ECMA-262.
napi_object_seal
napi_status napi_object_seal(napi_env env,
napi_value object); copy -
[in] env: среда, в которой вызывается Node-API. -
[in] object: объект, который требуется запечатать.
Возвращает napi_ok, если API выполнен успешно.
Этот метод запечатывает заданный объект. Это не позволяет добавлять в него новые свойства, а также помечает все существующие свойства как ненастраиваемые. Это описано в разделе 19.1.2.20 спецификации ECMA-262.
node_api_set_prototype
napi_status node_api_set_prototype(napi_env env,
napi_value object,
napi_value value); copy -
[in] env: среда, в которой вызывается Node-API. -
[in] object: объект, прототип которого требуется установить. -
[in] value: значение прототипа.
Возвращает napi_ok, если API выполнен успешно.
Этот API устанавливает прототип переданного Object.
Работа с функциями JavaScript
Node-API предоставляет набор API, позволяющих коду JavaScript вызывать собственный код. Node-API, поддерживающие вызов собственного кода, принимают функции обратного вызова, представленные типом napi_callback. Когда виртуальная машина JavaScript вызывает собственный код, вызывается предоставленная функция napi_callback. API, описанные в этом разделе, позволяют функции обратного вызова выполнять следующие действия:
- Получать сведения о контексте, в котором была вызвана функция обратного вызова.
- Получать аргументы, переданные функции обратного вызова.
- Возвращать из функции обратного вызова значение
napi_value.
Кроме того, Node-API предоставляет набор функций, позволяющих вызывать функции JavaScript из собственного кода. Функцию можно вызвать как обычную функцию JavaScript или как функцию-конструктор.
Любые данные, не являющиеся NULL и переданные этому API через поле data элементов napi_property_descriptor, можно связать с object и освободить при сборке мусора для object, передав и object, и данные в napi_add_finalizer.
napi_call_function
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); copy -
[in] env: среда, в которой вызывается API. -
[in] recv: значениеthis, передаваемое вызываемой функции. -
[in] func:napi_value, представляющий вызываемую функцию JavaScript. -
[in] argc: число элементов в массивеargv. -
[in] argv: массивnapi_values, представляющих значения JavaScript, передаваемые функции в качестве аргументов. -
[out] result:napi_value, представляющий возвращённый объект JavaScript.
Возвращает napi_ok, если API выполнен успешно.
Этот метод позволяет вызывать объект функции JavaScript из собственного дополнения. Это основной способ вызова JavaScript из собственного кода дополнения. Особый случай вызова JavaScript после асинхронной операции описан в разделе napi_make_callback.
Пример использования может выглядеть следующим образом. Рассмотрим следующий фрагмент кода JavaScript:
function AddTwo(num) {
return num + 2;
}
global.AddTwo = AddTwo; copy Затем приведённую выше функцию можно вызвать из собственного дополнения с помощью следующего кода:
// Get the function named "AddTwo" on the global object 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; // Convert the result back to a native type int32_t result; status = napi_get_value_int32(env, return_val, &result); if (status != napi_ok) return; copy
napi_create_function
napi_status napi_create_function(napi_env env,
const char* utf8name,
size_t length,
napi_callback cb,
void* data,
napi_value* result); copy -
[in] env: среда, в которой вызывается API. -
[in] utf8Name: необязательное имя функции в кодировке UTF-8. В JavaScript оно отображается в свойствеnameнового объекта функции. -
[in] length: длинаutf8nameв байтах илиNAPI_AUTO_LENGTH, если строка завершается нулевым символом. -
[in] cb: собственная функция, вызываемая при вызове этого объекта функции. Дополнительные сведения см. в разделеnapi_callback. -
[in] data: контекст данных, предоставленный пользователем. Он будет передан обратно функции при её последующем вызове. -
[out] result:napi_value, представляющий объект JavaScript для вновь созданной функции.
Возвращает napi_ok, если API выполнен успешно.
Этот API позволяет автору дополнения создавать объект функции в собственном коде. Это основной способ вызывать собственный код дополнения из JavaScript.
После этого вызова вновь созданная функция автоматически не становится доступной из скрипта. Чтобы функция была доступна из скрипта, необходимо явно установить её свойство для любого объекта, видимого из JavaScript.
Чтобы предоставить функцию как часть экспортируемых модулем дополнения значений, установите вновь созданную функцию для объекта exports. Пример модуля может выглядеть так:
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) copy С приведённым выше кодом дополнение можно использовать из JavaScript следующим образом:
const myaddon = require('./addon');
myaddon.sayHello(); copy Строка, переданная в require(), — это имя целевого объекта в binding.gyp, отвечающего за создание файла .node.
Любые данные, не являющиеся NULL и переданные этому API через параметр data, можно связать с результирующей функцией JavaScript (возвращаемой в параметре result) и освободить при сборке мусора для функции, передав и функцию JavaScript, и данные в napi_add_finalizer.
Объекты Function JavaScript описаны в разделе «Объекты функций» спецификации языка ECMAScript.
napi_get_cb_info
napi_status napi_get_cb_info(napi_env env,
napi_callback_info cbinfo,
size_t* argc,
napi_value* argv,
napi_value* thisArg,
void** data) copy -
[in] env: среда, в которой вызывается API. -
[in] cbinfo: сведения об обратном вызове, переданные функции обратного вызова. -
[in-out] argc: задаёт размер предоставленного массиваargvи получает фактическое число аргументов. При необходимостиargcможно игнорировать, передавNULL. -
[out] argv: массив C изnapi_value, в который копируются аргументы. Если аргументов больше, чем указано, копируется только запрошенное количество. Если аргументов меньше, чем указано, оставшаяся частьargvзаполняется значениямиnapi_value, представляющимиundefined. При необходимостиargvможно игнорировать, передавNULL. -
[out] thisArg: получает аргумент JavaScriptthisдля вызова. При необходимостиthisArgможно игнорировать, передавNULL. -
[out] data: получает указатель на данные обратного вызова. При необходимостиdataможно игнорировать, передавNULL.
Возвращает napi_ok, если API выполнен успешно.
Этот метод используется внутри функции обратного вызова для получения сведений о вызове, например аргументов и указателя this из заданной информации об обратном вызове.
napi_get_new_target
napi_status napi_get_new_target(napi_env env,
napi_callback_info cbinfo,
napi_value* result) copy -
[in] env: среда, в которой вызывается API. -
[in] cbinfo: сведения об обратном вызове, переданные функции обратного вызова. -
[out] result:new.targetвызова конструктора.
Возвращает napi_ok, если API выполнен успешно.
Этот API возвращает new.target вызова конструктора. Если текущий обратный вызов не является вызовом конструктора, результатом будет NULL.
napi_new_instance
napi_status napi_new_instance(napi_env env,
napi_value cons,
size_t argc,
napi_value* argv,
napi_value* result) copy -
[in] env: среда, в которой вызывается API. -
[in] cons:napi_value, представляющий функцию JavaScript, вызываемую как конструктор. -
[in] argc: число элементов в массивеargv. -
[in] argv: массив значений JavaScript в видеnapi_value, представляющих аргументы конструктора. Еслиargcравно нулю, этот параметр можно опустить, передавNULL. -
[out] result:napi_value, представляющий возвращённый объект JavaScript, которым в данном случае является созданный объект.
Этот метод используется для создания нового значения JavaScript с помощью заданного napi_value, представляющего конструктор объекта. Например, рассмотрим следующий фрагмент:
function MyObject(param) {
this.param = param;
}
const arg = 'hello';
const value = new MyObject(arg); copy Следующий фрагмент позволяет выполнить примерно то же самое с помощью Node-API:
// Get the constructor function 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); copy
Возвращает napi_ok, если API выполнен успешно.
Обёртывание объектов
Node-API позволяет «оборачивать» классы и экземпляры C++, чтобы конструктор и методы класса можно было вызывать из JavaScript.
- API
napi_define_classопределяет класс JavaScript с конструктором, статическими свойствами и методами, а также свойствами и методами экземпляров, соответствующими классу C++. - Когда код JavaScript вызывает конструктор, функция обратного вызова конструктора использует
napi_wrap, чтобы обернуть новый экземпляр C++ в объект JavaScript, а затем возвращает объект-обёртку. - Когда код JavaScript вызывает метод или аксессор свойства класса, вызывается соответствующая функция C++
napi_callback. Для обратного вызова экземпляра функцияnapi_unwrapполучает экземпляр C++, являющийся целью вызова.
Для обёрнутых объектов бывает трудно отличить функцию, вызванную для прототипа класса, от функции, вызванной для экземпляра класса. Распространённый способ решить эту проблему — сохранить постоянную ссылку на конструктор класса для последующих проверок 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 {
// otherwise...
} copy Ссылку необходимо освободить, когда она больше не нужна.
Иногда napi_instanceof() недостаточно, чтобы гарантировать, что объект JavaScript является обёрткой определённого собственного типа. Это особенно актуально, когда обёрнутые объекты JavaScript передаются обратно в аддон через статические методы, а не как значение this методов прототипа. В таких случаях существует вероятность, что они будут развёрнуты неправильно.
const myAddon = require('./build/Release/my_addon.node');
// `openDatabase()` returns a JavaScript object that wraps a native database
// handle.
const dbHandle = myAddon.openDatabase();
// `query()` returns a JavaScript object that wraps a native query handle.
const queryHandle = myAddon.query(dbHandle, 'Gimme ALL the things!');
// There is an accidental error in the line below. The first parameter to
// `myAddon.queryHasRecords()` should be the database handle (`dbHandle`), not
// the query handle (`query`), so the correct condition for the while-loop
// should be
//
// myAddon.queryHasRecords(dbHandle, queryHandle)
//
while (myAddon.queryHasRecords(queryHandle, dbHandle)) {
// retrieve records
} copy В приведённом выше примере myAddon.queryHasRecords() — метод, принимающий два аргумента. Первый — дескриптор базы данных, второй — дескриптор запроса. Метод разворачивает первый аргумент и приводит полученный указатель к типу собственного дескриптора базы данных. Затем он разворачивает второй аргумент и приводит полученный указатель к типу дескриптора запроса. Если аргументы переданы в неправильном порядке, приведение типов выполнится успешно, однако с большой вероятностью базовая операция с базой данных завершится ошибкой или даже вызовет недопустимый доступ к памяти.
Чтобы гарантировать, что указатель, полученный из первого аргумента, действительно указывает на дескриптор базы данных, а указатель, полученный из второго аргумента, действительно указывает на дескриптор запроса, реализация queryHasRecords() должна выполнять проверку типов. Сохранение конструктора класса JavaScript, из которого был создан дескриптор базы данных, и конструктора, из которого был создан дескриптор запроса, в napi_refах может помочь, поскольку тогда napi_instanceof() можно использовать, чтобы убедиться, что экземпляры, переданные в queryHashRecords(), действительно имеют правильный тип.
К сожалению, napi_instanceof() не защищает от манипуляций с прототипом. Например, прототип экземпляра дескриптора базы данных можно установить в прототип конструктора экземпляров дескриптора запроса. В этом случае экземпляр дескриптора базы данных может выглядеть как экземпляр дескриптора запроса и пройти проверку napi_instanceof() для экземпляра дескриптора запроса, при этом всё ещё содержать указатель на дескриптор базы данных.
Для этого Node-API предоставляет возможность присваивать типовые метки.
Типовая метка — это 128-битное целое число, уникальное для аддона. Node-API предоставляет структуру napi_type_tag для хранения типовой метки. Когда такое значение передаётся вместе с объектом JavaScript или external, хранящимся в 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().
// This value is the type tag for a database handle. The command
//
// uuidgen | sed -r -e 's/-//g' -e 's/(.{16})(.*)/0x\1, 0x\2/'
//
// can be used to obtain the two values with which to initialize the structure.
static const napi_type_tag DatabaseHandleTypeTag = {
0x1edf75a38336451d, 0xa5ed9ce2e4c00c38
};
// This value is the type tag for a query handle.
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;
// Perform the underlying action which results in a database handle.
DatabaseHandle* dbHandle = open_database();
// Create a new, empty JS object.
status = napi_create_object(env, &result);
if (status != napi_ok) return NULL;
// Tag the object to indicate that it holds a pointer to a `DatabaseHandle`.
status = napi_type_tag_object(env, result, &DatabaseHandleTypeTag);
if (status != napi_ok) return NULL;
// Store the pointer to the `DatabaseHandle` structure inside the JS object.
status = napi_wrap(env, result, dbHandle, NULL, NULL, NULL);
if (status != napi_ok) return NULL;
return result;
}
// Later when we receive a JavaScript object purporting to be a database handle
// we can use `napi_check_object_type_tag()` to ensure that it is indeed such a
// handle.
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;
// Check that the object passed as the first parameter has the previously
// applied tag.
status = napi_check_object_type_tag(env,
argv[0],
&DatabaseHandleTypeTag,
&is_db_handle);
if (status != napi_ok) return NULL;
// Throw a `TypeError` if it doesn't.
if (!is_db_handle) {
// Throw a TypeError.
return NULL;
}
} copy
napi_define_class
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); copy -
[in] env: среда, в которой вызывается API. -
[in] utf8name: имя функции-конструктора JavaScript. Для ясности при обёртывании класса C++ рекомендуется использовать имя класса C++. -
[in] length: длинаutf8nameв байтах или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, представляющий функцию-конструктор класса.
Возвращает napi_ok, если API выполнен успешно.
Определяет класс JavaScript, в том числе:
- Функцию-конструктор JavaScript с именем класса. При обёртывании соответствующего класса C++ функция обратного вызова, переданная через
constructor, может создавать новый экземпляр класса C++, который затем можно поместить внутрь создаваемого экземпляра объекта JavaScript с помощьюnapi_wrap. - Свойства функции-конструктора, реализация которых может вызывать соответствующие статические свойства данных, аксессоры и методы класса C++ (определённые дескрипторами свойств с атрибутом
napi_static). - Свойства объекта
prototypeфункции-конструктора. При обёртывании класса C++ из статических функций, указанных в дескрипторах свойств без атрибутаnapi_static, можно вызывать нестатические свойства данных, аксессоры и методы класса C++ после получения экземпляра класса C++, помещённого внутрь экземпляра объекта JavaScript с помощьюnapi_unwrap.
При обёртывании класса C++ функция обратного вызова конструктора C++, переданная через constructor, должна быть статическим методом класса, который вызывает фактический конструктор класса, затем оборачивает новый экземпляр C++ в объект JavaScript и возвращает объект-обёртку. Подробнее см. в разделе napi_wrap.
Функцию-конструктор JavaScript, возвращённую из napi_define_class, часто сохраняют и позднее используют для создания новых экземпляров класса из собственного кода и/или для проверки того, являются ли переданные значения экземплярами класса. В этом случае, чтобы предотвратить сборку мусора для значения функции, можно создать сильную постоянную ссылку на неё с помощью napi_create_reference, обеспечив, чтобы счётчик ссылок оставался >= 1.
Любые данные, не относящиеся к NULL, переданные этому API через параметр data или поле data элементов массива napi_property_descriptor, можно связать с результирующим конструктором JavaScript (который возвращается в параметре result) и освободить при сборке мусора для класса, передав функцию JavaScript и данные в napi_add_finalizer.
napi_wrap
napi_status napi_wrap(napi_env env,
napi_value js_object,
void* native_object,
napi_finalize finalize_cb,
void* finalize_hint,
napi_ref* result); copy -
[in] env: среда, в которой вызывается API. -
[in] js_object: объект JavaScript, который будет служить обёрткой для собственного объекта. -
[in] native_object: собственный экземпляр, который будет обёрнут в объект JavaScript. -
[in] finalize_cb: необязательная собственная функция обратного вызова, которую можно использовать для освобождения собственного экземпляра после сборки мусора для объекта JavaScript. Подробнее см. в разделеnapi_finalize. -
[in] finalize_hint: необязательная контекстная подсказка, передаваемая функции обратного вызова финализации. -
[out] result: необязательная ссылка на обёрнутый объект.
Возвращает napi_ok, если API выполнен успешно.
Оборачивает собственный экземпляр в объект JavaScript. Позднее собственный экземпляр можно получить с помощью napi_unwrap().
Когда код JavaScript вызывает конструктор класса, определённого с помощью napi_define_class(), вызывается napi_callback конструктора. После создания экземпляра собственного класса функция обратного вызова должна вызвать napi_wrap(), чтобы обернуть только что созданный экземпляр в уже созданный объект JavaScript, являющийся аргументом this функции обратного вызова конструктора. (Этот объект this создан на основе prototype функции-конструктора, поэтому в нём уже определены все свойства и методы экземпляра.)
Обычно при обёртывании экземпляра класса следует предоставить функцию обратного вызова финализации, которая просто удаляет собственный экземпляр, полученный как аргумент data функции обратного вызова финализации.
Необязательная возвращаемая ссылка изначально является слабой, то есть её счётчик ссылок равен 0. Обычно этот счётчик ссылок временно увеличивают во время асинхронных операций, для которых требуется, чтобы экземпляр оставался действительным.
Предупреждение: необязательную возвращаемую ссылку (если она получена) следует удалять с помощью napi_delete_reference ТОЛЬКО в ответ на вызов функции обратного вызова финализации. Если удалить её раньше, функция обратного вызова финализации может никогда не вызываться. Поэтому при получении ссылки также требуется функция обратного вызова финализации, чтобы обеспечить корректное удаление ссылки.
Вызовы функций обратного вызова финализации могут откладываться, из-за чего возникает промежуток времени, когда объект уже собран сборщиком мусора (а слабая ссылка недействительна), но функция финализации ещё не вызвана. При использовании napi_get_reference_value() для слабых ссылок, возвращённых napi_wrap(), всё равно необходимо обрабатывать пустой результат.
Повторный вызов napi_wrap() для объекта приведёт к ошибке. Чтобы связать с объектом другой собственный экземпляр, сначала используйте napi_remove_wrap().
napi_unwrap
napi_status napi_unwrap(napi_env env,
napi_value js_object,
void** result); copy -
[in] env: среда, в которой вызывается API. -
[in] js_object: объект, связанный с собственным экземпляром. -
[out] result: указатель на обёрнутый собственный экземпляр.
Возвращает napi_ok, если API выполнен успешно.
Получает собственный экземпляр, ранее обёрнутый в объект JavaScript с помощью napi_wrap().
Когда код JavaScript вызывает метод или аксессор свойства класса, вызывается соответствующая функция napi_callback. Если функция обратного вызова относится к методу или аксессору экземпляра, аргумент this функции обратного вызова является объектом-обёрткой; обёрнутый экземпляр C++, являющийся целью вызова, можно получить, вызвав napi_unwrap() для объекта-обёртки.
napi_remove_wrap
napi_status napi_remove_wrap(napi_env env,
napi_value js_object,
void** result); copy -
[in] env: среда, в которой вызывается API. -
[in] js_object: объект, связанный с собственным экземпляром. -
[out] result: указатель на обёрнутый собственный экземпляр.
Возвращает napi_ok, если API выполнен успешно.
Получает собственный экземпляр, ранее обёрнутый в объект JavaScript js_object с помощью napi_wrap(), и удаляет обёртку. Если с обёрткой была связана функция обратного вызова финализации, она больше не будет вызываться при сборке мусора для объекта JavaScript.
napi_type_tag_object
napi_status napi_type_tag_object(napi_env env,
napi_value js_object,
const napi_type_tag* type_tag); copy -
[in] env: среда, в которой вызывается API. -
[in] js_object: объект JavaScript или external, который нужно пометить. -
[in] type_tag: метка, которой нужно пометить объект.
Возвращает napi_ok, если API выполнен успешно.
Связывает значение указателя type_tag с объектом JavaScript или external. Затем napi_check_object_type_tag() можно использовать, чтобы сравнить метку, связанную с объектом, с меткой, принадлежащей аддону, и убедиться, что объект имеет правильный тип.
Если с объектом уже связана типовая метка, этот API вернёт napi_invalid_arg.
napi_check_object_type_tag
napi_status napi_check_object_type_tag(napi_env env,
napi_value js_object,
const napi_type_tag* type_tag,
bool* result); copy -
[in] env: среда, в которой вызывается API. -
[in] js_object: объект JavaScript или external, типовую метку которого нужно проверить. -
[in] type_tag: метка для сравнения с любой меткой, найденной у объекта. -
[out] result: совпадает ли указанная типовая метка с типовой меткой объекта.falseтакже возвращается, если у объекта не найдена типовая метка.
Возвращает napi_ok, если API выполнен успешно.
Сравнивает указатель, переданный как type_tag, с любым указателем, который можно найти у js_object. Если у js_object не найдена метка или найденная метка не совпадает с type_tag, то result устанавливается в false. Если метка найдена и совпадает с type_tag, то result устанавливается в true.
napi_add_finalizer
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); copy -
[in] env: среда, в которой вызывается API. -
[in] js_object: объект JavaScript, к которому будут присоединены собственные данные. -
[in] finalize_data: необязательные данные, передаваемые вfinalize_cb. -
[in] finalize_cb: собственная функция обратного вызова, которая будет использоваться для освобождения собственных данных после сборки мусора для объекта JavaScript. Подробнее см. в разделеnapi_finalize. -
[in] finalize_hint: необязательная контекстная подсказка, передаваемая функции обратного вызова финализации. -
[out] result: необязательная ссылка на объект JavaScript.
Возвращает napi_ok, если API выполнен успешно.
Добавляет функцию обратного вызова napi_finalize, которая будет вызвана после сборки мусора для объекта JavaScript в js_object.
Этот API можно вызывать для одного объекта JavaScript несколько раз.
Предупреждение: необязательную возвращаемую ссылку (если она получена) следует удалять с помощью napi_delete_reference ТОЛЬКО в ответ на вызов функции обратного вызова финализации. Если удалить её раньше, функция обратного вызова финализации может никогда не вызываться. Поэтому при получении ссылки также требуется функция обратного вызова финализации, чтобы обеспечить корректное удаление ссылки.
node_api_post_finalizer
napi_status node_api_post_finalizer(node_api_basic_env env,
napi_finalize finalize_cb,
void* finalize_data,
void* finalize_hint); copy -
[in] env: среда, в которой вызывается API. -
[in] finalize_cb: собственная функция обратного вызова, которая будет использоваться для освобождения собственных данных после сборки мусора для объекта JavaScript. Подробнее см. в разделеnapi_finalize. -
[in] finalize_data: необязательные данные, передаваемые вfinalize_cb. -
[in] finalize_hint: необязательная контекстная подсказка, передаваемая функции обратного вызова финализации.
Возвращает napi_ok, если API выполнен успешно.
Планирует асинхронный вызов функции обратного вызова napi_finalize в цикле событий.
Обычно функции финализации вызываются во время сборки объектов сборщиком мусора (GC). В этот момент вызов любого Node-API, который может изменить состояние GC, будет отключён и приведёт к аварийному завершению Node.js.
node_api_post_finalizer помогает обойти это ограничение, позволяя аддону отложить вызовы таких Node-API до момента, когда финализация GC завершится.
Простые асинхронные операции
Модулям-аддонам часто требуется использовать асинхронные вспомогательные средства из libuv в своей реализации. Это позволяет планировать выполнение работы в асинхронном режиме, чтобы методы могли возвращать управление до её завершения. Благодаря этому не блокируется выполнение приложения Node.js в целом.
Node-API предоставляет стабильный относительно ABI интерфейс для этих вспомогательных функций, охватывающий наиболее распространённые сценарии асинхронного выполнения.
Node-API определяет структуру napi_async_work, используемую для управления асинхронными рабочими задачами. Экземпляры создаются и удаляются с помощью napi_create_async_work и napi_delete_async_work.
Функции обратного вызова execute и complete вызываются соответственно, когда исполнитель готов приступить к работе и когда он завершает задачу.
Функции execute следует избегать вызовов Node-API, которые могут привести к выполнению JavaScript или взаимодействию с объектами JavaScript. Чаще всего любой код, которому нужно вызывать Node-API, следует размещать в функции обратного вызова complete. Не используйте параметр napi_env в функции обратного вызова выполнения, поскольку это, вероятно, приведёт к выполнению JavaScript.
Эти функции реализуют следующие интерфейсы:
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); copy При вызове этих методов параметр data будет содержать предоставленные аддоном данные void*, переданные в вызов napi_create_async_work.
После создания асинхронную рабочую задачу можно поставить в очередь для выполнения с помощью функции napi_queue_async_work:
napi_status napi_queue_async_work(node_api_basic_env env,
napi_async_work work); copy Если работу нужно отменить до начала выполнения, можно использовать napi_cancel_async_work.
После вызова napi_cancel_async_work функция обратного вызова complete будет вызвана со значением статуса napi_cancelled. Рабочую задачу нельзя удалять до вызова функции обратного вызова complete, даже если она была отменена.
napi_create_async_work
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); copy -
[in] env: среда, в которой вызывается API. -
[in] async_resource: необязательный объект, связанный с асинхронной работой и передаваемый возможным хукамasync_hooksinit. -
[in] async_resource_name: идентификатор типа предоставляемого ресурса для диагностической информации, доступной через APIasync_hooks. -
[in] execute: собственная функция, которая должна вызываться для асинхронного выполнения логики. Указанная функция вызывается в потоке из пула рабочих потоков и может выполняться параллельно с потоком основного цикла событий. -
[in] complete: собственная функция, которая будет вызвана после завершения или отмены асинхронной логики. Указанная функция вызывается в потоке основного цикла событий. Подробнее см. в разделеnapi_async_complete_callback. -
[in] data: предоставленный пользователем контекст данных. Он будет передан обратно функциям выполнения и завершения. -
[out] result:napi_async_work*, представляющий дескриптор только что созданной асинхронной рабочей задачи.
Возвращает napi_ok, если API выполнен успешно.
Этот API выделяет объект рабочей задачи, используемый для асинхронного выполнения логики. Когда задача больше не нужна, объект следует освободить с помощью napi_delete_async_work.
async_resource_name должна быть строкой UTF-8 с завершающим нулевым символом.
Идентификатор async_resource_name задаётся пользователем и должен отражать тип выполняемой асинхронной работы. Также рекомендуется включать в идентификатор пространство имён, например имя модуля. Дополнительные сведения см. в документации async_hooks.
napi_delete_async_work
napi_status napi_delete_async_work(napi_env env,
napi_async_work work); copy -
[in] env: среда, в которой вызывается API. -
[in] work: дескриптор, возвращённый вызовомnapi_create_async_work.
Возвращает napi_ok, если API выполнен успешно.
Этот API освобождает ранее выделенный объект рабочей задачи.
Этот API можно вызывать, даже если ожидает обработки исключение JavaScript.
napi_queue_async_work
napi_status napi_queue_async_work(node_api_basic_env env,
napi_async_work work); copy -
[in] env: среда, в которой вызывается API. -
[in] work: дескриптор, возвращённый вызовомnapi_create_async_work.
Возвращает napi_ok, если API выполнен успешно.
Этот API запрашивает постановку ранее выделенной рабочей задачи в очередь на выполнение. После успешного возврата этот API нельзя повторно вызывать с тем же элементом napi_async_work, иначе результат будет неопределённым.
napi_cancel_async_work
napi_status napi_cancel_async_work(node_api_basic_env env,
napi_async_work work); copy -
[in] env: среда, в которой вызывается API. -
[in] work: дескриптор, возвращённый вызовомnapi_create_async_work.
Возвращает napi_ok, если API выполнен успешно.
Этот API отменяет поставленную в очередь работу, если её выполнение ещё не началось. Если выполнение уже началось, отменить её нельзя, и будет возвращено napi_generic_failure. При успешной отмене функция обратного вызова complete будет вызвана со значением статуса napi_cancelled. Рабочую задачу нельзя удалять до вызова функции обратного вызова complete, даже если она была успешно отменена.
Этот API можно вызывать, даже если ожидает обработки исключение JavaScript.
Пользовательские асинхронные операции
Описанные выше простые API для асинхронной работы подходят не для всех сценариев. При использовании любого другого механизма асинхронной работы необходимы следующие API, чтобы среда выполнения могла правильно отслеживать асинхронную операцию.
napi_async_init
napi_status napi_async_init(napi_env env,
napi_value async_resource,
napi_value async_resource_name,
napi_async_context* result) copy -
[in] env: Среда, в которой вызывается API. -
[in] async_resource: Объект, связанный с асинхронной работой, который будет передан возможнымasync_hooksinitхукам и доступен черезasync_hooks.executionAsyncResource(). -
[in] async_resource_name: Идентификатор типа ресурса, предоставляемого для диагностической информации, доступной через APIasync_hooks. -
[out] result: Инициализированный асинхронный контекст.
Возвращает napi_ok, если API выполнен успешно.
Объект async_resource необходимо сохранять до вызова napi_async_destroy, чтобы связанные с async_hooks API работали правильно. Для сохранения совместимости ABI с предыдущими версиями объекты napi_async_context не поддерживают сильную ссылку на объекты async_resource, чтобы не допустить утечек памяти. Однако, если движок JavaScript удалит async_resource сборщиком мусора до того, как napi_async_context будет уничтожен с помощью napi_async_destroy, вызов связанных с napi_async_context API, таких как napi_open_callback_scope и napi_make_callback, может привести к проблемам, например к потере асинхронного контекста при использовании API AsyncLocalStorage.
Для сохранения совместимости ABI с предыдущими версиями передача NULL для async_resource не приводит к ошибке. Однако это не рекомендуется, поскольку может привести к нежелательному поведению хуков async_hooks init и async_hooks.executionAsyncResource(): нижележащая реализация async_hooks теперь требует ресурс для связывания асинхронных обратных вызовов.
napi_async_destroy
napi_status napi_async_destroy(napi_env env,
napi_async_context async_context); copy -
[in] env: Среда, в которой вызывается API. -
[in] async_context: Асинхронный контекст, который требуется уничтожить.
Возвращает napi_ok, если API выполнен успешно.
Это API можно вызвать, даже если ожидает обработки исключение JavaScript.
napi_make_callback
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); copy -
[in] env: Среда, в которой вызывается API. -
[in] async_context: Контекст асинхронной операции, из которой вызывается обратный вызов. Обычно это значение, ранее полученное с помощьюnapi_async_init. Для сохранения совместимости ABI с предыдущими версиями передачаNULLдляasync_contextне приводит к ошибке. Однако это нарушает работу асинхронных хуков. Возможные проблемы включают потерю асинхронного контекста при использовании APIAsyncLocalStorage. -
[in] recv: Значениеthis, передаваемое вызываемой функции. -
[in] func:napi_value, представляющий вызываемую функцию JavaScript. -
[in] argc: Количество элементов в массивеargv. -
[in] argv: Массив значений JavaScript в видеnapi_value, представляющих аргументы функции. Еслиargcравен нулю, этот параметр можно опустить, передавNULL. -
[out] result:napi_value, представляющий возвращаемый объект JavaScript.
Возвращает napi_ok, если API выполнен успешно.
Этот метод позволяет вызывать объект функции JavaScript из собственного дополнения. API похож на napi_call_function. Однако он используется для вызова JavaScript из собственного кода после возвращения из асинхронной операции (когда в стеке нет других скриптов). По сути, это простая обёртка над node::MakeCallback.
Обратите внимание: внутри napi_make_callback использовать napi_async_complete_callback не требуется; в этом случае асинхронный контекст обратного вызова уже настроен, поэтому достаточно и правильно напрямую вызвать napi_call_function. Функция napi_make_callback может потребоваться при реализации пользовательского асинхронного поведения, не использующего napi_create_async_work.
Любые объекты process.nextTick или Promise, поставленные JavaScript в очередь микрозадач во время обратного вызова, будут выполнены до возврата в C/C++.
napi_open_callback_scope
NAPI_EXTERN napi_status napi_open_callback_scope(napi_env env,
napi_value resource_object,
napi_async_context context,
napi_callback_scope* result) copy -
[in] env: Среда, в которой вызывается API. -
[in] resource_object: Объект, связанный с асинхронной работой, который будет передан возможным хукамasync_hooksinit. Этот параметр устарел и игнорируется во время выполнения. Вместо него используйте параметрasync_resourceвnapi_async_init. -
[in] context: Контекст асинхронной операции, из которой вызывается обратный вызов. Это должно быть значение, ранее полученное с помощьюnapi_async_init. -
[out] result: Созданная область видимости.
В некоторых случаях (например, при разрешении промисов) для выполнения определённых вызовов Node-API необходимо создать эквивалент области видимости, связанной с обратным вызовом. Если в стеке нет других скриптов, функции napi_open_callback_scope и napi_close_callback_scope можно использовать для открытия и закрытия необходимой области видимости.
napi_close_callback_scope
NAPI_EXTERN napi_status napi_close_callback_scope(napi_env env,
napi_callback_scope scope) copy -
[in] env: Среда, в которой вызывается API. -
[in] scope: Область видимости, которую требуется закрыть.
Это API можно вызвать, даже если ожидает обработки исключение JavaScript.
Управление версиями
napi_get_node_version
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); copy -
[in] env: Среда, в которой вызывается API. -
[out] version: Указатель на сведения о версии самого Node.js.
Возвращает napi_ok, если API выполнен успешно.
Эта функция заполняет структуру version основным, дополнительным и исправительным номерами версии запущенной версии Node.js, а поле release — значением process.release.name.
Возвращённый буфер выделен статически, освобождать его не нужно.
napi_get_version
napi_status napi_get_version(node_api_basic_env env,
uint32_t* result); copy -
[in] env: Среда, в которой вызывается API. -
[out] result: Наибольшая поддерживаемая версия Node-API.
Возвращает napi_ok, если API выполнен успешно.
Этот API возвращает наибольшую версию Node-API, поддерживаемую средой выполнения Node.js. Предполагается, что Node-API будет расширяться и новые выпуски Node.js смогут поддерживать дополнительные функции API. Чтобы дополнение могло использовать новую функцию в версиях Node.js, которые её поддерживают, и при этом обеспечивать резервное поведение в версиях Node.js без такой поддержки, выполните следующие действия:
- Вызовите
napi_get_version(), чтобы определить, доступен ли API. - Если доступен, динамически загрузите указатель на функцию с помощью
uv_dlsym(). - Используйте динамически загруженный указатель для вызова функции.
- Если функция недоступна, предоставьте альтернативную реализацию, которая её не использует.
Управление памятью
napi_adjust_external_memory
NAPI_EXTERN napi_status napi_adjust_external_memory(node_api_basic_env env,
int64_t change_in_bytes,
int64_t* result); copy -
[in] env: Среда, в которой вызывается API. -
[in] change_in_bytes: Изменение объёма внешней памяти, удерживаемой объектами JavaScript. -
[out] result: Скорректированное значение. Оно должно отражать общий объём внешней памяти с учётом указанногоchange_in_bytes. Не следует полагаться на абсолютное значение, возвращаемое функцией. Например, реализация может использовать один счётчик для всех дополнений или отдельный счётчик для каждого дополнения.
Возвращает napi_ok, если API выполнен успешно.
Эта функция сообщает среде выполнения объём внешней памяти, удерживаемой объектами JavaScript (то есть объект JavaScript указывает на собственную память, выделенную собственным дополнением). Учёт внешней памяти может привести к более частым глобальным сборкам мусора, чем без него, но это не гарантируется.
Эту функцию следует вызывать так, чтобы дополнение не уменьшало объём внешней памяти сильнее, чем ранее увеличило его.
Промисы
Node-API предоставляет средства для создания объектов Promise, описанных в разделе «Объекты Promise» спецификации ECMA. Промисы реализованы в виде пары объектов. При создании промиса с помощью napi_create_promise() создаётся объект «deferred», который возвращается вместе с Promise. Объект deferred связан с созданным Promise и является единственным способом разрешить или отклонить Promise с помощью napi_resolve_deferred() или napi_reject_deferred(). Объект deferred, созданный с помощью napi_create_promise(), освобождается функцией napi_resolve_deferred() или napi_reject_deferred(). Объект Promise можно вернуть в JavaScript и использовать обычным образом.
Например, чтобы создать промис и передать его асинхронному рабочему потоку:
napi_deferred deferred; napi_value promise; napi_status status; // Create the promise. status = napi_create_promise(env, &deferred, &promise); if (status != napi_ok) return NULL; // Pass the deferred to a function that performs an asynchronous action. do_something_asynchronous(deferred); // Return the promise to JS return promise; copy
Описанная выше функция do_something_asynchronous() выполнит асинхронное действие, а затем разрешит или отклонит deferred, завершив тем самым промис и освободив deferred:
napi_deferred deferred;
napi_value undefined;
napi_status status;
// Create a value with which to conclude the deferred.
status = napi_get_undefined(env, &undefined);
if (status != napi_ok) return NULL;
// Resolve or reject the promise associated with the deferred depending on
// whether the asynchronous action succeeded.
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;
// At this point the deferred has been freed, so we should assign NULL to it.
deferred = NULL; copy
napi_create_promise
napi_status napi_create_promise(napi_env env,
napi_deferred* deferred,
napi_value* promise); copy -
[in] env: Среда, в которой вызывается API. -
[out] deferred: Вновь созданный объект deferred, который впоследствии можно передать вnapi_resolve_deferred()илиnapi_reject_deferred(), чтобы соответственно разрешить или отклонить связанный промис. -
[out] promise: Промис JavaScript, связанный с объектом deferred.
Возвращает napi_ok, если API выполнен успешно.
Этот API создаёт объект deferred и промис JavaScript.
napi_resolve_deferred
napi_status napi_resolve_deferred(napi_env env,
napi_deferred deferred,
napi_value resolution); copy -
[in] env: Среда, в которой вызывается API. -
[in] deferred: Объект deferred, связанный промис которого требуется разрешить. -
[in] resolution: Значение, которым требуется разрешить промис.
Этот API разрешает промис JavaScript через связанный с ним объект deferred. Поэтому его можно использовать только для разрешения промисов JavaScript, для которых доступен соответствующий объект deferred. Это означает, что промис должен быть создан с помощью napi_create_promise(), а возвращённый при этом объект deferred необходимо сохранить, чтобы передать его этому API.
После успешного выполнения объект deferred освобождается.
napi_reject_deferred
napi_status napi_reject_deferred(napi_env env,
napi_deferred deferred,
napi_value rejection); copy -
[in] env: Среда, в которой вызывается API. -
[in] deferred: Объект deferred, связанный промис которого требуется отклонить. -
[in] rejection: Значение, которым требуется отклонить промис.
Этот API отклоняет промис JavaScript через связанный с ним объект deferred. Поэтому его можно использовать только для отклонения промисов JavaScript, для которых доступен соответствующий объект deferred. Это означает, что промис должен быть создан с помощью napi_create_promise(), а возвращённый при этом объект deferred необходимо сохранить, чтобы передать его этому API.
После успешного выполнения объект deferred освобождается.
napi_is_promise
napi_status napi_is_promise(napi_env env,
napi_value value,
bool* is_promise); copy -
[in] env: Среда, в которой вызывается API. -
[in] value: Проверяемое значение -
[out] is_promise: Флаг, указывающий, является лиpromiseнативным объектом Promise (то есть объектом Promise, созданным нижележащим движком).
Выполнение скриптов
Node-API предоставляет API для выполнения строки, содержащей JavaScript, с помощью нижележащего движка JavaScript.
napi_run_script
NAPI_EXTERN napi_status napi_run_script(napi_env env,
napi_value script,
napi_value* result); copy -
[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
NAPI_EXTERN napi_status napi_get_uv_event_loop(node_api_basic_env env,
struct uv_loop_s** loop); copy -
[in] env: Среда, в которой вызывается API. -
[out] loop: Текущий экземпляр цикла libuv.
Примечание. Хотя libuv со временем оставалась относительно стабильной, она не гарантирует стабильность ABI. Следует избегать использования этой функции: из-за неё дополнение может оказаться несовместимым с разными версиями Node.js. Во многих случаях альтернативой служат асинхронные потокобезопасные вызовы функций.
Асинхронные потокобезопасные вызовы функций
Функции JavaScript обычно можно вызывать только из главного потока нативного дополнения. Если дополнение создает дополнительные потоки, функции Node-API, которым требуется napi_env, napi_value или napi_ref, нельзя вызывать из этих потоков.
Если у дополнения есть дополнительные потоки и функции JavaScript нужно вызывать по результатам обработки, завершенной этими потоками, потоки должны взаимодействовать с главным потоком дополнения, чтобы главный поток мог вызывать функции JavaScript от их имени. API потокобезопасных функций предоставляют простой способ это сделать.
Эти API предоставляют тип napi_threadsafe_function, а также API для создания, уничтожения и вызова объектов этого типа. napi_create_threadsafe_function() создает постоянную ссылку на napi_value, содержащую функцию JavaScript, которую можно вызывать из нескольких потоков. Вызовы выполняются асинхронно. Это означает, что значения, с которыми нужно вызвать обратный вызов JavaScript, помещаются в очередь, а для каждого значения в очереди в конечном итоге будет выполнен вызов функции JavaScript.
При создании napi_threadsafe_function можно передать обратный вызов napi_finalize. Он будет вызван в главном потоке, когда потокобезопасная функция будет готова к уничтожению. Он получает контекст и данные для финализации, переданные при создании, и позволяет выполнить очистку после работы потоков, например вызвать uv_thread_join(). После завершения обратного вызова финализации никакие потоки, кроме потока главного цикла, не должны использовать потокобезопасную функцию.
Значение context, переданное при вызове napi_create_threadsafe_function(), можно получить из любого потока, вызвав 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 блокируется до появления свободного места в очереди. napi_call_threadsafe_function() никогда не блокируется, если потокобезопасная функция создана с максимальным размером очереди 0.
Не следует вызывать napi_call_threadsafe_function() со значением napi_tsfn_blocking из потока JavaScript, поскольку при заполненной очереди это может привести к взаимной блокировке потока JavaScript.
Фактический вызов JavaScript контролируется обратным вызовом, переданным через параметр call_js_cb. call_js_cb вызывается в главном потоке для каждого значения, помещенного в очередь успешным вызовом napi_call_threadsafe_function(). Если такой обратный вызов не передан, будет использоваться обратный вызов по умолчанию, и вызов JavaScript не будет иметь аргументов. Обратный вызов call_js_cb получает функцию JavaScript, которую нужно вызвать, в качестве napi_value среди параметров, а также указатель контекста void*, использованный при создании napi_threadsafe_function, и следующий указатель данных, созданный одним из вторичных потоков. Затем обратный вызов может использовать такой API, как napi_call_function(), для вызова JavaScript.
Обратный вызов также может быть вызван, когда env и call_js_cb имеют значение NULL. Это означает, что вызовы JavaScript больше невозможны, хотя в очереди остаются элементы, которые, возможно, нужно освободить. Обычно это происходит, когда процесс Node.js завершается, пока потокобезопасная функция еще активна.
Вызывать JavaScript через napi_make_callback() не требуется, поскольку Node-API запускает call_js_cb в контексте, подходящем для обратных вызовов.
За один такт цикла событий может быть вызвано ноль или более элементов очереди. Приложениям не следует рассчитывать на какое-либо конкретное поведение, кроме того, что вызовы обратных вызовов будут продвигаться, а события будут вызываться с течением времени.
Подсчет ссылок на потокобезопасные функции
В течение времени существования объекта napi_threadsafe_function в него можно добавлять потоки и удалять их из него. Поэтому, помимо указания начального числа потоков при создании, можно вызвать napi_acquire_threadsafe_function, чтобы сообщить о запуске нового потока, который будет использовать потокобезопасную функцию. Аналогично можно вызвать napi_release_threadsafe_function, чтобы сообщить, что существующий поток перестанет использовать потокобезопасную функцию.
Объекты napi_threadsafe_function уничтожаются, когда каждый использующий объект поток вызвал napi_release_threadsafe_function() или получил статус возврата napi_closing в ответ на вызов napi_call_threadsafe_function. Перед уничтожением napi_threadsafe_function очередь очищается. napi_release_threadsafe_function() должен быть последним API-вызовом, выполняемым для данного napi_threadsafe_function, поскольку после завершения вызова нет гарантии, что napi_threadsafe_function все еще выделен. По той же причине не используйте потокобезопасную функцию после получения значения возврата napi_closing в ответ на вызов napi_call_threadsafe_function. Данные, связанные с napi_threadsafe_function, можно освободить в обратном вызове napi_finalize, переданном в napi_create_threadsafe_function(). Параметр initial_thread_count функции napi_create_threadsafe_function задает начальное число получений потокобезопасной функции вместо многократного вызова napi_acquire_threadsafe_function при создании.
Когда число потоков, использующих napi_threadsafe_function, достигает нуля, никакие новые потоки не могут начать использовать его с помощью вызова napi_acquire_threadsafe_function(). Фактически все последующие связанные с ним вызовы API, кроме napi_release_threadsafe_function(), будут возвращать значение ошибки napi_closing.
Потокобезопасную функцию можно «прервать», передав значение napi_tsfn_abort в napi_release_threadsafe_function(). В результате все последующие связанные с потокобезопасной функцией вызовы API, кроме napi_release_threadsafe_function(), будут возвращать napi_closing, даже если счетчик ссылок еще не достиг нуля. В частности, napi_call_threadsafe_function() вернет napi_closing, сообщая потокам, что асинхронные вызовы потокобезопасной функции больше невозможны. Это можно использовать как условие завершения потока. Получив значение возврата napi_closing от napi_call_threadsafe_function(), поток больше не должен использовать потокобезопасную функцию, поскольку больше нет гарантии, что для нее выделена память.
Определение необходимости поддерживать работу процесса
Как и дескрипторы libuv, потокобезопасные функции можно «привязать» и «отвязать». Привязанная потокобезопасная функция не позволит циклу событий в потоке, в котором она создана, завершиться до уничтожения этой функции. Напротив, отвязанная потокобезопасная функция не препятствует завершению цикла событий. Для этого предназначены API napi_ref_threadsafe_function и napi_unref_threadsafe_function.
Вызов napi_unref_threadsafe_function не помечает потокобезопасные функции как готовые к уничтожению, а вызов napi_ref_threadsafe_function не препятствует их уничтожению.
napi_create_threadsafe_function
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); copy -
[in] env: Среда, в которой вызывается API. -
[in] func: Необязательная функция JavaScript, вызываемая из другого потока. Ее необходимо передать, если вcall_js_cbпереданоNULL. -
[in] async_resource: Необъязательный объект, связанный с асинхронной работой, который будет передан возможнымasync_hooksinithooks. -
[in] async_resource_name: Строка JavaScript, задающая идентификатор типа ресурса, предоставляемого для диагностической информации, доступной через APIasync_hooks. -
[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 будет вызвана без параметров, а значениемthisбудетundefined. Подробнее см. в разделеnapi_threadsafe_function_call_js. -
[out] result: Асинхронная потокобезопасная функция JavaScript.
История изменений:
-
Версия 10 (
NAPI_VERSIONопределено как10или выше):Необработанные исключения, выброшенные в
call_js_cb, обрабатываются событием'uncaughtException', а не игнорируются.
napi_get_threadsafe_function_context
NAPI_EXTERN napi_status
napi_get_threadsafe_function_context(napi_threadsafe_function func,
void** result); copy -
[in] func: Потокобезопасная функция, контекст которой нужно получить. -
[out] result: Место для сохранения контекста.
Этот API можно вызывать из любого потока, использующего func.
napi_call_threadsafe_function
NAPI_EXTERN napi_status
napi_call_threadsafe_function(napi_threadsafe_function func,
void* data,
napi_threadsafe_function_call_mode is_blocking); copy -
[in] func: Асинхронная потокобезопасная функция JavaScript, которую нужно вызвать. -
[in] data: Данные, передаваемые в JavaScript через обратный вызовcall_js_cb, предоставленный при создании потокобезопасной функции JavaScript. -
[in] is_blocking: Флаг, который может иметь значениеnapi_tsfn_blocking, указывающее, что вызов должен блокироваться при заполненной очереди, илиnapi_tsfn_nonblocking, указывающее, что при заполненной очереди вызов должен немедленно вернуть статусnapi_queue_full.
Не следует вызывать этот API со значением napi_tsfn_blocking из потока JavaScript, поскольку при заполненной очереди это может привести к взаимной блокировке потока JavaScript.
Этот API вернет napi_closing, если из какого-либо потока был вызван napi_release_threadsafe_function() со значением napi_tsfn_abort для параметра abort. Значение добавляется в очередь, только если API возвращает napi_ok.
Этот API можно вызывать из любого потока, использующего func.
napi_acquire_threadsafe_function
NAPI_EXTERN napi_status napi_acquire_threadsafe_function(napi_threadsafe_function func); copy
-
[in] func: Асинхронная потокобезопасная функция JavaScript, использование которой нужно начать.
Поток должен вызвать этот API, прежде чем передавать func другим API потокобезопасных функций, чтобы сообщить, что он будет использовать func. Это не позволит уничтожить func, когда все остальные потоки перестанут ее использовать.
Этот API можно вызвать из любого потока, который начнет использовать func.
napi_release_threadsafe_function
NAPI_EXTERN napi_status
napi_release_threadsafe_function(napi_threadsafe_function func,
napi_threadsafe_function_release_mode mode); copy -
[in] func: Асинхронная потокобезопасная функция JavaScript, счетчик ссылок которой нужно уменьшить. -
[in] mode: Флаг, который может иметь значениеnapi_tsfn_release, указывающее, что текущий поток больше не будет вызывать потокобезопасную функцию, илиnapi_tsfn_abort, указывающее, что ни текущий, ни другие потоки больше не должны вызывать потокобезопасную функцию. Если задано значениеnapi_tsfn_abort, последующие вызовыnapi_call_threadsafe_function()будут возвращатьnapi_closing, и новые значения не будут помещаться в очередь.
Поток должен вызвать этот API, когда перестает использовать func. Передача func в любые API потокобезопасных функций после вызова этого API приведет к неопределенным результатам, поскольку func может быть уничтожена.
Этот API можно вызвать из любого потока, который перестает использовать func.
napi_ref_threadsafe_function
NAPI_EXTERN napi_status napi_ref_threadsafe_function(node_api_basic_env env, napi_threadsafe_function func); copy
-
[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
NAPI_EXTERN napi_status napi_unref_threadsafe_function(node_api_basic_env env, napi_threadsafe_function func); copy
-
[in] env: Среда, в которой вызывается API. -
[in] func: Потокобезопасная функция, которую нужно отвязать.
Этот API указывает, что цикл событий, выполняющийся в главном потоке, может завершиться до уничтожения func. Как и uv_unref, этот вызов идемпотентен.
Этот API можно вызывать только из главного потока.
Различные вспомогательные средства
node_api_get_module_file_name
NAPI_EXTERN napi_status node_api_get_module_file_name(node_api_basic_env env, const char** result); copy
-
[in] env: Среда, в которой вызывается API. -
[out] result: URL-адрес, содержащий абсолютный путь к расположению, из которого была загружена надстройка. Для файла в локальной файловой системе он будет начинаться сfile://. Строка заканчивается нулевым символом, принадлежитenvи поэтому не должна изменяться или освобождаться.
result может быть пустой строкой, если в процессе загрузки не удалось определить имя файла надстройки.
© Joyent, Inc. and other Node contributors
Licensed under the MIT License.
Node.js is a trademark of Joyent, Inc. and is used with its permission.
We are not endorsed by or affiliated with Joyent.
https://nodejs.org/dist/latest-v24.x/docs/api/n-api.html
