V8

Модуль node:v8 предоставляет API, специфичные для версии V8, встроенной в исполняемый файл Node.js. К нему можно получить доступ с помощью:

import v8 from 'node:v8';

const v8 = require('node:v8');

v8.cachedDataVersionTag()

• Возвращает: <integer>

Возвращает целое число, представляющее тег версии, полученный на основе версии V8, флагов командной строки и обнаруженных возможностей процессора. Это полезно для определения совместимости буфера vm.Script cachedData с данным экземпляром V8.

console.log(v8.cachedDataVersionTag()); // 3947234607
// The value returned by v8.cachedDataVersionTag() is derived from the V8
// version, command-line flags, and detected CPU features. Test that the value
// does indeed update when flags are toggled.
v8.setFlagsFromString('--allow_natives_syntax');
console.log(v8.cachedDataVersionTag()); // 183726201
jscopy

v8.getHeapCodeStatistics()

• Возвращает: <Object>

Получает статистику о коде и его метаданных в куче; см. API V8 GetHeapCodeAndMetadataStatistics. Возвращает объект со следующими свойствами:

• code_and_metadata_size <number>
• bytecode_and_metadata_size <number>
• external_script_source_size <number>
• cpu_profiler_metadata_size <number>

{
  "code_and_metadata_size": 212208,
  "bytecode_and_metadata_size": 161368,
  "external_script_source_size": 1410794,
  "cpu_profiler_metadata_size": 0
}
jsoncopy

v8.getHeapSnapshot([options])

• options <Object>

  • exposeInternals <boolean> Если значение равно true, внутренние данные будут включены в снимок кучи. По умолчанию: false.
  • exposeNumericValues <boolean> Если значение равно true, числовые значения будут включены в искусственные поля. По умолчанию: false.

• Возвращает: <stream.Readable> Поток Readable, содержащий снимок кучи V8.

Создает снимок текущей кучи V8 и возвращает поток Readable, который можно использовать для чтения сериализованного в JSON представления. Этот формат JSON-потока предназначен для использования с такими инструментами, как Chrome DevTools. Схема JSON не документирована и специфична для движка V8. Поэтому схема может меняться от одной версии V8 к другой.

Для создания снимка кучи требуется объем памяти, примерно вдвое превышающий размер кучи на момент создания снимка. Это создает риск завершения процесса механизмами OOM killer.

Создание снимка — синхронная операция, блокирующая цикл событий на время, зависящее от размера кучи.

// Print heap snapshot to the console
import { getHeapSnapshot } from 'node:v8';
import process from 'node:process';
const stream = getHeapSnapshot();
stream.pipe(process.stdout);
mjscopy

// Print heap snapshot to the console
const v8 = require('node:v8');
const stream = v8.getHeapSnapshot();
stream.pipe(process.stdout);
jscopy

v8.getHeapSpaceStatistics()

• Возвращает: <Object[]>

Возвращает статистику по областям кучи V8, то есть сегментам, из которых состоит куча V8. Порядок областей кучи и наличие той или иной области не гарантируются, поскольку статистика предоставляется функцией V8 GetHeapSpaceStatistics и может меняться от одной версии V8 к другой.

Возвращаемое значение представляет собой массив объектов со следующими свойствами:

• space_name <string>
• space_size <number>
• space_used_size <number>
• space_available_size <number>
• physical_space_size <number>

[
  {
    "space_name": "new_space",
    "space_size": 2063872,
    "space_used_size": 951112,
    "space_available_size": 80824,
    "physical_space_size": 2063872
  },
  {
    "space_name": "old_space",
    "space_size": 3090560,
    "space_used_size": 2493792,
    "space_available_size": 0,
    "physical_space_size": 3090560
  },
  {
    "space_name": "code_space",
    "space_size": 1260160,
    "space_used_size": 644256,
    "space_available_size": 960,
    "physical_space_size": 1260160
  },
  {
    "space_name": "map_space",
    "space_size": 1094160,
    "space_used_size": 201608,
    "space_available_size": 0,
    "physical_space_size": 1094160
  },
  {
    "space_name": "large_object_space",
    "space_size": 0,
    "space_used_size": 0,
    "space_available_size": 1490980608,
    "physical_space_size": 0
  }
]
jsoncopy

v8.getHeapStatistics()

• Возвращает: <Object>

Возвращает объект со следующими свойствами:

• total_heap_size <number>
• total_heap_size_executable <number>
• total_physical_size <number>
• total_available_size <number>
• used_heap_size <number>
• heap_size_limit <number>
• malloced_memory <number>
• peak_malloced_memory <number>
• does_zap_garbage <number>
• number_of_native_contexts <number>
• number_of_detached_contexts <number>
• total_global_handles_size <number>
• used_global_handles_size <number>
• external_memory <number>
• total_allocated_bytes <number>

total_heap_size Значение total_heap_size — это количество байтов, выделенных V8 для кучи. Оно может увеличиваться, если used_heap требуется больше памяти.

total_heap_size_executable Значение total_heap_size_executable — это часть кучи, которая может содержать исполняемый код, в байтах. Сюда входит память, используемая кодом, скомпилированным JIT-компилятором, а также любая память, которую необходимо сохранять исполняемой.

total_physical_size Значение total_physical_size — это фактически используемый физический объем памяти кучи V8, в байтах. Это объем выделенной (или используемой), а не зарезервированной памяти.

total_available_size Значение total_available_size — это количество байтов памяти, доступной для кучи V8. Оно показывает, сколько дополнительной памяти может использовать V8, прежде чем будет превышен предел размера кучи.

used_heap_size Значение used_heap_size — это количество байтов, используемых в данный момент объектами JavaScript V8. Это фактически используемая память; в нее не входит память, которая была выделена, но еще не использована.

heap_size_limit Значение heap_size_limit — это максимальный размер кучи V8 в байтах (либо предел по умолчанию, определяемый системными ресурсами, либо значение, переданное параметру --max_old_space_size).

malloced_memory Значение malloced_memory — это количество байтов, выделенных V8 с помощью malloc.

peak_malloced_memory Значение peak_malloced_memory — это максимальное количество байтов, выделенных V8 с помощью malloc за время существования процесса.

