Node-API

Node-API (ранее N-API) — это API для создания нативных аддонов. Он не зависит от используемой среды выполнения JavaScript (например, V8) и поддерживается в составе самого Node.js. Этот API будет стабилен на уровне ABI во всех версиях Node.js. Он предназначен для защиты аддонов от изменений в базовом движке JavaScript и позволяет модулям, скомпилированным для одной основной версии, работать в более поздних основных версиях Node.js без повторной компиляции. В руководстве Стабильность ABI приводится более подробное объяснение.

Аддоны создаются и упаковываются с помощью того же подхода и тех же инструментов, которые описаны в разделе Аддоны на C++. Отличается только набор API, используемых нативным кодом. Вместо API V8 или нативных абстракций для 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, будут зависеть от символов функций Node-API на основе C, экспортируемых Node.js. Следующий фрагмент кода — пример node-addon-api:

Object obj = Object::New(env);
obj["foo"] = String::New(env, "bar");
cppcopy

Приведённый выше код на 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;
}
cppcopy

В результате аддон использует только экспортируемые 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>
  cppcopy

• API libuv, которые также входят в состав Node.js и доступны через

  #include <uv.h>
  cppcopy

• API V8, доступный через

  #include <v8.h>
  cppcopy

Таким образом, чтобы аддон оставался ABI-совместимым в разных основных версиях Node.js, он должен использовать исключительно Node-API и ограничиваться использованием

#include <node_api.h>
ccopy

а также проверять, что для всех используемых им внешних библиотек гарантируется стабильность ABI, аналогичная гарантии Node-API.

Значения перечислений при стабильности ABI

Все типы перечислений, определённые в Node-API, следует считать значениями фиксированного размера int32_t. Типы перечислений с битовыми флагами должны быть явно задокументированы; они работают с побитовыми операторами, например побитовым ИЛИ (|), как значения битов. Если не указано иное, тип перечисления следует считать расширяемым.

Новое значение перечисления будет добавляться в конец его определения. Значения перечислений не будут удаляться или переименовываться.

Для типа перечисления, возвращаемого функцией Node-API или передаваемого в качестве выходного параметра функции Node-API, значение является целым числом, и аддон должен обрабатывать неизвестные значения. Новые значения могут добавляться без проверки версии. Например, при проверке napi_status в операторах switch аддон должен включать ветвь по умолчанию, поскольку в новых версиях 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
bashcopy

Разработчикам для Windows все необходимые инструменты компилятора предоставляет Visual Studio. Однако устанавливать всю среду разработки Visual Studio не требуется. Следующая команда устанавливает необходимую цепочку инструментов:

npm install --global windows-build-tools
bashcopy

В следующих разделах описаны дополнительные инструменты для разработки и развёртывания нативных аддонов 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. Преимущество prebuildify заключается в том, что собранные бинарные файлы включаются в нативный аддон при его загрузке в npm. Бинарные файлы скачиваются из npm и сразу становятся доступны пользователю модуля при установке нативного аддона.

Использование

Чтобы использовать функции Node-API, включите файл node_api.h, расположенный в каталоге src дерева исходного кода Node.js:

#include <node_api.h>
ccopy

Это позволит использовать версию NAPI_VERSION по умолчанию для данного выпуска Node.js. Чтобы обеспечить совместимость с конкретными версиями Node-API, версию можно явно указать при включении заголовочного файла:

#define NAPI_VERSION 3
#include <node_api.h>
ccopy

Это ограничивает набор Node-API только функциональностью, доступной в указанной версии и более ранних версиях.

Некоторые компоненты Node-API являются экспериментальными и требуют явного разрешения на использование:

#define NAPI_EXPERIMENTAL
#include <node_api.h>
ccopy

В этом случае коду модуля будет доступен весь набор API, включая экспериментальные API.

Иногда добавляются экспериментальные функции, влияющие на уже выпущенные стабильные API. Такие функции можно отключить, отказавшись от их использования:

#define NAPI_EXPERIMENTAL
#define NODE_API_EXPERIMENTAL_<FEATURE_NAME>_OPT_OUT
#include <node_api.h>
ccopy

где <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 имел экспериментальный статус.

** В 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. Он создаёт экземпляр аддона, вызывая addon.c, когда аддон загружается в среду Node.js.

// addon.h
#ifndef _ADDON_H_
#define _ADDON_H_
#include <js_native_api.h>
napi_value create_addon(napi_env env);
#endif  // _ADDON_H_
ccopy

// 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;
}
ccopy

// 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);
}
ccopy

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);
ccopy

• [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);
ccopy

• [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;
ccopy

Если после возврата 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;
ccopy

• 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). Существует подмножество Node-API, принимающих параметр типа node_api_basic_env в качестве первого аргумента. Эти API не обращаются к состоянию движка JavaScript, поэтому их безопасно вызывать из синхронных финализаторов. Передавать в эти API параметр типа napi_env разрешено, однако передавать параметр типа 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;
ccopy

napi_threadsafe_function_call_mode

Значение, передаваемое в napi_call_threadsafe_function(), указывает, должен ли вызов блокироваться, если очередь, связанная с потокобезопасной функцией, заполнена.

typedef enum {
  napi_tsfn_nonblocking,
  napi_tsfn_blocking
} napi_threadsafe_function_call_mode;
ccopy

Типы управления памятью 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;
ccopy

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);
ccopy

За исключением случаев, описанных в разделе Управление временем жизни объектов, создавать область дескрипторов и/или область обратного вызова внутри 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);
ccopy

За исключением случаев, описанных в разделе Управление временем жизни объектов, создавать дескриптор и/или область обратного вызова внутри тела функции не требуется.

Поскольку эти функции могут вызываться, когда движок JavaScript находится в состоянии, в котором он не может выполнять код JavaScript, можно вызывать только функции 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

Тип указателя на функцию, предоставляемую дополнением, который позволяет пользователю запланировать группу вызовов Node-API в ответ на событие сборки мусора после завершения цикла сборки мусора. Эти указатели на функции можно использовать с node_api_post_finalizer.

typedef void (*napi_finalize)(napi_env env,
                              void* finalize_data,
                              void* finalize_hint);
