Node.js v8.x 中文文档

V8#

v8 模块暴露了特定于[V8][]版本内置到 Node.js 二进制文件中的API. 通过以下方式使用：

const v8 = require('v8');

注意: APIs 和实现可能在任何时间变动。

v8.cachedDataVersionTag()#

新增于: v8.0.0

返回一个表示从V8版本，命令行标志和已检测到的CPU功能派生的“version tag”的整数。这对于判断[vm.Script][] cachedData是否兼容当前v8实例非常有用。

v8.getHeapSpaceStatistics()#

版本历史
版本变更
v7.5.0

Support values exceeding the 32-bit unsigned integer range.

v6.0.0

新增于: v6.0.0

返回关于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.getHeapStatistics()#

版本历史
版本变更
v7.5.0

新增对超过32位的非符号整型的支持

v7.2.0

新增 malloced_memory, peak_malloced_memory, 和 does_zap_garbage.

v1.0.0

新增于: v1.0.0

返回拥有以下参数的对象：

does_zap_garbage是个0/1式布尔值，它凸显是否设置了--zap_code_space选项。若为真，那么V8引擎会用一个位模式来覆盖堆中的垃圾。如此，RSS(常驻内存集)会变得越来越大，因为V8会一直征用所有的堆页，从而让他们更难被操作系统交换掉。

For example:

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

新增于: v1.0.0

v8.setFlagsFromString()可以被用来在脚本中设置V8引擎的命令行标识。此方法应该谨慎使用。在虚拟机已经运行后修改其设置可能会造成不可预测的结果，包括崩溃和数据丢失，或者一点作用也没有。

针对一个特定版本的Node.js，可供其使用的V8选项可以通过运行node --v8-options来获取。一个非官方的，由社区维护的选项清单及其效果可参见[这里][here]。

用法:

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

Serialization API#

稳定性: 1 - 实验性质

序列化API提供了一系列用于序列化JavaScript值的方法，它们兼容于[HTML structured clone algorithm][]。 格式是向下兼容的（可以安心存储于硬盘中）。

注意: 此API正在开发中，任何变化（包括不兼容的API或者传输格式）可能会随时发生直到此警告被移除。

v8.serialize(value)#

使用[DefaultSerializer][]来序列化value到一个缓冲区中。

v8.deserialize(buffer)#

用默认配置来执行[DefaultDeserializer][]从而从一个缓冲区中读取一个JS值

class: v8.Serializer#

new Serializer()#

创建一个新的Serializer对象。

serializer.writeHeader()#

写出一个包含序列化格式版本的头文件

serializer.writeValue(value)#

序列化一个JavaScript值并将结果加入内部的缓冲区。

如果value不能被序列化则抛出错误。

serializer.releaseBuffer()#

返回存储里的内部缓冲区。若缓冲区已经被释放则不应该使用此序列化机制。如果之前的一次写入操作失败，那么执行此方法会造成不可预知的行为。

serializer.transferArrayBuffer(id, arrayBuffer)#

标记一个ArrayBuffer, 表明它的内容正在被带外传输中。同时将ArrayBuffer包裹于一个反序列化的上下文内，之后将结果传入[deserializer.transferArrayBuffer()][]中。

serializer.writeUint32(value)#

写出一个原始32位无符号整型。 此方法在一个自定义的[serializer._writeHostObject()][]中使用.

serializer.writeUint64(hi, lo)#

写出一个原始64位无符号整型，会被拆分成高32位和低32位两部分。 此方法用于一个自定义的[serializer._writeHostObject()][].

serializer.writeDouble(value)#

写出一个JS的number值。 从方法用于一个自定义的[serializer._writeHostObject()][].

serializer.writeRawBytes(buffer)#

将原始字节写入序列化机制的内部缓冲区中。反序列化机制会有对应的方法来获得缓冲区的长度。 此方法用于一个自定义的[serializer._writeHostObject()][]中。

serializer._writeHostObject(object)#

此方法用来写出某种宿主对象，进一步说，是由绑定的原生C++代码所生成的一个对象。 如果无法序列化object，那么一个恰当的异常会被抛出。

此方法在Serializer对象本身是不存在的，但可在其子类中提供。

serializer._getDataCloneError(message)#

当一个对象无法被克隆时，会使用此方法来生成待抛出的错误对象。

此方法默认为[Error][]的构造函数，可以在子类中被覆盖。

serializer._getSharedArrayBufferId(sharedArrayBuffer)#