does_zap_garbage — это логическое значение 0/1, указывающее, включен ли параметр --zap_code_space. При его включении V8 перезаписывает мусор в куче битовым шаблоном. Размер резидентного набора (RSS) увеличивается, поскольку происходит непрерывное обращение ко всем страницам кучи, из-за чего операционная система с меньшей вероятностью выгрузит их в файл подкачки.

number_of_native_contexts Значение native_context — это количество активных контекстов верхнего уровня. Увеличение этого числа со временем указывает на утечку памяти.

number_of_detached_contexts Значение detached_context — это количество отсоединенных контекстов, которые еще не были собраны сборщиком мусора. Ненулевое значение указывает на возможную утечку памяти.

total_global_handles_size Значение total_global_handles_size — это общий размер памяти глобальных дескрипторов V8.

used_global_handles_size Значение used_global_handles_size — это объем используемой памяти глобальных дескрипторов V8.

external_memory Значение external_memory — это объем памяти буферов массивов и внешних строк.

total_allocated_bytes Значение общего количества выделенных байтов с момента создания Isolate

{
  "total_heap_size": 7326976,
  "total_heap_size_executable": 4194304,
  "total_physical_size": 7326976,
  "total_available_size": 1152656,
  "used_heap_size": 3476208,
  "heap_size_limit": 1535115264,
  "malloced_memory": 16384,
  "peak_malloced_memory": 1127496,
  "does_zap_garbage": 0,
  "number_of_native_contexts": 1,
  "number_of_detached_contexts": 0,
  "total_global_handles_size": 8192,
  "used_global_handles_size": 3296,
  "external_memory": 318824
}
jsoncopy

v8.getCppHeapStatistics([detailLevel])

Получает статистику CppHeap о потреблении и использовании памяти с помощью функции V8 CollectStatistics(), которая может меняться от одной версии V8 к другой.

• detailLevel <string> | <undefined>: По умолчанию: 'detailed'. Задает уровень детализации возвращаемой статистики. Допустимые значения:
  • 'brief': краткая статистика содержит только общие сведения о выделенной и используемой памяти всей кучи.
  • 'detailed': подробная статистика также содержит разбивку по областям и страницам, а также статистику списков свободных блоков и гистограммы типов объектов.

Возвращает объект со структурой, похожей на структуру объекта cppgc::HeapStatistics. Дополнительные сведения о свойствах объекта см. в документации V8.

// Detailed
({
  committed_size_bytes: 131072,
  resident_size_bytes: 131072,
  used_size_bytes: 152,
  space_statistics: [
    {
      name: 'NormalPageSpace0',
      committed_size_bytes: 0,
      resident_size_bytes: 0,
      used_size_bytes: 0,
      page_stats: [{}],
      free_list_stats: {},
    },
    {
      name: 'NormalPageSpace1',
      committed_size_bytes: 131072,
      resident_size_bytes: 131072,
      used_size_bytes: 152,
      page_stats: [{}],
      free_list_stats: {},
    },
    {
      name: 'NormalPageSpace2',
      committed_size_bytes: 0,
      resident_size_bytes: 0,
      used_size_bytes: 0,
      page_stats: [{}],
      free_list_stats: {},
    },
    {
      name: 'NormalPageSpace3',
      committed_size_bytes: 0,
      resident_size_bytes: 0,
      used_size_bytes: 0,
      page_stats: [{}],
      free_list_stats: {},
    },
    {
      name: 'LargePageSpace',
      committed_size_bytes: 0,
      resident_size_bytes: 0,
      used_size_bytes: 0,
      page_stats: [{}],
      free_list_stats: {},
    },
  ],
  type_names: [],
  detail_level: 'detailed',
});
jscopy

// Brief
({
  committed_size_bytes: 131072,
  resident_size_bytes: 131072,
  used_size_bytes: 128864,
  space_statistics: [],
  type_names: [],
  detail_level: 'brief',
});
jscopy

v8.queryObjects(ctor[, options])

• ctor <Function> Конструктор, который можно использовать для поиска по цепочке прототипов, чтобы отфильтровать целевые объекты в куче.
• options <undefined> | <Object>
  • format <string> Если значение равно 'count', возвращается количество совпавших объектов. Если оно равно 'summary', возвращается массив строк с краткими сведениями о совпавших объектах.
• Возвращает: <number> | <string[]>

Этот метод аналогичен функции queryObjects() API консоли, предоставляемой консолью Chromium DevTools. Его можно использовать для поиска в куче объектов, у которых в цепочке прототипов имеется соответствующий конструктор, после полной сборки мусора; это может быть полезно для регрессионного тестирования утечек памяти. Чтобы избежать неожиданных результатов, не следует использовать этот API для конструкторов, реализацию которых вы не контролируете, или конструкторов, которые могут вызываться другими участниками приложения.

Чтобы избежать случайных утечек, этот API не возвращает непосредственные ссылки на найденные объекты. По умолчанию он возвращает количество найденных объектов. Если options.format равно 'summary', возвращается массив, содержащий краткие строковые представления каждого объекта. Предоставляемые этим API данные аналогичны данным снимка кучи, однако этот API позволяет избежать затрат на сериализацию и разбор и напрямую фильтровать целевые объекты во время поиска.

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

const { queryObjects } = require('node:v8');
class A { foo = 'bar'; }
console.log(queryObjects(A)); // 0
const a = new A();
console.log(queryObjects(A)); // 1
// [ "A { foo: 'bar' }" ]
console.log(queryObjects(A, { format: 'summary' }));

class B extends A { bar = 'qux'; }
const b = new B();
console.log(queryObjects(B)); // 1
// [ "B { foo: 'bar', bar: 'qux' }" ]
console.log(queryObjects(B, { format: 'summary' }));

// Note that, when there are child classes inheriting from a constructor,
// the constructor also shows up in the prototype chain of the child
// classes's prototype, so the child classes's prototype would also be
// included in the result.
console.log(queryObjects(A));  // 3
// [ "B { foo: 'bar', bar: 'qux' }", 'A {}', "A { foo: 'bar' }" ]
console.log(queryObjects(A, { format: 'summary' }));