ccopy

История изменений:

• экспериментальная функция (определена 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);
ccopy

Реализации этой функции должны избегать вызовов 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);
ccopy

За исключением случаев, описанных в разделе Управление временем жизни объектов, создавать дескриптор и/или область обратного вызова внутри тела функции не требуется.

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);
ccopy

• [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);
ccopy

• [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);
ccopy

• [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;
};
ccopy

• 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);
ccopy

• [in] env: среда, в которой вызывается API.
• [out] result: структура napi_extended_error_info с дополнительными сведениями об ошибке.

Возвращает napi_ok, если вызов API выполнен успешно.

Этот API получает структуру napi_extended_error_info со сведениями о последней произошедшей ошибке.

Содержимое возвращённой структуры napi_extended_error_info действительно только до следующего вызова функции Node-API для того же env. Это относится и к вызову napi_is_exception_pending, поэтому часто может потребоваться скопировать сведения, чтобы использовать их позднее. Указатель, возвращённый в error_message, указывает на статически определённую строку, поэтому этот указатель безопасно использовать, если скопировать его из поля error_message (которое будет перезаписано) до вызова другой функции Node-API.

Не полагайтесь на содержимое или формат каких-либо дополнительных сведений: на них не распространяется 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_pending_exception в виде napi_status. Однако это происходит не со всеми функциями. 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]
textcopy

где originalName — исходное имя, связанное с ошибкой, а code — указанный код. Например, если код — 'ERR_ERROR_1' и создаётся TypeError, имя будет таким:

TypeError [ERR_ERROR_1]
textcopy

napi_throw

NAPI_EXTERN napi_status napi_throw(napi_env env, napi_value error);
ccopy

• [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);
ccopy

• [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);
ccopy

• [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);
ccopy

• [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);
ccopy

• [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);
ccopy

• [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);
ccopy

• [in] env: среда, в которой вызывается API.
• [in] code: необязательный napi_value со строкой кода ошибки, который будет связан с ошибкой.
• [in] msg: napi_value, ссылающийся на объект JavaScript string, который будет использоваться в качестве сообщения для 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);
ccopy

• [in] env: среда, в которой вызывается API.
• [in] code: необязательный napi_value со строкой кода ошибки, который будет связан с ошибкой.
• [in] msg: napi_value, ссылающийся на объект JavaScript string, который будет использоваться в качестве сообщения для 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);
ccopy

• [in] env: среда, в которой вызывается API.
• [in] code: необязательный napi_value со строкой кода ошибки, который будет связан с ошибкой.
• [in] msg: napi_value, ссылающийся на объект JavaScript string, который будет использоваться в качестве сообщения для 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);
ccopy

• [in] env: среда, в которой вызывается API.
• [in] code: необязательный napi_value со строкой кода ошибки, который будет связан с ошибкой.
• [in] msg: napi_value, ссылающийся на объект JavaScript string, который будет использоваться в качестве сообщения для 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);
ccopy

• [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);
ccopy

• [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);
ccopy

• [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);
ccopy

• [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
}
ccopy

В результате будет создано большое количество дескрипторов, что потребует значительных ресурсов. Кроме того, хотя нативный код может использовать только последний дескриптор, все связанные объекты также будут оставаться живыми, поскольку у них одна и та же область.

Для решения этой задачи 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;
  }
}
ccopy

При вложении областей в некоторых случаях дескриптор из внутренней области должен оставаться действительным дольше, чем эта область. Для этого 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);
ccopy

• [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);
ccopy

• [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);
ccopy

• [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);
ccopy

• [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);
ccopy

• [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 позволяет создавать ссылки только на ограниченный набор типов значений, включая объекты, внешние значения, функции и символы.

С каждой ссылкой связано счетчиковое значение 0 или больше, которое определяет, будет ли ссылка удерживать соответствующее значение в памяти. Ссылки со счетчиком 0 не препятствуют сборке соответствующих значений. Значения типов object (объект, функция, внешнее значение) и 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);
ccopy

• [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);
ccopy

• [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);
ccopy

• [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);
ccopy

• [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);
ccopy

• [in] env: среда, в которой вызывается API.
• [in] ref: napi_ref, для которой запрашивается соответствующее значение.
• [out] result: napi_value, на которое ссылается napi_ref.

Возвращает napi_ok, если вызов API выполнен успешно.

Если значение еще действительно, этот API возвращает napi_value, представляющий значение JavaScript, связанное с napi_ref. В противном случае результатом будет 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);
ccopy

Регистрирует 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);
ccopy

Отменяет регистрацию 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);
ccopy

• [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);
ccopy

• [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)
ccopy

Следующее отличие — сигнатура метода Init. Для модуля Node-API она выглядит так:

napi_value Init(napi_env env, napi_value exports);
ccopy

Возвращаемое значение 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;
}
ccopy

Чтобы указать функцию, возвращаемую методом 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;
}
ccopy

Чтобы определить класс, экземпляры которого можно создавать (часто используется вместе с оберткой объекта):

// 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;
}
ccopy

Можно также использовать макрос 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;
}
ccopy

Параметры env и exports доступны в теле макроса NAPI_MODULE_INIT.

Все дополнения Node-API учитывают контекст, то есть их можно загружать несколько раз. При объявлении такого модуля следует учитывать несколько аспектов проектирования. Дополнительные сведения см. в документации о дополнениях с поддержкой контекста.

Переменные env и exports будут доступны внутри тела функции после вызова макроса.

Дополнительные сведения о настройке свойств объектов см. в разделе Работа со свойствами JavaScript.

Дополнительные сведения о создании модулей дополнений в целом см. в существующей документации API.

Работа со значениями JavaScript

Node-API предоставляет набор API для создания всех типов значений JavaScript. Некоторые из этих типов описаны в разделе «Типы языка» спецификации языка ECMAScript.

В основном эти API используются для выполнения следующих задач:

1. Создание объекта JavaScript
2. Преобразование примитивного типа C в значение Node-API
3. Преобразование значения Node-API в примитивный тип C
4. Получение глобальных экземпляров, включая 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;
ccopy