当序列化机制将要序列化一个ShareArrayBuffer对象时会调用此方法。它必须为这对象返回一个32位无符号整型的ID，但若这个对象已被序列化过，则返回上一次序列化时所分配的ID。这个ID会在对象被反序列化时传入[deserializer.transferArrayBuffer()][]中。

如果对象不能被序列化，则抛出异常。

Serializer类本身不包含此方法，但可以在其子类中设置它。

serializer._setTreatArrayBufferViewsAsHostObjects(flag)#

表明是否视TypedArray，DataView对象为宿主对象，也就是说，是否能将他们传入[serializer._writeHostObject()][]中。

默认以上对象非宿主对象。

class: v8.Deserializer#

new Deserializer(buffer)#

生成一个新的Deserializer对象。

deserializer.readHeader()#

读取并验证一个头文件（包含格式信息）。 验证在某些情况下有可能不会通过，比如传输格式不合格或者不被支持。若发生上述情况，那么一个Error会被抛出。

deserializer.readValue()#

从缓冲区中反序列化一个JavaScript值，并返回它。

deserializer.transferArrayBuffer(id, arrayBuffer)#

标记一个ArrayBuffer, 表明它的内容正在被带外传输中。同时将ArrayBuffer包裹于一个序列化的上下文内，之后将结果传入[serializer.transferArrayBuffer()][]中（当arrayBuffer是ShareArrayBuffer实例时，返回[serializer._getSharedArrayBufferId()][]产生的id）

deserializer.getWireFormatVersion()#

读取底层的传输格式的版本。很可能有助于遗留代码来读取旧的传输格式版本。不可在.readHeader()之前调用此方法。

deserializer.readUint32()#

读取并返回一个原始32位无符号整型。 用于一个自定义的[deserializer._readHostObject()][]。

deserializer.readUint64()#

读取一个原始64位无符号整型，将其拆分成一个包含两个32位无符号整型的[hi, lo]数组，并返回此数组。 用于一个自定义的[deserializer._readHostObject()][]。

deserializer.readDouble()#

读取一个JSnumber值。 用于一个自定义的[deserializer._readHostObject()][]。

deserializer.readRawBytes(length)#

从反序列化机制的内部缓冲区中读取原始字节。length必须和传入[serializer.writeRawBytes()][]中的缓冲区的长度相符。 用于一个自定义的[serializer.writeRawBytes()][]。

deserializer._readHostObject()#

此方法用来写出某种宿主对象，进一步说，是由绑定的原生C++代码所生成的一个对象。 如果无法序列化数据，那么一个恰当的异常会被抛出。

此方法在Deserializer对象本身上是不存在的，但可有其子类提供。

class: v8.DefaultSerializer#

[Serializer][]的子类，用来将TypedArray(尤其是[Buffer][])和Dataview序列化成一个宿主对象，并且对于它们底层的ArrayBuffer，只有被它们实际指向的部分会被存储起来。

class: v8.DefaultDeserializer#

[Deserializer][]的一个子类，根据[DefaultSerializer][]的格式而定。 [Buffer]: buffer.html [DefaultDeserializer]: #v8_class_v8_defaultdeserializer [DefaultSerializer]: #v8_class_v8_defaultserializer [Deserializer]: #v8_class_v8_deserializer [Error]: errors.html#errors_class_error [Serializer]: #v8_class_v8_serializer [deserializer._readHostObject()]: #v8_deserializer_readhostobject [deserializer.transferArrayBuffer()]: #v8_deserializer_transferarraybuffer_id_arraybuffer [serialize()]: #v8_v8_serialize_value [serializer._getSharedArrayBufferId()]: #v8_serializer_getsharedarraybufferid_sharedarraybuffer [serializer._writeHostObject()]: #v8_serializer_writehostobject_object [serializer.releaseBuffer()]: #v8_serializer_releasebuffer [serializer.transferArrayBuffer()]: #v8_serializer_transferarraybuffer_id_arraybuffer [serializer.writeRawBytes()]: #v8_serializer_writerawbytes_buffer [HTML structured clone algorithm]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm [V8]: https://developers.google.com/v8/ [vm.Script]: vm.html#vm_new_vm_script_code_options [here]: https://github.com/thlorenz/v8-flags/blob/master/flags-0.11.md [GetHeapSpaceStatistics]: https://v8docs.nodesource.com/node-8.0/d5/dda/classv8_1_1_isolate.html#ac673576f24fdc7a33378f8f57e1d13a4