import { queryObjects } from 'node:v8';
class A { foo = 'bar'; }
console.log(queryObjects(A)); // 0
const a = new A();
console.log(queryObjects(A)); // 1
// [ "A { foo: 'bar' }" ]
console.log(queryObjects(A, { format: 'summary' }));

class B extends A { bar = 'qux'; }
const b = new B();
console.log(queryObjects(B)); // 1
// [ "B { foo: 'bar', bar: 'qux' }" ]
console.log(queryObjects(B, { format: 'summary' }));

// Note that, when there are child classes inheriting from a constructor,
// the constructor also shows up in the prototype chain of the child
// classes's prototype, so the child classes's prototype would also be
// included in the result.
console.log(queryObjects(A));  // 3
// [ "B { foo: 'bar', bar: 'qux' }", 'A {}', "A { foo: 'bar' }" ]
console.log(queryObjects(A, { format: 'summary' }));

v8.setFlagsFromString(flags)

• flags <string>

Метод v8.setFlagsFromString() можно использовать для программной установки флагов командной строки V8. Этот метод следует использовать с осторожностью. Изменение настроек после запуска виртуальной машины может привести к непредсказуемому поведению, включая сбои и потерю данных, либо не дать никакого эффекта.

Список параметров V8, доступных для конкретной версии Node.js, можно получить, выполнив node --v8-options.

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

import { setFlagsFromString } from 'node:v8';
import { setInterval } from 'node:timers';

// setFlagsFromString to trace garbage collection events
setFlagsFromString('--trace-gc');

// Trigger GC events by using some memory
let arrays = [];
const interval = setInterval(() => {
  for (let i = 0; i < 500; i++) {
    arrays.push(new Array(10000).fill(Math.random()));
  }

  if (arrays.length > 5000) {
    arrays = arrays.slice(-1000);
  }

  console.log(`\n* Created ${arrays.length} arrays\n`);
}, 100);

// setFlagsFromString to stop tracing GC events after 1.5 seconds
setTimeout(() => {
  setFlagsFromString('--notrace-gc');
  console.log('\nStopped tracing!\n');
}, 1500);

// Stop triggering GC events altogether after 2.5 seconds
setTimeout(() => {
  clearInterval(interval);
}, 2500);

const { setFlagsFromString } = require('node:v8');
const { setInterval } = require('node:timers');

// setFlagsFromString to trace garbage collection events
setFlagsFromString('--trace-gc');

// Trigger GC events by using some memory
let arrays = [];
const interval = setInterval(() => {
  for (let i = 0; i < 500; i++) {
    arrays.push(new Array(10000).fill(Math.random()));
  }

  if (arrays.length > 5000) {
    arrays = arrays.slice(-1000);
  }

  console.log(`\n* Created ${arrays.length} arrays\n`);
}, 100);

// setFlagsFromString to stop tracing GC events after 1.5 seconds
setTimeout(() => {
  console.log('\nStopped tracing!\n');
  setFlagsFromString('--notrace-gc');
}, 1500);

// Stop triggering GC events altogether after 2.5 seconds
setTimeout(() => {
  clearInterval(interval);
}, 2500);

v8.stopCoverage()

Метод v8.stopCoverage() позволяет остановить сбор данных о покрытии, начатый с помощью NODE_V8_COVERAGE, чтобы V8 мог освободить записи счетчиков выполнения и оптимизировать код. Его можно использовать вместе с v8.takeCoverage(), если требуется собирать данные о покрытии по запросу.

v8.takeCoverage()

Метод v8.takeCoverage() позволяет по запросу записывать на диск данные о покрытии, сбор которых начат с помощью NODE_V8_COVERAGE. Этот метод можно вызывать несколько раз в течение времени существования процесса. При каждом вызове счетчик выполнения сбрасывается, а новый отчет о покрытии записывается в каталог, указанный в NODE_V8_COVERAGE.

Перед завершением процесса последние данные о покрытии все равно будут записаны на диск, если до завершения процесса не был вызван v8.stopCoverage().

v8.writeHeapSnapshot([filename[,options]])

• filename <string> Путь к файлу, в который будет сохранен снимок кучи V8. Если он не указан, будет создано имя файла по шаблону 'Heap-${yyyymmdd}-${hhmmss}-${pid}-${thread_id}.heapsnapshot', где {pid} — PID процесса Node.js, а {thread_id} будет равно 0, если вызов writeHeapSnapshot() выполняется в основном потоке Node.js, или будет содержать идентификатор рабочего потока.
• options <Object>
  • exposeInternals <boolean> Если значение равно true, внутренние данные будут включены в снимок кучи. По умолчанию: false.
  • exposeNumericValues <boolean> Если значение равно true, числовые значения будут включены в искусственные поля. По умолчанию: false.
• Возвращает: <string> Имя файла, в который был сохранен снимок.

Создает снимок текущей кучи V8 и записывает его в файл JSON. Этот файл предназначен для использования с такими инструментами, как Chrome DevTools. Схема JSON не документирована и специфична для движка V8; она может меняться от одной версии V8 к другой.

Снимок кучи относится к одному экземпляру V8. При использовании рабочих потоков снимок, созданный в основном потоке, не будет содержать сведений о рабочих потоках, и наоборот.

Для создания снимка кучи требуется объем памяти, примерно вдвое превышающий размер кучи на момент создания снимка. Это создает риск завершения процесса механизмами OOM killer.

Создание снимка — синхронная операция, блокирующая цикл событий на время, зависящее от размера кучи.

import { writeHeapSnapshot } from 'node:v8';
import { Worker, isMainThread, parentPort } from 'node:worker_threads';
import { fileURLToPath } from 'node:url';

if (isMainThread) {
  const __filename = fileURLToPath(import.meta.url);
  const worker = new Worker(__filename);

  worker.once('message', (filename) => {
    console.log(`worker heapdump: ${filename}`);
    // Now get a heapdump for the main thread.
    console.log(`main thread heapdump: ${writeHeapSnapshot()}`);
  });

  // Tell the worker to create a heapdump.
  worker.postMessage('heapdump');
} else {
  parentPort.once('message', (message) => {
    if (message === 'heapdump') {
      // Generate a heapdump for the worker
      // and return the filename to the parent.
      parentPort.postMessage(writeHeapSnapshot());
    }
  });
}