Описывает перечисления фильтров 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;
ccopy

Битовая маска фильтра свойств. С помощью побитовых операторов из нее можно составлять комбинированный фильтр.

napi_key_conversion

typedef enum {
  napi_key_keep_numbers,
  napi_key_numbers_to_strings
} napi_key_conversion;
ccopy

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;
ccopy

Описывает тип 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;
ccopy

Представляет базовый скалярный двоичный тип данных TypedArray. Элементы этого перечисления соответствуют разделу «Объекты TypedArray» спецификации языка ECMAScript.

Функции создания объектов

napi_create_array

napi_status napi_create_array(napi_env env, napi_value* result)
ccopy

• [in] env: среда, в которой вызывается Node-API.
• [out] result: napi_value, представляющий JavaScript-Array.

Возвращает 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)
ccopy

• [in] env: среда, в которой вызывается API.
• [in] length: начальная длина Array.
• [out] result: napi_value, представляющий JavaScript-Array.

Возвращает 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)
ccopy

• [in] env: среда, в которой вызывается API.
• [in] length: длина создаваемого буфера массива в байтах.
• [out] data: указатель на базовый байтовый буфер ArrayBuffer. Параметр data можно не использовать, передав NULL.
• [out] result: napi_value, представляющий JavaScript-ArrayBuffer.

Возвращает 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)
ccopy

• [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)
ccopy

• [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);
ccopy

• [in] env: среда, в которой вызывается API.
• [in] time: значение времени ECMAScript в миллисекундах с 1 января 1970 года по UTC.
• [out] result: napi_value, представляющий JavaScript-Date.

Возвращает 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)
ccopy

• [in] env: среда, в которой вызывается API.
• [in] data: указатель на внешние данные.
• [in] finalize_cb: необязательный обратный вызов, вызываемый при сборке внешнего значения. Дополнительные сведения см. в разделе napi_finalize.
• [in] finalize_hint: необязательная подсказка, передаваемая обратному вызову финализации при сборке.
• [out] result: napi_value, представляющий внешнее значение.

Возвращает napi_ok, если вызов API выполнен успешно.

Этот API выделяет значение JavaScript, связанное с внешними данными. Оно используется для передачи внешних данных через код JavaScript, чтобы позднее нативный код мог получить их с помощью napi_get_value_external.

API добавляет обратный вызов 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)
ccopy

• [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, представляющий JavaScript ArrayBuffer.

Возвращает napi_ok, если API выполнен успешно.

В некоторых средах выполнения, отличных от Node.js, прекращена поддержка внешних буферов. В средах выполнения, отличных от 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 ArrayBuffers описаны в разделе «Объекты ArrayBuffer» Спецификации языка ECMAScript.

node_api_create_external_sharedarraybuffer

napi_status
node_api_create_external_sharedarraybuffer(napi_env env,
                                           void* external_data,
                                           size_t byte_length,
                                           node_api_noenv_finalize finalize_cb,
                                           void* finalize_hint,
                                           napi_value* result)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] external_data: Указатель на базовый байтовый буфер SharedArrayBuffer.
• [in] byte_length: Длина базового буфера в байтах.
• [in] finalize_cb: Необязательный callback, вызываемый при сборке мусора для SharedArrayBuffer. Вызывается в произвольном потоке. Поскольку SharedArrayBuffer может существовать дольше среды, в которой он создан, callback не получает ссылку на env.
• [in] finalize_hint: Необязательная подсказка, передаваемая callback-функции финализации во время сборки мусора.
• [out] result: napi_value, представляющий JavaScript SharedArrayBuffer.

Возвращает napi_ok, если API выполнен успешно.

Создает SharedArrayBuffer с памятью, управляемой извне.

Сведения о совместимости со средами выполнения см. в описании napi_create_external_arraybuffer.

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)
ccopy

• [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, прекращена поддержка внешних буферов. В средах выполнения, отличных от 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)
ccopy

• [in] env: Среда, в которой вызывается API.
• [out] result: napi_value, представляющий JavaScript Object.

Возвращает 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)
cppcopy

• [in] env: Среда, в которой вызывается API.
• [in] prototype_or_null: Объект-прототип нового объекта. Может быть napi_value, представляющим объект JavaScript, используемый в качестве прототипа, napi_value, представляющим JavaScript null, или nullptr, который будет преобразован в null.
• [in] property_names: Массив napi_value, представляющих имена свойств.
• [in] property_values: Массив napi_value, представляющих значения свойств.
• [in] property_count: Количество свойств в массивах.
• [out] result: napi_value, представляющий JavaScript Object.

Возвращает 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)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] description: Необязательный napi_value, ссылающийся на JavaScript string, который будет задан в качестве описания символа.
• [out] result: napi_value, представляющий JavaScript symbol.

Возвращает 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)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] utf8description: Строка C в кодировке UTF-8, представляющая текст, который будет использоваться в качестве описания символа.
• [in] length: Длина строки описания в байтах или NAPI_AUTO_LENGTH, если она завершается нулевым символом.
• [out] result: napi_value, представляющий JavaScript symbol.

Возвращает 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)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] type: Скалярный тип данных элементов TypedArray.
• [in] length: Количество элементов в TypedArray.
• [in] arraybuffer: ArrayBuffer или SharedArrayBuffer, лежащий в основе типизированного массива.
• [in] byte_offset: Смещение в байтах внутри ArrayBuffer или SharedArrayBuffer, с которого начинается представление TypedArray.
• [out] result: napi_value, представляющий JavaScript TypedArray.

Возвращает napi_ok, если API выполнен успешно.

Этот API создает объект JavaScript TypedArray на основе существующего ArrayBuffer или SharedArrayBuffer. Объекты TypedArray предоставляют представление базового буфера данных в виде массива, где все элементы имеют один и тот же базовый скалярный двоичный тип данных.

Значение (length * size_of_element) + byte_offset должно быть меньше или равно размеру в байтах переданного ArrayBuffer или SharedArrayBuffer. В противном случае возникает исключение RangeError.

