目录

• v8（V8引擎）
  • v8.cachedDataVersionTag()
  • v8.getHeapSpaceStatistics()
  • v8.getHeapSnapshot()
  • v8.getHeapStatistics()
  • v8.getHeapCodeStatistics()
  • v8.setFlagsFromString(flags)
  • v8.writeHeapSnapshot([filename])
  • 序列化的 API
    • v8.serialize(value)
    • v8.deserialize(buffer)
    • v8.Serializer 类
      • new Serializer()
      • serializer.writeHeader()
      • serializer.writeValue(value)
      • serializer.releaseBuffer()
      • serializer.transferArrayBuffer(id, arrayBuffer)
      • serializer.writeUint32(value)
      • serializer.writeUint64(hi, lo)
      • serializer.writeDouble(value)
      • serializer.writeRawBytes(buffer)
      • serializer._writeHostObject(object)
      • serializer._getDataCloneError(message)
      • serializer._getSharedArrayBufferId(sharedArrayBuffer)
      • serializer._setTreatArrayBufferViewsAsHostObjects(flag)
    • v8.Deserializer 类
      • new Deserializer(buffer)
      • deserializer.readHeader()
      • deserializer.readValue()
      • deserializer.transferArrayBuffer(id, arrayBuffer)
      • deserializer.getWireFormatVersion()
      • deserializer.readUint32()
      • deserializer.readUint64()
      • deserializer.readDouble()
      • deserializer.readRawBytes(length)
      • deserializer._readHostObject()
    • v8.DefaultSerializer 类
    • v8.DefaultDeserializer 类

v8（V8引擎）#

源代码: lib/v8.js

v8 模块暴露了特定于内置到 Node.js 二进制文件中的 V8 版本的 API。 可以使用以下方式访问它：

const v8 = require('v8');

API 和实现随时可能发生变化。

v8.cachedDataVersionTag()#

• 返回: <integer>

返回一个整数，表示从 V8 版本、命令行标志、以及检测到的 CPU 特性派生的版本标记。 这对于判断 vm.Script 的 cachedData buffer 是否与此 V8 实例兼容非常有用。

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

v8.getHeapSnapshot()#

• 返回: <stream.Readable> 包含 V8 堆快照的可读流。

生成当前 V8 堆的快照，并返回可读流，该可读流可用于读取 JSON 序列化表示。 此 JSON 流格式旨在与 Chrome DevTools 等工具一起使用。 JSON 模式未记录且特定于V8引擎，并且可能从 V8 的一个版本更改为下一个版本。

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

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>

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()#

• 返回: <Object>

返回具有以下属性的对象：

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

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

v8.setFlagsFromString(flags)#

• flags <string>

v8.setFlagsFromString() 方法可用于以编程方式设置 V8 的命令行标志。 应谨慎使用此方法。 虚拟机启动后更改设置可能会导致不可预测的行为，包括崩溃和数据丢失，或者它可能根本就什么都不做。

可以通过运行 node --v8-options 来检测可用于 Node.js 版本的 V8 选项。

用法:

// 将 GC 事件打印到 stdout 一分钟。
const v8 = require('v8');
v8.setFlagsFromString('--trace_gc');
setTimeout(() => { v8.setFlagsFromString('--notrace_gc'); }, 60e3);

v8.writeHeapSnapshot([filename])#

• filename <string> 要保存 V8 堆快照的文件路径。 如果未指定，则将会生成具有 'Heap-${yyyymmdd}-${hhmmss}-${pid}-${thread_id}.heapsnapshot' 模式的文件名， 其中 {pid} 将会是 Node.js 进程的 PID， {thread_id} 将会为 0（当从主 Node.js 线程调用 writeHeapSnapshot() 时）或工作线程的 id。
• 返回: <string> 保存快照的文件名。

生成当前 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(`工作线程的堆转储: ${filename}`);
    // 获取主线程的堆转储。
    console.log(`主线程的堆转储: ${writeHeapSnapshot()}`);
  });

  // 通知工作线程创建一个堆转储。
  worker.postMessage('heapdump');
} else {
  parentPort.once('message', (message) => {
    if (message === 'heapdump') {
      // 为工作线程生成一个堆转储，并返回文件名到父线程。
      parentPort.postMessage(writeHeapSnapshot());
    }
  });
}

序列化的 API#

The serialization API provides means of serializing JavaScript values in a way that is compatible with the HTML structured clone algorithm.

The format is backward-compatible (i.e. safe to store to disk). Equal JavaScript values may result in different serialized output.

v8.serialize(value)#

• value <any>
• Returns: <Buffer>

Uses a DefaultSerializer to serialize value into a buffer.

v8.deserialize(buffer)#

• buffer <Buffer> | <TypedArray> | <DataView> A buffer returned by serialize().

Uses a DefaultDeserializer with default options to read a JS value from a buffer.

v8.Serializer 类#

new Serializer()#

Creates a new Serializer object.

serializer.writeHeader()#

Writes out a header, which includes the serialization format version.