const { writeHeapSnapshot } = require('node:v8');
const { Worker, isMainThread, parentPort } = require('node:worker_threads');

if (isMainThread) {
  const worker = new Worker(__filename);

  worker.once('message', (filename) => {
    console.log(`worker heapdump: ${filename}`);
    // Now get a heapdump for the main thread.
    console.log(`main thread heapdump: ${writeHeapSnapshot()}`);
  });

  // Tell the worker to create a heapdump.
  worker.postMessage('heapdump');
} else {
  parentPort.once('message', (message) => {
    if (message === 'heapdump') {
      // Generate a heapdump for the worker
      // and return the filename to the parent.
      parentPort.postMessage(writeHeapSnapshot());
    }
  });
}

v8.setHeapSnapshotNearHeapLimit(limit)

• limit <integer>

API ничего не делает, если --heapsnapshot-near-heap-limit уже задан в командной строке или если API вызывается более одного раза. limit должно быть положительным целым числом. Дополнительные сведения см. в разделе --heapsnapshot-near-heap-limit.

API сериализации

API сериализации предоставляет средства для сериализации значений JavaScript способом, совместимым с алгоритмом структурированного клонирования HTML.

Формат обратно совместим (то есть безопасен для хранения на диске). Одинаковые значения JavaScript могут иметь разное сериализованное представление.

v8.serialize(value)

• value <any>
• Возвращает: <Buffer>

Использует DefaultSerializer для сериализации value в буфер.

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

v8.deserialize(buffer)

• buffer <Buffer> | <TypedArray> | <DataView> Буфер, возвращенный методом serialize().

Использует DefaultDeserializer с параметрами по умолчанию для чтения значения JS из буфера.

Класс: v8.Serializer

new Serializer()

Создает новый объект Serializer.

serializer.writeHeader()

Записывает заголовок, содержащий версию формата сериализации.

serializer.writeValue(value)

• value <any>

Сериализует значение JavaScript и добавляет его сериализованное представление во внутренний буфер.

Если value невозможно сериализовать, будет выброшена ошибка.

serializer.releaseBuffer()

• Возвращает: <Buffer>

Возвращает сохраненный внутренний буфер. После освобождения буфера этот сериализатор использовать нельзя. Если предыдущая запись завершилась ошибкой, вызов этого метода приводит к неопределенному поведению.

serializer.transferArrayBuffer(id, arrayBuffer)

• id <integer> Беззнаковое 32-разрядное целое число.
• arrayBuffer <ArrayBuffer> Экземпляр ArrayBuffer.

Помечает ArrayBuffer как объект, содержимое которого передается вне основного потока данных. Передайте соответствующий ArrayBuffer в контекст десериализации для вызова deserializer.transferArrayBuffer().

serializer.writeUint32(value)

• value <integer>

Записывает необработанное беззнаковое 32-разрядное целое число. Используется внутри пользовательского метода serializer._writeHostObject().

serializer.writeUint64(hi, lo)

• hi <integer>
• lo <integer>

Записывает необработанное беззнаковое 64-разрядное целое число, разделенное на старшую и младшую 32-разрядные части. Используется внутри пользовательского метода serializer._writeHostObject().

serializer.writeDouble(value)

• value <number>

Записывает значение JS типа number. Используется внутри пользовательского метода serializer._writeHostObject().

serializer.writeRawBytes(buffer)

• buffer <Buffer> | <TypedArray> | <DataView>

Записывает необработанные байты во внутренний буфер сериализатора. Десериализатору потребуется способ вычисления длины буфера. Используется внутри пользовательского метода serializer._writeHostObject().

serializer._writeHostObject(object)

• object <Object>

Этот метод вызывается для записи хост-объекта, то есть объекта, созданного нативными привязками C++. Если сериализовать object невозможно, следует выбросить подходящее исключение.

Этот метод отсутствует в самом классе Serializer, но может быть реализован в подклассах.

serializer._getDataCloneError(message)

• message <string>

Этот метод вызывается для создания объектов ошибок, которые будут выброшены, если объект не удается клонировать.

По умолчанию метод использует конструктор Error; в подклассах его можно переопределить.

serializer._getSharedArrayBufferId(sharedArrayBuffer)

• sharedArrayBuffer <SharedArrayBuffer>

Этот метод вызывается, когда сериализатор собирается сериализовать объект SharedArrayBuffer. Он должен возвращать беззнаковый 32-разрядный идентификатор объекта, используя один и тот же идентификатор, если этот SharedArrayBuffer уже был сериализован. При десериализации этот идентификатор будет передан методу deserializer.transferArrayBuffer().

Если объект невозможно сериализовать, следует выбросить исключение.

Этот метод отсутствует в самом классе Serializer, но может быть реализован в подклассах.

serializer._setTreatArrayBufferViewsAsHostObjects(flag)

• flag <boolean> По умолчанию: false

Указывает, следует ли считать объекты TypedArray и DataView хост-объектами, то есть передавать их методу serializer._writeHostObject().

Класс: v8.Deserializer

new Deserializer(buffer)

• buffer <Buffer> | <TypedArray> | <DataView> Буфер, возвращенный методом serializer.releaseBuffer().

Создает новый объект Deserializer.

deserializer.readHeader()

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

deserializer.readValue()

Десериализует значение JavaScript из буфера и возвращает его.

deserializer.transferArrayBuffer(id, arrayBuffer)

• id <integer> 32-разрядное беззнаковое целое число.
• arrayBuffer <ArrayBuffer> | <SharedArrayBuffer> Экземпляр ArrayBuffer.

Помечает ArrayBuffer как объект, содержимое которого передается вне основного потока. Передайте соответствующий ArrayBuffer в контекст сериализации в serializer.transferArrayBuffer() (или верните id из serializer._getSharedArrayBufferId() в случае объектов SharedArrayBuffer).

deserializer.getWireFormatVersion()

• Возвращает: <integer>