Для размеров элементов больше 1 значение 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)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] arraybuffer: ArrayBuffer, из которого будет создан буфер.
• [in] byte_offset: Смещение в байтах внутри ArrayBuffer, с которого начинается создание буфера.
• [in] byte_length: Длина создаваемого из ArrayBuffer буфера в байтах.
• [out] result: napi_value, представляющий созданный объект JavaScript Buffer.

Возвращает 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)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] length: Количество элементов в DataView.
• [in] arraybuffer: ArrayBuffer или SharedArrayBuffer, лежащий в основе DataView.
• [in] byte_offset: Смещение в байтах внутри ArrayBuffer, с которого начинается представление DataView.
• [out] result: napi_value, представляющий JavaScript DataView.

Возвращает 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)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] value: Целочисленное значение, которое будет представлено в JavaScript.
• [out] result: napi_value, представляющий JavaScript number.

Возвращает 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)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] value: Беззнаковое целочисленное значение, которое будет представлено в JavaScript.
• [out] result: napi_value, представляющий JavaScript number.

Возвращает 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)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] value: Целочисленное значение, которое будет представлено в JavaScript.
• [out] result: napi_value, представляющий JavaScript number.

Возвращает 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)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] value: Значение двойной точности, которое будет представлено в JavaScript.
• [out] result: napi_value, представляющий JavaScript number.

Возвращает 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);
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] value: Целочисленное значение, которое будет представлено в JavaScript.
• [out] result: napi_value, представляющий JavaScript BigInt.

Возвращает 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);
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] value: Беззнаковое целочисленное значение, которое будет представлено в JavaScript.
• [out] result: napi_value, представляющий JavaScript BigInt.

Возвращает 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);
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] sign_bit: Определяет, будет ли результирующее значение BigInt положительным или отрицательным.
• [in] word_count: Длина массива words.
• [in] words: Массив 64-битных слов uint64_t в порядке от младшего к старшему.
• [out] result: napi_value, представляющий JavaScript BigInt.

Возвращает napi_ok, если API выполнен успешно.

Этот API преобразует массив беззнаковых 64-битных слов в одно значение BigInt.

Результирующее значение BigInt вычисляется по формуле: (–1)^sign_bit (words[0] × (2⁶⁴)⁰ + words[1] × (2⁶⁴)¹ + …)

napi_create_string_latin1

napi_status napi_create_string_latin1(napi_env env,
                                      const char* str,
                                      size_t length,
                                      napi_value* result);
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] str: Буфер символов, представляющий строку в кодировке ISO-8859-1.
• [in] length: Длина строки в байтах или NAPI_AUTO_LENGTH, если она завершается нулевым символом.
• [out] result: napi_value, представляющий JavaScript string.

Возвращает 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);
ccopy

• [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: Необязательная подсказка, передаваемая callback-функции финализации во время сборки мусора.
• [out] result: napi_value, представляющий JavaScript string.
• [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)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] str: Буфер символов, представляющий строку в кодировке UTF-16 LE.
• [in] length: Длина строки в двухбайтовых кодовых единицах или NAPI_AUTO_LENGTH, если она завершается нулевым символом.
• [out] result: napi_value, представляющий JavaScript string.

Возвращает napi_ok, если API выполнен успешно.

Этот API создает значение JavaScript string из строки C в кодировке UTF-16 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);
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] str: Буфер символов, представляющий строку в кодировке UTF-16 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: Необязательная подсказка, передаваемая callback-функции финализации во время сборки мусора.
• [out] result: napi_value, представляющий JavaScript string.
• [out] copied: Была ли строка скопирована. Если да, финализатор уже был вызван для уничтожения str.

Возвращает napi_ok, если API выполнен успешно.

Этот API создает значение JavaScript string из строки C в кодировке UTF-16 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)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] str: Буфер символов, представляющий строку в кодировке UTF-8.
• [in] length: Длина строки в байтах или NAPI_AUTO_LENGTH, если она завершается нулевым символом.
• [out] result: napi_value, представляющий JavaScript string.

Возвращает napi_ok, если API выполнен успешно.

Этот API создает значение JavaScript string из строки C в кодировке UTF-8. Исходная строка копируется.

Тип 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);
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] str: Символьный буфер, представляющий строку в кодировке ISO-8859-1.
• [in] length: Длина строки в байтах или NAPI_AUTO_LENGTH, если строка завершается нулевым символом.
• [out] result: napi_value, представляющий оптимизированное значение JavaScript string, которое будет использоваться в качестве ключа свойства объекта.

Возвращает 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);
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] str: Символьный буфер, представляющий строку в кодировке UTF16-LE.
• [in] length: Длина строки в двухбайтовых кодовых единицах или NAPI_AUTO_LENGTH, если строка завершается нулевым символом.
• [out] result: napi_value, представляющий оптимизированное значение JavaScript string, которое будет использоваться в качестве ключа свойства объекта.

Возвращает 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);
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] str: Символьный буфер, представляющий строку в кодировке UTF8.
• [in] length: Длина строки в двухбайтовых кодовых единицах или NAPI_AUTO_LENGTH, если строка завершается нулевым символом.
• [out] result: napi_value, представляющий оптимизированное значение JavaScript string, которое будет использоваться в качестве ключа свойства объекта.

Возвращает 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)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] value: napi_value, представляющий массив JavaScript Array, длина которого запрашивается.
• [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)
ccopy

• [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)
ccopy

• [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)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] object: napi_value, представляющий объект JavaScript Object, прототип которого нужно вернуть. Возвращается эквивалент 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)
ccopy

• [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 или SharedArrayBuffer, лежащий в основе 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)
ccopy

• [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)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] value: napi_value, представляющий объект JavaScript Date.
• [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)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] value: napi_value, представляющий JavaScript Boolean.
• [out] result: Примитив C типа boolean, эквивалентный заданному JavaScript Boolean.

Возвращает 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)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] value: napi_value, представляющий JavaScript number.
• [out] result: Примитив C типа double, эквивалентный заданному JavaScript number.

Возвращает 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);
ccopy

