From 1fde98bb4fa5cab0d060994768ebd055ce6fbf2c Mon Sep 17 00:00:00 2001 From: Anna Henningsen Date: Thu, 26 Jan 2017 21:38:11 -0800 Subject: v8: expose new V8 serialization API MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Expose the new serialization API that was added in V8 5.5 to userland. The JS API is virtually a direct copy of what V8 provides on the C++ level. This is useful Node as a possible replacement for some internals that currently use JSON, like IPC, but is likely to be useful to general userland code as well. PR-URL: https://github.com/nodejs/node/pull/11048 Reviewed-By: Michaël Zasso Reviewed-By: Ben Noordhuis --- doc/api/v8.md | 251 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 251 insertions(+) (limited to 'doc/api/v8.md') diff --git a/doc/api/v8.md b/doc/api/v8.md index 173d0abeef..8d5d428e56 100644 --- a/doc/api/v8.md +++ b/doc/api/v8.md @@ -157,3 +157,254 @@ setTimeout(function() { v8.setFlagsFromString('--notrace_gc'); }, 60e3); [`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-5.0/d5/dda/classv8_1_1_isolate.html#ac673576f24fdc7a33378f8f57e1d13a4 + +## Serialization API + +> Stability: 1 - Experimental + +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). + +*Note*: 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) + + +* Returns: {Buffer} + +Uses a [`DefaultSerializer`][] to serialize `value` into a buffer. + +### v8.deserialize(buffer) + + +* `buffer` {Buffer|Uint8Array} A buffer returned by [`serialize()`][]. + +Uses a [`DefaultDeserializer`][] with default options to read a JS value +from a buffer. + +### class: 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) + +* `id` {integer} A 32-bit unsigned integer. +* `arrayBuffer` {ArrayBuffer} An `ArrayBuffer` instance. + +Marks an `ArrayBuffer` as havings 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|Uint8Array} + +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 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} + +Indicate whether to treat `TypedArray` and `DataView` objects as +host objects, i.e. pass them to [`serializer._writeHostObject`][]. + +The default is not to treat those objects as host objects. + +### class: v8.Deserializer + + +#### new Deserializer(buffer) + +* `buffer` {Buffer|Uint8Array} 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 havings 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 `SharedArrayBuffer`s). + +#### 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: {Array} + +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) + +* 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. + +### class: 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 `ArrayBuffer`s that they are referring to. + +### class: v8.DefaultDeserializer + + +A subclass of [`Deserializer`][] corresponding to the format written by +[`DefaultSerializer`][]. + +[`Buffer`]: buffer.html +[`Error`]: errors.html#errors_class_error +[`deserializer.transferArrayBuffer()`]: #v8_deserializer_transferarraybuffer_id_arraybuffer +[`deserializer._readHostObject()`]: #v8_deserializer_readhostobject +[`serializer.transferArrayBuffer()`]: #v8_serializer_transferarraybuffer_id_arraybuffer +[`serializer.releaseBuffer()`]: #v8_serializer_releasebuffer +[`serializer.writeRawBytes()`]: #v8_serializer_writerawbytes_buffer +[`serializer._writeHostObject()`]: #v8_serializer_writehostobject_object +[`serializer._getSharedArrayBufferId()`]: #v8_serializer_getsharedarraybufferid_sharedarraybuffer +[`Serializer`]: #v8_class_v8_serializer +[`Deserializer`]: #v8_class_v8_deserializer +[`DefaultSerializer`]: #v8_class_v8_defaultserializer +[`DefaultDeserializer`]: #v8_class_v8_defaultdeserializer +[`serialize()`]: #v8_v8_serialize_value +[HTML structured clone algorithm]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm -- cgit v1.2.3