Читает версию используемого формата передачи данных. Вероятно, это будет полезно в основном устаревшему коду, считывающему старые версии формата. Вызов до .readHeader() невозможен.

deserializer.readUint32()

• Возвращает: <integer>

Читает необработанное 32-разрядное беззнаковое целое число и возвращает его. Используется внутри пользовательского deserializer._readHostObject().

deserializer.readUint64()

• Возвращает: <integer[]>

Читает необработанное 64-разрядное беззнаковое целое число и возвращает его в виде массива [hi, lo] с двумя элементами — 32-разрядными беззнаковыми целыми числами. Используется внутри пользовательского deserializer._readHostObject().

deserializer.readDouble()

• Возвращает: <number>

Читает значение number JavaScript. Используется внутри пользовательского deserializer._readHostObject().

deserializer.readRawBytes(length)

• length <integer>
• Возвращает: <Buffer>

Читает необработанные байты из внутреннего буфера десериализатора. Параметр length должен соответствовать длине буфера, переданного в serializer.writeRawBytes(). Используется внутри пользовательского deserializer._readHostObject().

deserializer._readHostObject()

Этот метод вызывается для чтения объекта определенного типа, созданного, например, привязками кода C++. Если десериализовать данные невозможно, следует выбросить подходящее исключение.

Этот метод отсутствует в самом классе Deserializer, но его можно реализовать в подклассах.

Класс: v8.DefaultSerializer

Подкласс Serializer, который сериализует объекты TypedArray (в частности, Buffer) и DataView как объекты среды выполнения и сохраняет только ту часть базовых ArrayBuffer, на которую они ссылаются.

Класс: v8.DefaultDeserializer

Подкласс Deserializer, соответствующий формату, записываемому с помощью DefaultSerializer.

Перехватчики Promise

Интерфейс promiseHooks можно использовать для отслеживания событий жизненного цикла Promise. Для отслеживания всей асинхронной активности см. async_hooks, который использует этот модуль для создания событий жизненного цикла Promise, а также событий для других асинхронных ресурсов. Для управления контекстом запросов см. AsyncLocalStorage.

import { promiseHooks } from 'node:v8';

// There are four lifecycle events produced by promises:

// The `init` event represents the creation of a promise. This could be a
// direct creation such as with `new Promise(...)` or a continuation such
// as `then()` or `catch()`. It also happens whenever an async function is
// called or does an `await`. If a continuation promise is created, the
// `parent` will be the promise it is a continuation from.
function init(promise, parent) {
  console.log('a promise was created', { promise, parent });
}

// The `settled` event happens when a promise receives a resolution or
// rejection value. This may happen synchronously such as when using
// `Promise.resolve()` on non-promise input.
function settled(promise) {
  console.log('a promise resolved or rejected', { promise });
}

// The `before` event runs immediately before a `then()` or `catch()` handler
// runs or an `await` resumes execution.
function before(promise) {
  console.log('a promise is about to call a then handler', { promise });
}

// The `after` event runs immediately after a `then()` handler runs or when
// an `await` begins after resuming from another.
function after(promise) {
  console.log('a promise is done calling a then handler', { promise });
}

// Lifecycle hooks may be started and stopped individually
const stopWatchingInits = promiseHooks.onInit(init);
const stopWatchingSettleds = promiseHooks.onSettled(settled);
const stopWatchingBefores = promiseHooks.onBefore(before);
const stopWatchingAfters = promiseHooks.onAfter(after);

// Or they may be started and stopped in groups
const stopHookSet = promiseHooks.createHook({
  init,
  settled,
  before,
  after,
});

// Trigger the hooks by using promises
const promiseLog = (word) => Promise.resolve(word).then(console.log);
promiseLog('Hello');
promiseLog('World');

// To stop a hook, call the function returned at its creation.
stopWatchingInits();
stopWatchingSettleds();
stopWatchingBefores();
stopWatchingAfters();
stopHookSet();

const { promiseHooks } = require('node:v8');

// There are four lifecycle events produced by promises:

// The `init` event represents the creation of a promise. This could be a
// direct creation such as with `new Promise(...)` or a continuation such
// as `then()` or `catch()`. It also happens whenever an async function is
// called or does an `await`. If a continuation promise is created, the
// `parent` will be the promise it is a continuation from.
function init(promise, parent) {
  console.log('a promise was created', { promise, parent });
}

// The `settled` event happens when a promise receives a resolution or
// rejection value. This may happen synchronously such as when using
// `Promise.resolve()` on non-promise input.
function settled(promise) {
  console.log('a promise resolved or rejected', { promise });
}

// The `before` event runs immediately before a `then()` or `catch()` handler
// runs or an `await` resumes execution.
function before(promise) {
  console.log('a promise is about to call a then handler', { promise });
}

// The `after` event runs immediately after a `then()` handler runs or when
// an `await` begins after resuming from another.
function after(promise) {
  console.log('a promise is done calling a then handler', { promise });
}

// Lifecycle hooks may be started and stopped individually
const stopWatchingInits = promiseHooks.onInit(init);
const stopWatchingSettleds = promiseHooks.onSettled(settled);
const stopWatchingBefores = promiseHooks.onBefore(before);
const stopWatchingAfters = promiseHooks.onAfter(after);

// Or they may be started and stopped in groups
const stopHookSet = promiseHooks.createHook({
  init,
  settled,
  before,
  after,
});

// Trigger the hooks by using promises
const promisePrint = (word) => Promise.resolve(word).then(console.log);
promisePrint('Hello');
promisePrint('World');

// To stop a hook, call the function returned at its creation.
stopWatchingInits();
stopWatchingSettleds();
stopWatchingBefores();
stopWatchingAfters();
stopHookSet();

promiseHooks.onInit(init)

• init <Function> Функция обратного вызова init, вызываемая при создании Promise.
• Возвращает: <Function> Вызов для остановки перехватчика.

Перехватчик init должен быть обычной функцией. Передача асинхронной функции приведет к ошибке, поскольку она создаст бесконечный цикл микрозадач.

import { promiseHooks } from 'node:v8';

const stop = promiseHooks.onInit((promise, parent) => {});

const { promiseHooks } = require('node:v8');