• [in] env: Среда, в которой вызывается API
• [in] value: napi_value, представляющий JavaScript BigInt.
• [out] result: Примитив C int64_t, эквивалентный заданному JavaScript BigInt.
• [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);
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] value: napi_value, представляющий JavaScript BigInt.
• [out] result: Примитив C uint64_t, эквивалентный заданному JavaScript BigInt.
• [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);
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] value: napi_value, представляющий JavaScript BigInt.
• [out] sign_bit: Целое число, указывающее, является ли JavaScript BigInt положительным или отрицательным.
• [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)
ccopy

• [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)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] value: napi_value, представляющий JavaScript number.
• [out] result: Примитив C int32, эквивалентный заданному JavaScript number.

Возвращает napi_ok, если API выполнен успешно. Если передан объект, не являющийся числом napi_value, возвращается napi_number_expected.

Этот API возвращает примитив C int32, эквивалентный заданному JavaScript number.

Если число выходит за пределы диапазона 32-битного целого числа, результат усекается до значения, эквивалентного младшим 32 битам. В результате большое положительное число может стать отрицательным, если значение > 2³¹ - 1.

Для не конечных числовых значений (NaN, +Infinity или -Infinity) результат устанавливается в ноль.

napi_get_value_int64

napi_status napi_get_value_int64(napi_env env,
                                 napi_value value,
                                 int64_t* result)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] value: napi_value, представляющий JavaScript number.
• [out] result: Примитив C int64, эквивалентный заданному JavaScript number.

Возвращает 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)
ccopy

• [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)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] value: napi_value, представляющий строку JavaScript.
• [in] buf: Буфер для записи строки в кодировке UTF8. Если передано NULL, длина строки в байтах без завершающего нулевого символа возвращается в result.
• [in] bufsize: Размер целевого буфера. Если этого значения недостаточно, возвращаемая строка усекается и завершается нулевым символом. Если это значение равно нулю, строка не возвращается и буфер не изменяется.
• [out] result: Количество байтов, скопированных в буфер, без завершающего нулевого символа.

Возвращает napi_ok, если API выполнен успешно. Если передан string napi_value, не являющийся строкой, возвращается napi_string_expected.

Этот API возвращает строку в кодировке UTF8, соответствующую переданному значению.

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)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] value: napi_value, представляющий строку JavaScript.
• [in] buf: Буфер для записи строки в кодировке UTF16-LE. Если передано NULL, длина строки в двухбайтовых кодовых единицах без завершающего нулевого символа возвращается.
• [in] bufsize: Размер целевого буфера. Если этого значения недостаточно, возвращаемая строка усекается и завершается нулевым символом. Если это значение равно нулю, строка не возвращается и буфер не изменяется.
• [out] result: Количество двухбайтовых кодовых единиц, скопированных в буфер, без завершающего нулевого символа.

Возвращает napi_ok, если API выполнен успешно. Если передан string napi_value, не являющийся строкой, возвращается napi_string_expected.

Этот API возвращает строку в кодировке UTF16, соответствующую переданному значению.

napi_get_value_uint32

napi_status napi_get_value_uint32(napi_env env,
                                  napi_value value,
                                  uint32_t* result)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] value: napi_value, представляющий JavaScript number.
• [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)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] value: Значение логического типа, которое нужно получить.
• [out] result: napi_value, представляющий экземпляр-одиночку JavaScript Boolean, который нужно получить.

Возвращает napi_ok, если API выполнен успешно.

Этот API используется для возврата объекта-экземпляра-одиночки JavaScript, представляющего заданное логическое значение.

napi_get_global

napi_status napi_get_global(napi_env env, napi_value* result)
ccopy

• [in] env: Среда, в которой вызывается API.
• [out] result: napi_value, представляющий объект JavaScript global.

Возвращает napi_ok, если API выполнен успешно.

Этот API возвращает объект global.

napi_get_null

napi_status napi_get_null(napi_env env, napi_value* result)
ccopy

• [in] env: Среда, в которой вызывается API.
• [out] result: napi_value, представляющий объект JavaScript null.

Возвращает napi_ok, если API выполнен успешно.

Этот API возвращает объект null.

napi_get_undefined

napi_status napi_get_undefined(napi_env env, napi_value* result)
ccopy

• [in] env: Среда, в которой вызывается API.
• [out] result: napi_value, представляющий значение JavaScript Undefined.

Возвращает napi_ok, если API выполнен успешно.

Этот API возвращает объект Undefined.

Работа со значениями JavaScript и абстрактными операциями

Node-API предоставляет набор API для выполнения некоторых абстрактных операций над значениями JavaScript.

Эти API позволяют выполнять следующие действия:

1. Преобразовывать значения JavaScript в определенные типы JavaScript (например, number или string).
2. Проверять тип значения JavaScript.
3. Проверять равенство двух значений JavaScript.

napi_coerce_to_bool

napi_status napi_coerce_to_bool(napi_env env,
                                napi_value value,
                                napi_value* result)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] value: Значение JavaScript, которое нужно привести к другому типу.
• [out] result: napi_value, представляющий приведенное значение JavaScript Boolean.

Возвращает 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)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] value: Значение JavaScript, которое нужно привести к другому типу.
• [out] result: napi_value, представляющий приведенное значение JavaScript number.

Возвращает 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)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] value: Значение JavaScript, которое нужно привести к другому типу.
• [out] result: napi_value, представляющий приведенное значение JavaScript Object.

Возвращает 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)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] value: Значение JavaScript для приведения.
• [out] result: napi_value, представляющий приведённое значение JavaScript string.

Возвращает napi_ok, если API выполнен успешно.

Этот API реализует абстрактную операцию ToString(), определённую в разделе ToString спецификации языка ECMAScript. Эта функция может выполнять код JS, если переданное значение является объектом.

napi_typeof

napi_status napi_typeof(napi_env env, napi_value value, napi_valuetype* result)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] value: Значение JavaScript, тип которого нужно определить.
• [out] result: Тип значения JavaScript.

Возвращает napi_ok, если API выполнен успешно.

• napi_invalid_arg, если тип value не является известным типом ECMAScript и value не является значением External.

Этот API реализует поведение, аналогичное вызову оператора typeof для объекта, как определено в разделе «Оператор typeof» спецификации языка ECMAScript. Однако есть некоторые отличия:

1. Поддерживается обнаружение значения External.
2. Значение null определяется как отдельный тип, тогда как оператор ECMAScript typeof определил бы его как object.

Если тип value недопустим, возвращается ошибка.

napi_instanceof

napi_status napi_instanceof(napi_env env,
                            napi_value object,
                            napi_value constructor,
                            bool* result)
ccopy

• [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)
ccopy

• [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)
ccopy

• [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)
ccopy

• [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)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] value: Проверяемое значение JavaScript.
• [out] result: Представляет ли заданный napi_value объект JavaScript Date.

Возвращает napi_ok, если API выполнен успешно.

Этот API проверяет, является ли переданный Object датой.

napi_is_error

napi_status napi_is_error(napi_env env, napi_value value, bool* result)
ccopy

• [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)
ccopy

• [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)
ccopy

• [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)
ccopy

• [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)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] arraybuffer: Отключаемый объект JavaScript ArrayBuffer.

Возвращает 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)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] arraybuffer: Проверяемый объект JavaScript ArrayBuffer.
• [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)
ccopy

• [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)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] byte_length: Длина создаваемого совместно используемого буфера массива в байтах.
• [out] data: Указатель на базовый байтовый буфер объекта SharedArrayBuffer. Параметр data можно не использовать, передав NULL.
• [out] result: napi_value, представляющий объект JavaScript SharedArrayBuffer.

Возвращает 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;
jscopy

Эквивалентный код с использованием значений 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;
ccopy

Индексированные свойства можно устанавливать аналогичным образом. Рассмотрим следующий фрагмент кода JavaScript:

const arr = [];
arr[123] = 'hello';
jscopy

Эквивалентный код с использованием значений 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;
ccopy

Свойства можно получать с помощью API, описанных в этом разделе. Рассмотрим следующий фрагмент кода JavaScript:

const arr = [];
const value = arr[123];
jscopy

Ниже приведён приблизительный эквивалент на 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;
ccopy

Наконец, для повышения производительности объекту можно определить сразу несколько свойств. Рассмотрим следующий код JavaScript:

const obj = {};
Object.defineProperties(obj, {
  'foo': { value: 123, writable: true, configurable: true, enumerable: true },
  'bar': { value: 456, writable: true, configurable: true, enumerable: true },
});
jscopy

Ниже приведён приблизительный эквивалент на 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;
ccopy

Структуры

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;
ccopy

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;
ccopy

• 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);
ccopy

• [in] env: Среда, в которой вызывается вызов Node-API.
• [in] object: Объект, свойства которого нужно получить.
• [out] result: napi_value, представляющий массив значений JavaScript с именами свойств объекта. Для перебора элементов 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);
ccopy

• [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);
ccopy

• [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);
ccopy

• [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);
ccopy

• [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);
ccopy

• [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);
ccopy

• [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);
ccopy

• [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);
ccopy

• [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);
ccopy

• [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);
ccopy

• [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);
ccopy

• [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);
ccopy

• [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);
ccopy

• [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);
ccopy

• [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);
ccopy

• [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);
ccopy

• [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);
ccopy

• [in] env: среда, в которой выполняется вызов Node-API.
• [in] object: объект, которому нужно задать прототип.
• [in] value: значение прототипа.

Возвращает napi_ok в случае успешного выполнения API.

Этот API задаёт прототип переданного Object.

Работа с функциями JavaScript

Node-API предоставляет набор API, позволяющих коду JavaScript вызывать собственный код. API 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);
ccopy

• [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;
jscopy

Затем указанную выше функцию можно вызвать из собственного дополнения с помощью следующего кода:

// 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;
ccopy

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);
ccopy

• [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)
ccopy

С указанным выше кодом дополнение можно использовать из JavaScript следующим образом:

const myaddon = require('./addon');
myaddon.sayHello();
jscopy

Строка, переданная в require(), — это имя цели в binding.gyp, отвечающей за создание файла .node.

Любые данные, не являющиеся NULL, переданные этому API через параметр data, можно связать с результирующей функцией JavaScript (возвращаемой в параметре result) и освободить при сборке мусора для функции, передав и функцию JavaScript, и данные в napi_add_finalizer.

Функции JavaScript Function описаны в разделе «Объекты-функции» спецификации языка 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)
ccopy

• [in] env: среда, в которой вызывается API.
• [in] cbinfo: информация о вызове, переданная функции обратного вызова.
• [in-out] argc: задаёт длину предоставленного массива argv и получает фактическое количество аргументов. Параметр argc можно не использовать, передав NULL.
• [out] argv: массив C из napi_value, в который будут скопированы аргументы. Если аргументов больше, чем указано в счётчике, копируется только запрошенное количество. Если передано меньше аргументов, чем заявлено, оставшаяся часть argv заполняется значениями napi_value, обозначающими undefined. Параметр argv можно не использовать, передав NULL.
• [out] thisArg: получает аргумент JavaScript this для вызова. Параметр 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)
ccopy

• [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)
ccopy

• [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);
jscopy

Следующее поведение можно приблизительно реализовать в 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);
ccopy

Возвращает napi_ok в случае успешного выполнения API.

Обёртывание объектов

Node-API позволяет «оборачивать» классы и экземпляры C++, чтобы конструктор класса и его методы можно было вызывать из JavaScript.

1. API napi_define_class определяет класс JavaScript с конструктором, статическими свойствами и методами, а также свойствами и методами экземпляра, соответствующими классу C++.
2. Когда код JavaScript вызывает конструктор, функция обратного вызова конструктора использует napi_wrap, чтобы обернуть новый экземпляр C++ в объект JavaScript, а затем возвращает объект-обёртку.
3. Когда код 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...
}
ccopy

Ссылку необходимо освободить, когда она больше не нужна.

В некоторых случаях 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
}
jscopy