serializer.writeValue(value)#

• value <any>

Serializes a JavaScript value and adds the serialized representation to the internal buffer.

This throws an error if value cannot be serialized.

serializer.releaseBuffer()#

• Returns: <Buffer>

Returns the stored internal buffer. This serializer should not be used once the buffer is released. Calling this method results in undefined behavior if a previous write has failed.

serializer.transferArrayBuffer(id, arrayBuffer)#

• id <integer> A 32-bit unsigned integer.
• arrayBuffer <ArrayBuffer> An ArrayBuffer instance.

Marks an ArrayBuffer as having its contents transferred out of band. Pass the corresponding ArrayBuffer in the deserializing context to deserializer.transferArrayBuffer().

serializer.writeUint32(value)#

• value <integer>

Write a raw 32-bit unsigned integer. For use inside of a custom serializer._writeHostObject().

serializer.writeUint64(hi, lo)#

• hi <integer>
• lo <integer>

Write a raw 64-bit unsigned integer, split into high and low 32-bit parts. For use inside of a custom serializer._writeHostObject().

serializer.writeDouble(value)#

• value <number>

Write a JS number value. For use inside of a custom serializer._writeHostObject().

serializer.writeRawBytes(buffer)#

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

Write raw bytes into the serializer’s internal buffer. The deserializer will require a way to compute the length of the buffer. For use inside of a custom serializer._writeHostObject().

serializer._writeHostObject(object)#

• object <Object>

This method is called to write some kind of host object, i.e. an object created by native C++ bindings. If it is not possible to serialize object, a suitable exception should be thrown.

This method is not present on the Serializer class itself but can be provided by subclasses.

serializer._getDataCloneError(message)#

• message <string>

This method is called to generate error objects that will be thrown when an object can not be cloned.

This method defaults to the Error constructor and can be overridden on subclasses.

serializer._getSharedArrayBufferId(sharedArrayBuffer)#

• sharedArrayBuffer <SharedArrayBuffer>

This method is called when the serializer is going to serialize a SharedArrayBuffer object. It must return an unsigned 32-bit integer ID for the object, using the same ID if this SharedArrayBuffer has already been serialized. When deserializing, this ID will be passed to deserializer.transferArrayBuffer().

If the object cannot be serialized, an exception should be thrown.

This method is not present on the Serializer class itself but can be provided by subclasses.

serializer._setTreatArrayBufferViewsAsHostObjects(flag)#

• flag <boolean> Default: false

Indicate whether to treat TypedArray and DataView objects as host objects, i.e. pass them to serializer._writeHostObject().

v8.Deserializer 类#

new Deserializer(buffer)#

• buffer <Buffer> | <TypedArray> | <DataView> A buffer returned by serializer.releaseBuffer().

Creates a new Deserializer object.

deserializer.readHeader()#

Reads and validates a header (including the format version). May, for example, reject an invalid or unsupported wire format. In that case, an Error is thrown.

deserializer.readValue()#

Deserializes a JavaScript value from the buffer and returns it.

deserializer.transferArrayBuffer(id, arrayBuffer)#

• id <integer> A 32-bit unsigned integer.
• arrayBuffer <ArrayBuffer> | <SharedArrayBuffer> An ArrayBuffer instance.

Marks an ArrayBuffer as having its contents transferred out of band. Pass the corresponding ArrayBuffer in the serializing context to serializer.transferArrayBuffer() (or return the id from serializer._getSharedArrayBufferId() in the case of SharedArrayBuffers).

deserializer.getWireFormatVersion()#

• Returns: <integer>

Reads the underlying wire format version. Likely mostly to be useful to legacy code reading old wire format versions. May not be called before .readHeader().

deserializer.readUint32()#

• Returns: <integer>

Read a raw 32-bit unsigned integer and return it. For use inside of a custom deserializer._readHostObject().

deserializer.readUint64()#

• Returns: <integer[]>

Read a raw 64-bit unsigned integer and return it as an array [hi, lo] with two 32-bit unsigned integer entries. For use inside of a custom deserializer._readHostObject().

deserializer.readDouble()#

• Returns: <number>

Read a JS number value. For use inside of a custom deserializer._readHostObject().

deserializer.readRawBytes(length)#

• length <integer>
• Returns: <Buffer>

Read raw bytes from the deserializer’s internal buffer. The length parameter must correspond to the length of the buffer that was passed to serializer.writeRawBytes(). For use inside of a custom deserializer._readHostObject().

deserializer._readHostObject()#

This method is called to read some kind of host object, i.e. an object that is created by native C++ bindings. If it is not possible to deserialize the data, a suitable exception should be thrown.

This method is not present on the Deserializer class itself but can be provided by subclasses.

v8.DefaultSerializer 类#

A subclass of Serializer that serializes TypedArray (in particular Buffer) and DataView objects as host objects, and only stores the part of their underlying ArrayBuffers that they are referring to.

v8.DefaultDeserializer 类#

A subclass of Deserializer corresponding to the format written by DefaultSerializer.