const stop = promiseHooks.onInit((promise, parent) => {});

promiseHooks.onSettled(settled)

• settled <Function> Функция обратного вызова settled, вызываемая при выполнении или отклонении Promise.
• Возвращает: <Function> Вызов для остановки перехватчика.

Перехватчик settled должен быть обычной функцией. Передача асинхронной функции приведет к ошибке, поскольку она создаст бесконечный цикл микрозадач.

import { promiseHooks } from 'node:v8';

const stop = promiseHooks.onSettled((promise) => {});

const { promiseHooks } = require('node:v8');

const stop = promiseHooks.onSettled((promise) => {});

promiseHooks.onBefore(before)

• before <Function> Функция обратного вызова before, вызываемая перед выполнением продолжения Promise.
• Возвращает: <Function> Вызов для остановки перехватчика.

Перехватчик before должен быть обычной функцией. Передача асинхронной функции приведет к ошибке, поскольку она создаст бесконечный цикл микрозадач.

import { promiseHooks } from 'node:v8';

const stop = promiseHooks.onBefore((promise) => {});

const { promiseHooks } = require('node:v8');

const stop = promiseHooks.onBefore((promise) => {});

promiseHooks.onAfter(after)

• after <Function> Функция обратного вызова after, вызываемая после выполнения продолжения Promise.
• Возвращает: <Function> Вызов для остановки перехватчика.

Перехватчик after должен быть обычной функцией. Передача асинхронной функции приведет к ошибке, поскольку она создаст бесконечный цикл микрозадач.

import { promiseHooks } from 'node:v8';

const stop = promiseHooks.onAfter((promise) => {});

const { promiseHooks } = require('node:v8');

const stop = promiseHooks.onAfter((promise) => {});

promiseHooks.createHook(callbacks)

• callbacks <Object> Функции обратного вызова перехватчиков, которые нужно зарегистрировать
  • init <Function> Функция обратного вызова init.
  • before <Function> Функция обратного вызова before.
  • after <Function> Функция обратного вызова after.
  • settled <Function> Функция обратного вызова settled.
• Возвращает: <Function> Используется для отключения перехватчиков

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

Регистрирует функции, вызываемые при различных событиях жизненного цикла каждого Promise.

Функции обратного вызова init()/before()/after()/settled() вызываются при соответствующих событиях жизненного цикла Promise.

Все функции обратного вызова необязательны. Например, если нужно отслеживать только создание Promise, достаточно передать функцию обратного вызова init. Описание всех функций, которые можно передать в callbacks, см. в разделе Функции обратного вызова перехватчиков.

import { promiseHooks } from 'node:v8';

const stopAll = promiseHooks.createHook({
  init(promise, parent) {},
});

const { promiseHooks } = require('node:v8');

const stopAll = promiseHooks.createHook({
  init(promise, parent) {},
});

Функции обратного вызова перехватчиков

Ключевые события жизненного цикла Promise разделены на четыре группы: создание Promise, выполнение обработчика продолжения (до и после вызова) или выполнение await, а также разрешение или отклонение Promise.

Хотя эти перехватчики похожи на перехватчики async_hooks, в них отсутствует перехватчик destroy. Другие типы асинхронных ресурсов обычно представляют сокеты или файловые дескрипторы, которые имеют отдельное состояние «закрыто», обозначающее событие жизненного цикла destroy, тогда как Promise остаются доступными, пока код может на них ссылаться. Для включения Promise в модель событий async_hooks используется отслеживание сборки мусора, однако оно обходится очень дорого, и сборка мусора для них может вообще никогда не выполняться.

Поскольку Promise — это асинхронные ресурсы, жизненный цикл которых отслеживается механизмом перехватчиков Promise, функции обратного вызова init(), before(), after() и settled() не должны быть асинхронными функциями, поскольку они создают новые Promise, что привело бы к бесконечному циклу.

Хотя этот API используется для передачи событий Promise в async_hooks, порядок вызова событий в этих двух API не определен. Оба API могут использоваться несколькими потребителями, поэтому события могут возникать в любом порядке относительно друг друга.

init(promise, parent)

• promise <Promise> Создаваемый Promise.
• parent <Promise> Promise, от которого продолжается выполнение, если применимо.

Вызывается при создании Promise. Это не означает, что произойдут соответствующие события before/after, а лишь то, что такая возможность существует. Это происходит, если Promise создается, но для него так и не создается продолжение.

before(promise)

• promise <Promise>

Вызывается перед выполнением продолжения Promise. Это может быть обработчик then(), catch() или finally() либо возобновление await.

Функция обратного вызова before вызывается от 0 до N раз. Функция обратного вызова before обычно не вызывается, если для Promise не было создано продолжение. Функция обратного вызова before может вызываться много раз, если для одного и того же Promise создано несколько продолжений.

after(promise)

• promise <Promise>

Вызывается сразу после выполнения продолжения Promise. Это может происходить после обработчика then(), catch() или finally() либо перед await после другого await.

settled(promise)

• promise <Promise>

Вызывается, когда Promise получает значение результата или отклонения. Это может происходить синхронно в случае Promise.resolve() или Promise.reject().

API снимков состояния при запуске

Интерфейс v8.startupSnapshot можно использовать для добавления обработчиков сериализации и десериализации пользовательских снимков состояния при запуске.

$ node --snapshot-blob snapshot.blob --build-snapshot entry.js
# This launches a process with the snapshot
$ node --snapshot-blob snapshot.blob
consolecopy

В приведенном выше примере entry.js может использовать методы интерфейса v8.startupSnapshot, чтобы указать, как сохранять сведения о пользовательских объектах в снимке при сериализации и как использовать эти сведения для синхронизации объектов при десериализации снимка. Например, если entry.js содержит следующий скрипт:

const fs = require('node:fs');
const zlib = require('node:zlib');
const path = require('node:path');
const assert = require('node:assert');

const v8 = require('node:v8');

class BookShelf {
  storage = new Map();

  // Reading a series of files from directory and store them into storage.
  constructor(directory, books) {
    for (const book of books) {
      this.storage.set(book, fs.readFileSync(path.join(directory, book)));
    }
  }

