Node.js v12.2.0 文档


v8(V8引擎)#

中英对照提交修改

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

const v8 = require('v8');

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

v8.cachedDataVersionTag()#

中英对照提交修改

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

v8.getHeapSpaceStatistics()#

中英对照提交修改

返回有关 V8 堆空间的统计信息,即组成 V8 堆的片段。 由于统计信息是通过 V8 的 GetHeapSpaceStatistics 函数提供的,因此可以保证堆空间的排序以及堆空间的可用性,并且可以从一个 V8 版本更改为下一个版本。

返回的值是包含以下属性的对象数组:

[
  {
    "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()#

暂无中英对照

Generates a snapshot of the current V8 heap and returns a Readable Stream that may be used to read the JSON serialized representation. This JSON stream format is intended to be used with tools such as Chrome DevTools. The JSON schema is undocumented and specific to the V8 engine, and may change from one version of V8 to the next.

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

v8.getHeapStatistics()#

中英对照提交修改

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

does_zap_garbage 是一个 0/1 布尔值,表示是否启用了 --zap_code_space 选项。 这使得 V8 用位模式覆盖堆垃圾。 RSS 占用空间(常驻内存集)会变得越来越大,因为它不断触及所有堆页面,这使得它们不太可能被操作系统交换出。

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

v8.setFlagsFromString(flags)#

查看v10.x中文文档

The v8.setFlagsFromString() method can be used to programmatically set V8 command line flags. This method should be used with care. Changing settings after the VM has started may result in unpredictable behavior, including crashes and data loss; or it may simply do nothing.

The V8 options available for a version of Node.js may be determined by running node --v8-options.

Usage:

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

v8.writeHeapSnapshot([filename])#

暂无中英对照

  • filename <string> The file path where the V8 heap snapshot is to be saved. If not specified, a file name with the pattern 'Heap-${yyyymmdd}-${hhmmss}-${pid}-${thread_id}.heapsnapshot' will be generated, where {pid} will be the PID of the Node.js process, {thread_id} will be 0 when writeHeapSnapshot() is called from the main Node.js thread or the id of a worker thread.
  • Returns: <string> The filename where the snapshot was saved.

Generates a snapshot of the current V8 heap and writes it to a JSON file. This file is intended to be used with tools such as Chrome DevTools. The JSON schema is undocumented and specific to the V8 engine, and may change from one version of V8 to the next.

A heap snapshot is specific to a single V8 isolate. When using Worker Threads, a heap snapshot generated from the main thread will not contain any information about the workers, and vice versa.

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());
    }
  });
}

序列化的 API#

暂无中英对照

稳定性: 1 - 试验

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

This API is under development, and changes (including incompatible changes to the API or wire format) may occur until this warning is removed.

v8.serialize(value)#

暂无中英对照

Uses a DefaultSerializer to serialize value into a buffer.

v8.deserialize(buffer)#

暂无中英对照

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

暂无中英对照

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

暂无中英对照

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

暂无中英对照

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

serializer.writeUint64(hi, lo)#

暂无中英对照

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

暂无中英对照

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

serializer.writeRawBytes(buffer)#

暂无中英对照

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

暂无中英对照

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

暂无中英对照

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

暂无中英对照

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

暂无中英对照

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

v8.Deserializer 类#

暂无中英对照

new Deserializer(buffer)#

暂无中英对照

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

暂无中英对照

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

暂无中英对照

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

暂无中英对照

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

deserializer.readUint64()#

暂无中英对照

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

暂无中英对照

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

deserializer.readRawBytes(length)#

暂无中英对照

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.