В приведённом выше примере myAddon.queryHasRecords() — это метод, принимающий два аргумента. Первый — дескриптор базы данных, второй — дескриптор запроса. Метод извлекает обёрнутое значение первого аргумента и приводит полученный указатель к типу дескриптора базы данных. Затем он извлекает обёрнутое значение второго аргумента и приводит полученный указатель к типу дескриптора запроса. Если аргументы переданы в неправильном порядке, приведение типов всё равно выполнится, однако базовая операция с базой данных, скорее всего, завершится ошибкой или даже приведёт к недопустимому доступу к памяти.

Чтобы убедиться, что указатель, полученный из первого аргумента, действительно указывает на дескриптор базы данных, а указатель, полученный из второго аргумента, — на дескриптор запроса, реализация queryHasRecords() должна выполнять проверку типа. Сохранение конструкторов JavaScript-классов, из которых были созданы дескрипторы базы данных и запроса, в napi_ref может помочь, поскольку napi_instanceof() можно использовать для проверки того, что экземпляры, переданные в queryHashRecords(), действительно имеют правильный тип.

К сожалению, napi_instanceof() не защищает от манипуляций с прототипами. Например, прототип экземпляра дескриптора базы данных можно задать равным прототипу конструктора экземпляров дескриптора запроса. В этом случае экземпляр дескриптора базы данных может выглядеть как экземпляр дескриптора запроса и пройти проверку napi_instanceof() для экземпляра дескриптора запроса, сохраняя при этом указатель на дескриптор базы данных.

Для решения этой проблемы Node-API предоставляет возможность помечать типы.

Тег типа — это 128-битное целое число, уникальное для дополнения. Node-API предоставляет структуру napi_type_tag для хранения тега типа. Если такое значение передать вместе с объектом JavaScript или внешним объектом, сохранённым в napi_value, в napi_type_tag_object(), объект JavaScript будет «помечен» тегом типа. Эта «метка» невидима со стороны JavaScript. Когда объект JavaScript попадает в собственную привязку, napi_check_object_type_tag() можно использовать вместе с исходным тегом типа, чтобы определить, был ли этот объект JavaScript ранее «помечен» данным тегом. Это обеспечивает более надёжную проверку типа, чем napi_instanceof(), поскольку такая проверка сохраняет работоспособность после манипуляций с прототипами и выгрузки или повторной загрузки дополнения.

Продолжая предыдущий пример, следующий каркас реализации дополнения иллюстрирует использование napi_type_tag_object() и napi_check_object_type_tag().

// 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;
  }
}
ccopy

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);
ccopy

• [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++ к нестатическим свойствам данных, аксессорам и методам класса C++ можно обращаться из статических функций, указанных в дескрипторах свойств без атрибута napi_static, предварительно получив экземпляр класса 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);
ccopy

• [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);
ccopy

• [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);
ccopy

• [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);
ccopy

• [in] env: среда, в которой вызывается API.
• [in] js_object: объект JavaScript или внешний объект, который нужно пометить.
• [in] type_tag: тег, которым нужно пометить объект.

Возвращает napi_ok в случае успешного выполнения API.

Связывает значение указателя type_tag с объектом JavaScript или внешним объектом. Затем 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);
ccopy

• [in] env: среда, в которой вызывается API.
• [in] js_object: объект JavaScript или внешний объект, тег типа которого нужно проверить.
• [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);
ccopy

• [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);
ccopy

• [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 в обратном вызове execute, так как он, вероятно, выполнит 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);
ccopy

При вызове этих методов параметр 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);
ccopy

Функцию 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);
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] async_resource: Необязательный объект, связанный с асинхронной рабочей задачей, который будет передан возможным хукам async_hooks init.
• [in] async_resource_name: Идентификатор типа ресурса, предоставляемого для диагностической информации, доступной через API async_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);
ccopy

• [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);
ccopy

• [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);
ccopy

• [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)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] async_resource: Объект, связанный с асинхронной рабочей задачей, который будет передан возможным хукам async_hooks init и доступен через async_hooks.executionAsyncResource().
• [in] async_resource_name: Идентификатор типа ресурса, предоставляемого для диагностической информации, доступной через API async_hooks.
• [out] result: Инициализированный асинхронный контекст.

Возвращает napi_ok, если API выполнен успешно.

Для сохранения ABI-совместимости с предыдущими версиями передача NULL для async_resource не приводит к ошибке. Однако это не рекомендуется, поскольку может привести к нежелательному поведению хуков async_hooks init и async_hooks.executionAsyncResource(): теперь нижележащей реализации async_hooks необходим этот ресурс для связывания асинхронных обратных вызовов.

В предыдущих версиях этого API сильная ссылка на async_resource не сохранялась, пока существовал объект napi_async_context; вместо этого предполагалось, что вызывающий код удерживает сильную ссылку. Это поведение изменено, поскольку в любом случае для предотвращения утечек памяти требуется соответствующий вызов napi_async_destroy для каждого вызова napi_async_init().

napi_async_destroy

napi_status napi_async_destroy(napi_env env,
                               napi_async_context async_context);
ccopy

• [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);
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] async_context: Контекст асинхронной операции, инициирующей обратный вызов. Обычно это значение, ранее полученное с помощью napi_async_init. Для сохранения ABI-совместимости с предыдущими версиями передача NULL для async_context не приводит к ошибке. Однако это приведет к некорректной работе асинхронных хуков. Среди возможных проблем — потеря асинхронного контекста при использовании API AsyncLocalStorage.
• [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)
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] resource_object: Объект, связанный с асинхронной рабочей задачей, который будет передан возможным хукам async_hooks init. Этот параметр устарел и игнорируется во время выполнения. Вместо него используйте параметр 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)
ccopy

• [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);
ccopy

• [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);
ccopy

• [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.
• Если 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);
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] change_in_bytes: Изменение объема внешней памяти, удерживаемой объектами JavaScript.
• [out] result: Скорректированное значение. Оно должно отражать общий объем внешней памяти с учетом заданного change_in_bytes. Не следует полагаться на абсолютное значение возвращаемого результата. Например, реализация может использовать один счетчик для всех дополнений или отдельный счетчик для каждого дополнения.

Возвращает napi_ok, если API выполнен успешно.