  static compressAll(shelf) {
    for (const [ book, content ] of shelf.storage) {
      shelf.storage.set(book, zlib.gzipSync(content));
    }
  }

  static decompressAll(shelf) {
    for (const [ book, content ] of shelf.storage) {
      shelf.storage.set(book, zlib.gunzipSync(content));
    }
  }
}

// __dirname here is where the snapshot script is placed
// during snapshot building time.
const shelf = new BookShelf(__dirname, [
  'book1.en_US.txt',
  'book1.es_ES.txt',
  'book2.zh_CN.txt',
]);

assert(v8.startupSnapshot.isBuildingSnapshot());
// On snapshot serialization, compress the books to reduce size.
v8.startupSnapshot.addSerializeCallback(BookShelf.compressAll, shelf);
// On snapshot deserialization, decompress the books.
v8.startupSnapshot.addDeserializeCallback(BookShelf.decompressAll, shelf);
v8.startupSnapshot.setDeserializeMainFunction((shelf) => {
  // process.env and process.argv are refreshed during snapshot
  // deserialization.
  const lang = process.env.BOOK_LANG || 'en_US';
  const book = process.argv[1];
  const name = `${book}.${lang}.txt`;
  console.log(shelf.storage.get(name));
}, shelf);
cjscopy

При запуске бинарный файл выведет данные, десериализованные из снимка, используя обновленные process.env и process.argv запущенного процесса:

$ BOOK_LANG=es_ES node --snapshot-blob snapshot.blob book1
# Prints content of book1.es_ES.txt deserialized from the snapshot.
consolecopy

В настоящее время приложение, десериализованное из пользовательского снимка, нельзя повторно сохранить в снимок, поэтому эти API доступны только приложениям, не десериализованным из пользовательского снимка.

v8.startupSnapshot.addSerializeCallback(callback[, data])

• callback <Function> Функция обратного вызова, вызываемая перед сериализацией.
• data <any> Необязательные данные, передаваемые в callback при вызове.

Добавляет функцию обратного вызова, вызываемую перед сериализацией экземпляра Node.js в снимок и его завершением. Ее можно использовать для освобождения ресурсов, которые не следует или невозможно сериализовать, либо для преобразования пользовательских данных в форму, более подходящую для сериализации.

Функции обратного вызова выполняются в порядке добавления.

v8.startupSnapshot.addDeserializeCallback(callback[, data])

• callback <Function> Функция обратного вызова, вызываемая после десериализации снимка.
• data <any> Необязательные данные, передаваемые в callback при вызове.

Добавляет функцию обратного вызова, вызываемую при десериализации экземпляра Node.js из снимка. callback и data (если они указаны) будут сериализованы в снимок; их можно использовать для повторной инициализации состояния приложения или повторного получения ресурсов, необходимых приложению при перезапуске из снимка.

Функции обратного вызова выполняются в порядке добавления.

v8.startupSnapshot.setDeserializeMainFunction(callback[, data])

• callback <Function> Функция обратного вызова, вызываемая в качестве точки входа после десериализации снимка.
• data <any> Необязательные данные, передаваемые в callback при вызове.

Задает точку входа приложения Node.js при его десериализации из снимка. Этот метод можно вызвать только один раз в скрипте создания снимка. Если он вызван, десериализованному приложению больше не нужен дополнительный скрипт точки входа для запуска: будет вызвана функция обратного вызова вместе с десериализованными данными (если они указаны). В противном случае для десериализованного приложения по-прежнему потребуется скрипт точки входа.

v8.startupSnapshot.isBuildingSnapshot()

• Возвращает: <boolean>

Возвращает true, если экземпляр Node.js запущен для создания снимка.

Класс: v8.GCProfiler

Этот API собирает данные GC в текущем потоке.

new v8.GCProfiler()

Создает новый экземпляр класса v8.GCProfiler. Этот API поддерживает синтаксис using.

profiler.start()

Начинает сбор данных GC.

profiler.stop()

Останавливает сбор данных GC и возвращает объект. Объект содержит следующие данные.

{
  "version": 1,
  "startTime": 1674059033862,
  "statistics": [
    {
      "gcType": "Scavenge",
      "beforeGC": {
        "heapStatistics": {
          "totalHeapSize": 5005312,
          "totalHeapSizeExecutable": 524288,
          "totalPhysicalSize": 5226496,
          "totalAvailableSize": 4341325216,
          "totalGlobalHandlesSize": 8192,
          "usedGlobalHandlesSize": 2112,
          "usedHeapSize": 4883840,
          "heapSizeLimit": 4345298944,
          "mallocedMemory": 254128,
          "externalMemory": 225138,
          "peakMallocedMemory": 181760
        },
        "heapSpaceStatistics": [
          {
            "spaceName": "read_only_space",
            "spaceSize": 0,
            "spaceUsedSize": 0,
            "spaceAvailableSize": 0,
            "physicalSpaceSize": 0
          }
        ]
      },
      "cost": 1574.14,
      "afterGC": {
        "heapStatistics": {
          "totalHeapSize": 6053888,
          "totalHeapSizeExecutable": 524288,
          "totalPhysicalSize": 5500928,
          "totalAvailableSize": 4341101384,
          "totalGlobalHandlesSize": 8192,
          "usedGlobalHandlesSize": 2112,
          "usedHeapSize": 4059096,
          "heapSizeLimit": 4345298944,
          "mallocedMemory": 254128,
          "externalMemory": 225138,
          "peakMallocedMemory": 181760
        },
        "heapSpaceStatistics": [
          {
            "spaceName": "read_only_space",
            "spaceSize": 0,
            "spaceUsedSize": 0,
            "spaceAvailableSize": 0,
            "physicalSpaceSize": 0
          }
        ]
      }
    }
  ],
  "endTime": 1674059036865
}
jsoncopy

Пример:

import { GCProfiler } from 'node:v8';
const profiler = new GCProfiler();
profiler.start();
setTimeout(() => {
  console.log(profiler.stop());
}, 1000);

const { GCProfiler } = require('node:v8');
const profiler = new GCProfiler();
profiler.start();
setTimeout(() => {
  console.log(profiler.stop());
}, 1000);

