V8

Исходный код: lib/v8.js

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

const v8 = require('v8');

API и реализация могут быть изменены в любое время.

v8.cachedDataVersionTag()

• Возвращает: <целое число>

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

v8.getHeapSpaceStatistics()

• Возвращает: <Массив объектов>

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

Возвращаемое значение — массив объектов, содержащих следующие свойства:

• space_name <строка>
• space_size <число>
• space_used_size <число>
• space_available_size <число>
• physical_space_size <число>

[
  {
    "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
  }
]

v8.getHeapSnapshot()

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

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

const stream = v8.getHeapSnapshot();
stream.pipe(process.stdout);

v8.getHeapStatistics()

• Возвращает: <Объект>

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

• total_heap_size <число>
• total_heap_size_executable <число>
• total_physical_size <число>
• total_available_size <число>
• used_heap_size <число>
• heap_size_limit <число>
• malloced_memory <число>
• peak_malloced_memory <число>
• does_zap_garbage <число>
• number_of_native_contexts <число>
• number_of_detached_contexts <число>

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

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

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

{
  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
}

v8.getHeapCodeStatistics()

• Возвращает: <Объект>

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

• code_and_metadata_size <число>
• bytecode_and_metadata_size <число>
• external_script_source_size <число>

{
  code_and_metadata_size: 212208,
  bytecode_and_metadata_size: 161368,
  external_script_source_size: 1410794
}

v8.setFlagsFromString(flags)

• flags <строка>

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

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

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

// Print GC events to stdout for one minute.
const v8 = require('v8');
v8.setFlagsFromString('--trace_gc');
setTimeout(() => { v8.setFlagsFromString('--notrace_gc'); }, 60e3);

v8.takeCoverage()

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

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

v8.stopCoverage()

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

v8.writeHeapSnapshot([filename])

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

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

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

const { writeHeapSnapshot } = require('v8');
const {
  Worker,
  isMainThread,
  parentPort
} = require('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());
    }
  });
}

Serialization API

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

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

v8.serialize(value)

• value <любой>
• Возвращает: <Буфер>

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

v8.deserialize(buffer)

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

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

Класс: v8.Serializer

new Serializer()

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

serializer.writeHeader()

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

serializer.writeValue(value)

• value <любой>

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

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

serializer.releaseBuffer()

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

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

serializer.transferArrayBuffer(id, arrayBuffer)

• id <целое без знака 32 бита> Целое без знака 32 бита.
• arrayBuffer <ArrayBuffer> Экземпляр ArrayBuffer.

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

serializer.writeUint32(value)

• value <целое без знака>

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

serializer.writeUint64(hi, lo)

• hi <целое без знака>
• lo <целое без знака>

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

serializer.writeDouble(value)

• value <число>

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

serializer.writeRawBytes(buffer)

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

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

serializer._writeHostObject(object)

• object <Объект>

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

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

serializer._getDataCloneError(message)

• message <строка>

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

Этот метод по умолчанию использует конструктор Error и может быть переопределён в подклассах.

serializer._getSharedArrayBufferId(sharedArrayBuffer)

• sharedArrayBuffer <SharedArrayBuffer>

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

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

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

serializer._setTreatArrayBufferViewsAsHostObjects(flag)

• flag <булево> По умолчанию: 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 <целое без знака 32 бита> Целое без знака 32 бита.
• arrayBuffer <ArrayBuffer> | <SharedArrayBuffer> Экземпляр ArrayBuffer.

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

deserializer.getWireFormatVersion()

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

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

deserializer.readUint32()

• Возвращает: <целое без знака>

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

deserializer.readUint64()

• Возвращает: <массив целых>

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

deserializer.readDouble()

• Возвращает: <число>

Считывает значение JS number. Для использования внутри пользовательского метода deserializer._readHostObject().

deserializer.readRawBytes(length)

• length <целое без знака>
• Возвращает: <Buffer>

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

deserializer._readHostObject()

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

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

Класс: v8.DefaultSerializer

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

Класс: v8.DefaultDeserializer

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