Эта функция сообщает среде выполнения об объеме внешней памяти, удерживаемой объектами JavaScript (то есть об объекте JavaScript, ссылающемся на собственную память, выделенную нативным дополнением). Регистрация внешней памяти может привести к более частому запуску глобальной сборки мусора, хотя это и не гарантируется.

Предполагается, что эта функция вызывается таким образом, чтобы дополнение не уменьшало объем внешней памяти сильнее, чем оно его увеличило.

Промисы

Node-API предоставляет средства для создания объектов Promise, описанных в разделе спецификации ECMA «Объекты Promise». Промисы реализованы в виде пары объектов. При создании промиса с помощью napi_create_promise() создается объект «отложенного выполнения», который возвращается вместе с Promise. Объект отложенного выполнения связан с созданным Promise и является единственным способом разрешить или отклонить Promise с помощью napi_resolve_deferred() или napi_reject_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;
ccopy

Описанная выше функция do_something_asynchronous() выполнит асинхронное действие, а затем разрешит или отклонит отложенное выполнение, тем самым завершив промис и освободив объект отложенного выполнения:

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;
ccopy

napi_create_promise

napi_status napi_create_promise(napi_env env,
                                napi_deferred* deferred,
                                napi_value* promise);
ccopy

• [in] env: Среда, в которой вызывается API.
• [out] deferred: Только что созданный объект отложенного выполнения, который позднее можно передать в napi_resolve_deferred() или napi_reject_deferred() для разрешения или отклонения соответствующего промиса.
• [out] promise: Промис JavaScript, связанный с объектом отложенного выполнения.

Возвращает napi_ok, если API выполнен успешно.

Этот API создает объект отложенного выполнения и промис JavaScript.

napi_resolve_deferred

napi_status napi_resolve_deferred(napi_env env,
                                  napi_deferred deferred,
                                  napi_value resolution);
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] deferred: Объект отложенного выполнения, связанный с разрешаемым промисом.
• [in] resolution: Значение, которым разрешается промис.

Этот API разрешает промис JavaScript с помощью связанного с ним объекта отложенного выполнения. Поэтому его можно использовать только для разрешения промисов JavaScript, для которых доступен соответствующий объект отложенного выполнения. Это означает, что промис должен быть создан с помощью napi_create_promise(), а возвращенный этим вызовом объект отложенного выполнения должен быть сохранен, чтобы передать его в этот API.

Объект отложенного выполнения освобождается после успешного завершения.

napi_reject_deferred

napi_status napi_reject_deferred(napi_env env,
                                 napi_deferred deferred,
                                 napi_value rejection);
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] deferred: Объект отложенного выполнения, связанный с отклоняемым промисом.
• [in] rejection: Значение, которым отклоняется промис.

Этот API отклоняет промис JavaScript с помощью связанного с ним объекта отложенного выполнения. Поэтому его можно использовать только для отклонения промисов JavaScript, для которых доступен соответствующий объект отложенного выполнения. Это означает, что промис должен быть создан с помощью napi_create_promise(), а возвращенный этим вызовом объект отложенного выполнения должен быть сохранен, чтобы передать его в этот API.

Объект отложенного выполнения освобождается после успешного завершения.

napi_is_promise

napi_status napi_is_promise(napi_env env,
                            napi_value value,
                            bool* is_promise);
ccopy

• [in] env: Среда, в которой вызывается API.
• [in] value: Проверяемое значение
• [out] is_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);
ccopy

• [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);
ccopy

• [in] env: Среда, в которой вызывается API.
• [out] loop: Текущий экземпляр цикла libuv.

Примечание. Хотя libuv гарантирует стабильность ABI только в пределах одной основной версии, его использование может привести к тому, что дополнение не будет работать в разных основных версиях Node.js.

ThreadSafeFunction — это ABI-совместимая альтернатива вызову из другого потока кода в потоке JavaScript для многих сценариев использования.

Асинхронные потокобезопасные вызовы функций

Обычно функции 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().

Вызов потокобезопасной функции

Для инициирования вызова JavaScript можно использовать napi_call_threadsafe_function(). 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_call_threadsafe_function() значение возврата napi_closing, поток больше не должен использовать потокобезопасную функцию, поскольку её выделение больше не гарантируется.

Определение необходимости продолжать работу процесса

Как и дескрипторы 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);
ccopy

• [in] env: среда, в которой вызывается API.
• [in] func: необязательная функция JavaScript, вызываемая из другого потока. Её необходимо передать, если в call_js_cb передан NULL.
• [in] async_resource: необязательный объект, связанный с асинхронной работой, который будет передан возможным хукам async_hooks init.
• [in] async_resource_name: строка JavaScript, задающая идентификатор типа ресурса, предоставляемого для диагностической информации, доступной через API async_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 будет вызвана без параметров и со значением undefined в качестве значения this. Подробнее см. в разделе 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);
ccopy

• [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);
ccopy

• [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);
ccopy

• [in] func: асинхронная потокобезопасная функция JavaScript, использование которой нужно начать.

Прежде чем передавать func в любые другие API потокобезопасной функции, поток должен вызвать этот 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);
ccopy

• [in] func: асинхронная потокобезопасная функция JavaScript, счётчик ссылок на которую нужно уменьшить.
• [in] mode: флаг, значением которого может быть napi_tsfn_release, чтобы указать, что текущий поток больше не будет вызывать потокобезопасную функцию, или napi_tsfn_abort, чтобы указать, что ни текущий, ни какие-либо другие потоки больше не должны вызывать потокобезопасную функцию. Если задано значение napi_tsfn_abort, последующие вызовы napi_call_threadsafe_function() будут возвращать napi_closing, а новые значения не будут помещаться в очередь.

Когда поток прекращает использовать func, он должен вызвать этот API. Передача 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);
ccopy

• [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);
ccopy

• [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);

ccopy

• [in] env: среда, в которой вызывается API.
• [out] result: URL-адрес, содержащий абсолютный путь к месту загрузки аддона. Для файла в локальной файловой системе он будет начинаться с file://. Строка завершается нулевым символом, принадлежит env и поэтому не должна изменяться или освобождаться.

result может быть пустой строкой, если в процессе загрузки аддона не удалось определить его имя файла.