profiler[Symbol.dispose]()

Останавливает сбор данных GC и отбрасывает профиль.

Класс: SyncCPUProfileHandle

syncCpuProfileHandle.stop()

• Возвращает: <string>

Останавливает сбор профиля и возвращает данные профиля.

syncCpuProfileHandle[Symbol.dispose]()

Останавливает сбор профиля и отбрасывает профиль.

Класс: SyncHeapProfileHandle

syncHeapProfileHandle.stop()

• Возвращает: <string>

Останавливает сбор профиля и возвращает данные профиля.

syncHeapProfileHandle[Symbol.dispose]()

Останавливает сбор профиля и отбрасывает профиль.

Класс: CPUProfileHandle

cpuProfileHandle.stop()

• Возвращает: <Promise>

Останавливает сбор профиля, а затем возвращает Promise, который выполняется с ошибкой или данными профиля.

cpuProfileHandle[Symbol.asyncDispose]()

• Возвращает: <Promise>

Останавливает сбор профиля и отбрасывает профиль.

Класс: HeapProfileHandle

heapProfileHandle.stop()

• Возвращает: <Promise>

Останавливает сбор профиля, а затем возвращает Promise, который выполняется с ошибкой или данными профиля.

heapProfileHandle[Symbol.asyncDispose]()

• Возвращает: <Promise>

Останавливает сбор профиля и отбрасывает профиль.

v8.isStringOneByteRepresentation(content)

• content <string>
• Возвращает: <boolean>

V8 поддерживает только Latin-1/ISO-8859-1 и UTF16 в качестве внутреннего представления строки. Если для content используется Latin-1/ISO-8859-1 в качестве внутреннего представления, эта функция возвращает true; в противном случае она возвращает false.

Если этот метод возвращает false, это не означает, что строка содержит символы, отсутствующие в Latin-1/ISO-8859-1. Иногда строка Latin-1 также может быть представлена как UTF16.

import { isStringOneByteRepresentation } from 'node:v8';
import { Buffer } from 'node:buffer';

const Encoding = {
  latin1: 1,
  utf16le: 2,
};
const buffer = Buffer.alloc(100);
function writeString(input) {
  if (isStringOneByteRepresentation(input)) {
    console.log(`input: '${input}'`);
    buffer.writeUint8(Encoding.latin1);
    buffer.writeUint32LE(input.length, 1);
    buffer.write(input, 5, 'latin1');
    console.log(`decoded: '${buffer.toString('latin1', 5, 5 + input.length)}'\n`);
  } else {
    console.log(`input: '${input}'`);
    buffer.writeUint8(Encoding.utf16le);
    buffer.writeUint32LE(input.length * 2, 1);
    buffer.write(input, 5, 'utf16le');
    console.log(`decoded: '${buffer.toString('utf16le', 5, 5 + input.length * 2)}'`);
  }
}
writeString('hello');
writeString('你好');

const { isStringOneByteRepresentation } = require('node:v8');
const { Buffer } = require('node:buffer');

const Encoding = {
  latin1: 1,
  utf16le: 2,
};
const buffer = Buffer.alloc(100);
function writeString(input) {
  if (isStringOneByteRepresentation(input)) {
    console.log(`input: '${input}'`);
    buffer.writeUint8(Encoding.latin1);
    buffer.writeUint32LE(input.length, 1);
    buffer.write(input, 5, 'latin1');
    console.log(`decoded: '${buffer.toString('latin1', 5, 5 + input.length)}'\n`);
  } else {
    console.log(`input: '${input}'`);
    buffer.writeUint8(Encoding.utf16le);
    buffer.writeUint32LE(input.length * 2, 1);
    buffer.write(input, 5, 'utf16le');
    console.log(`decoded: '${buffer.toString('utf16le', 5, 5 + input.length * 2)}'`);
  }
}
writeString('hello');
writeString('你好');

v8.startCpuProfile([options])

• options <Object>
  • sampleInterval <number> Запрашиваемый интервал выборки в миллисекундах. По умолчанию: 0.
  • maxBufferSize <integer> Максимальное количество сохраняемых выборок, после достижения которого старые записи отбрасываются. По умолчанию: 4294967295.
• Возвращает: {SyncCPUProfileHandle}

Запускает профилирование ЦП и возвращает объект SyncCPUProfileHandle. Этот API поддерживает синтаксис using.

const handle = v8.startCpuProfile({ sampleInterval: 1, maxBufferSize: 10_000 });
const profile = handle.stop();
console.log(profile);
cjscopy

v8.startHeapProfile([options])

• options <Object>
  • sampleInterval <number> Средний интервал выборки в байтах. По умолчанию: 524288 (512 КиБ).
  • stackDepth <integer> Максимальная глубина стека для выборок. По умолчанию: 16.
  • forceGC <boolean> Принудительно запускать сборку мусора перед созданием профиля. По умолчанию: false.
  • includeObjectsCollectedByMajorGC <boolean> Включать объекты, собранные полной сборкой мусора. По умолчанию: false.
  • includeObjectsCollectedByMinorGC <boolean> Включать объекты, собранные частичной сборкой мусора. По умолчанию: false.
• Возвращает: {SyncHeapProfileHandle}

Запускает профилирование кучи и возвращает объект SyncHeapProfileHandle. Этот API поддерживает синтаксис using.

const v8 = require('node:v8');

const handle = v8.startHeapProfile();
const profile = handle.stop();
console.log(profile);

import v8 from 'node:v8';

const handle = v8.startHeapProfile();
const profile = handle.stop();
console.log(profile);

С пользовательскими параметрами:

const v8 = require('node:v8');

const handle = v8.startHeapProfile({
  sampleInterval: 1024,
  stackDepth: 8,
  forceGC: true,
  includeObjectsCollectedByMajorGC: true,
});
const profile = handle.stop();
console.log(profile);

import v8 from 'node:v8';

const handle = v8.startHeapProfile({
  sampleInterval: 1024,
  stackDepth: 8,
  forceGC: true,
  includeObjectsCollectedByMajorGC: true,
});
const profile = handle.stop();
console.log(profile);