V8 API Reference, 7.2.502.16 (for Deno 0.2.4)
value-serializer.h
1 // Copyright 2016 the V8 project authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4 
5 #ifndef V8_VALUE_SERIALIZER_H_
6 #define V8_VALUE_SERIALIZER_H_
7 
8 #include <cstdint>
9 #include <vector>
10 
11 #include "include/v8.h"
12 #include "src/base/compiler-specific.h"
13 #include "src/base/macros.h"
14 #include "src/identity-map.h"
15 #include "src/maybe-handles.h"
16 #include "src/message-template.h"
17 #include "src/vector.h"
18 #include "src/zone/zone.h"
19 
20 namespace v8 {
21 namespace internal {
22 
23 class BigInt;
24 class HeapNumber;
25 class Isolate;
26 class JSArrayBuffer;
27 class JSArrayBufferView;
28 class JSDate;
29 class JSMap;
30 class JSRegExp;
31 class JSSet;
32 class JSValue;
33 class MutableHeapNumber;
34 class Object;
35 class Oddball;
36 class Smi;
37 class WasmMemoryObject;
38 class WasmModuleObject;
39 
40 enum class SerializationTag : uint8_t;
41 
49  public:
51  ~ValueSerializer();
52 
53  /*
54  * Writes out a header, which includes the format version.
55  */
56  void WriteHeader();
57 
58  /*
59  * Serializes a V8 object into the buffer.
60  */
61  Maybe<bool> WriteObject(Handle<Object> object) V8_WARN_UNUSED_RESULT;
62 
63  /*
64  * Returns the stored data. This serializer should not be used once the buffer
65  * is released. The contents are undefined if a previous write has failed.
66  */
67  std::vector<uint8_t> ReleaseBuffer();
68 
69  /*
70  * Returns the buffer, allocated via the delegate, and its size.
71  * Caller assumes ownership of the buffer.
72  */
73  std::pair<uint8_t*, size_t> Release();
74 
75  /*
76  * Marks an ArrayBuffer as havings its contents transferred out of band.
77  * Pass the corresponding JSArrayBuffer in the deserializing context to
78  * ValueDeserializer::TransferArrayBuffer.
79  */
80  void TransferArrayBuffer(uint32_t transfer_id,
81  Handle<JSArrayBuffer> array_buffer);
82 
83  /*
84  * Publicly exposed wire format writing methods.
85  * These are intended for use within the delegate's WriteHostObject method.
86  */
87  void WriteUint32(uint32_t value);
88  void WriteUint64(uint64_t value);
89  void WriteRawBytes(const void* source, size_t length);
90  void WriteDouble(double value);
91 
92  /*
93  * Indicate whether to treat ArrayBufferView objects as host objects,
94  * i.e. pass them to Delegate::WriteHostObject. This should not be
95  * called when no Delegate was passed.
96  *
97  * The default is not to treat ArrayBufferViews as host objects.
98  */
99  void SetTreatArrayBufferViewsAsHostObjects(bool mode);
100 
101  private:
102  // Managing allocations of the internal buffer.
103  Maybe<bool> ExpandBuffer(size_t required_capacity);
104 
105  // Writing the wire format.
106  void WriteTag(SerializationTag tag);
107  template <typename T>
108  void WriteVarint(T value);
109  template <typename T>
110  void WriteZigZag(T value);
111  void WriteOneByteString(Vector<const uint8_t> chars);
112  void WriteTwoByteString(Vector<const uc16> chars);
113  void WriteBigIntContents(BigInt* bigint);
114  Maybe<uint8_t*> ReserveRawBytes(size_t bytes);
115 
116  // Writing V8 objects of various kinds.
117  void WriteOddball(Oddball* oddball);
118  void WriteSmi(Smi smi);
119  void WriteHeapNumber(HeapNumber* number);
120  void WriteMutableHeapNumber(MutableHeapNumber* number);
121  void WriteBigInt(BigInt* bigint);
122  void WriteString(Handle<String> string);
123  Maybe<bool> WriteJSReceiver(Handle<JSReceiver> receiver)
124  V8_WARN_UNUSED_RESULT;
125  Maybe<bool> WriteJSObject(Handle<JSObject> object) V8_WARN_UNUSED_RESULT;
126  Maybe<bool> WriteJSObjectSlow(Handle<JSObject> object) V8_WARN_UNUSED_RESULT;
127  Maybe<bool> WriteJSArray(Handle<JSArray> array) V8_WARN_UNUSED_RESULT;
128  void WriteJSDate(JSDate* date);
129  Maybe<bool> WriteJSValue(Handle<JSValue> value) V8_WARN_UNUSED_RESULT;
130  void WriteJSRegExp(JSRegExp* regexp);
131  Maybe<bool> WriteJSMap(Handle<JSMap> map) V8_WARN_UNUSED_RESULT;
132  Maybe<bool> WriteJSSet(Handle<JSSet> map) V8_WARN_UNUSED_RESULT;
133  Maybe<bool> WriteJSArrayBuffer(Handle<JSArrayBuffer> array_buffer)
134  V8_WARN_UNUSED_RESULT;
135  Maybe<bool> WriteJSArrayBufferView(JSArrayBufferView* array_buffer);
136  Maybe<bool> WriteWasmModule(Handle<WasmModuleObject> object)
137  V8_WARN_UNUSED_RESULT;
138  Maybe<bool> WriteWasmMemory(Handle<WasmMemoryObject> object)
139  V8_WARN_UNUSED_RESULT;
140  Maybe<bool> WriteHostObject(Handle<JSObject> object) V8_WARN_UNUSED_RESULT;
141 
142  /*
143  * Reads the specified keys from the object and writes key-value pairs to the
144  * buffer. Returns the number of keys actually written, which may be smaller
145  * if some keys are not own properties when accessed.
146  */
147  Maybe<uint32_t> WriteJSObjectPropertiesSlow(
148  Handle<JSObject> object, Handle<FixedArray> keys) V8_WARN_UNUSED_RESULT;
149 
150  /*
151  * Asks the delegate to handle an error that occurred during data cloning, by
152  * throwing an exception appropriate for the host.
153  */
154  void ThrowDataCloneError(MessageTemplate template_index);
155  V8_NOINLINE void ThrowDataCloneError(MessageTemplate template_index,
156  Handle<Object> arg0);
157 
158  Maybe<bool> ThrowIfOutOfMemory();
159 
160  Isolate* const isolate_;
161  v8::ValueSerializer::Delegate* const delegate_;
162  uint8_t* buffer_ = nullptr;
163  size_t buffer_size_ = 0;
164  size_t buffer_capacity_ = 0;
165  bool treat_array_buffer_views_as_host_objects_ = false;
166  bool out_of_memory_ = false;
167  Zone zone_;
168 
169  // To avoid extra lookups in the identity map, ID+1 is actually stored in the
170  // map (checking if the used identity is zero is the fast way of checking if
171  // the entry is new).
173  uint32_t next_id_ = 0;
174 
175  // A similar map, for transferred array buffers.
176  IdentityMap<uint32_t, ZoneAllocationPolicy> array_buffer_transfer_map_;
177 
178  DISALLOW_COPY_AND_ASSIGN(ValueSerializer);
179 };
180 
181 /*
182  * Deserializes values from data written with ValueSerializer, or a compatible
183  * implementation.
184  */
186  public:
190 
191  /*
192  * Runs version detection logic, which may fail if the format is invalid.
193  */
194  Maybe<bool> ReadHeader() V8_WARN_UNUSED_RESULT;
195 
196  /*
197  * Reads the underlying wire format version. Likely mostly to be useful to
198  * legacy code reading old wire format versions. Must be called after
199  * ReadHeader.
200  */
201  uint32_t GetWireFormatVersion() const { return version_; }
202 
203  /*
204  * Deserializes a V8 object from the buffer.
205  */
206  MaybeHandle<Object> ReadObject() V8_WARN_UNUSED_RESULT;
207 
208  /*
209  * Reads an object, consuming the entire buffer.
210  *
211  * This is required for the legacy "version 0" format, which did not allow
212  * reference deduplication, and instead relied on a "stack" model for
213  * deserializing, with the contents of objects and arrays provided first.
214  */
215  MaybeHandle<Object> ReadObjectUsingEntireBufferForLegacyFormat()
216  V8_WARN_UNUSED_RESULT;
217 
218  /*
219  * Accepts the array buffer corresponding to the one passed previously to
220  * ValueSerializer::TransferArrayBuffer.
221  */
222  void TransferArrayBuffer(uint32_t transfer_id,
223  Handle<JSArrayBuffer> array_buffer);
224 
225  /*
226  * Publicly exposed wire format writing methods.
227  * These are intended for use within the delegate's WriteHostObject method.
228  */
229  bool ReadUint32(uint32_t* value) V8_WARN_UNUSED_RESULT;
230  bool ReadUint64(uint64_t* value) V8_WARN_UNUSED_RESULT;
231  bool ReadDouble(double* value) V8_WARN_UNUSED_RESULT;
232  bool ReadRawBytes(size_t length, const void** data) V8_WARN_UNUSED_RESULT;
233  void set_expect_inline_wasm(bool expect_inline_wasm) {
234  expect_inline_wasm_ = expect_inline_wasm;
235  }
236 
237  private:
238  // Reading the wire format.
239  Maybe<SerializationTag> PeekTag() const V8_WARN_UNUSED_RESULT;
240  void ConsumeTag(SerializationTag peeked_tag);
241  Maybe<SerializationTag> ReadTag() V8_WARN_UNUSED_RESULT;
242  template <typename T>
243  Maybe<T> ReadVarint() V8_WARN_UNUSED_RESULT;
244  template <typename T>
245  Maybe<T> ReadZigZag() V8_WARN_UNUSED_RESULT;
246  Maybe<double> ReadDouble() V8_WARN_UNUSED_RESULT;
247  Maybe<Vector<const uint8_t>> ReadRawBytes(int size) V8_WARN_UNUSED_RESULT;
248  bool expect_inline_wasm() const { return expect_inline_wasm_; }
249 
250  // Reads a string if it matches the one provided.
251  // Returns true if this was the case. Otherwise, nothing is consumed.
252  bool ReadExpectedString(Handle<String> expected) V8_WARN_UNUSED_RESULT;
253 
254  // Like ReadObject, but skips logic for special cases in simulating the
255  // "stack machine".
256  MaybeHandle<Object> ReadObjectInternal() V8_WARN_UNUSED_RESULT;
257 
258  // Reads a string intended to be part of a more complicated object.
259  // Before v12, these are UTF-8 strings. After, they can be any encoding
260  // permissible for a string (with the relevant tag).
261  MaybeHandle<String> ReadString() V8_WARN_UNUSED_RESULT;
262 
263  // Reading V8 objects of specific kinds.
264  // The tag is assumed to have already been read.
265  MaybeHandle<BigInt> ReadBigInt() V8_WARN_UNUSED_RESULT;
266  MaybeHandle<String> ReadUtf8String() V8_WARN_UNUSED_RESULT;
267  MaybeHandle<String> ReadOneByteString() V8_WARN_UNUSED_RESULT;
268  MaybeHandle<String> ReadTwoByteString() V8_WARN_UNUSED_RESULT;
269  MaybeHandle<JSObject> ReadJSObject() V8_WARN_UNUSED_RESULT;
270  MaybeHandle<JSArray> ReadSparseJSArray() V8_WARN_UNUSED_RESULT;
271  MaybeHandle<JSArray> ReadDenseJSArray() V8_WARN_UNUSED_RESULT;
272  MaybeHandle<JSDate> ReadJSDate() V8_WARN_UNUSED_RESULT;
273  MaybeHandle<JSValue> ReadJSValue(SerializationTag tag) V8_WARN_UNUSED_RESULT;
274  MaybeHandle<JSRegExp> ReadJSRegExp() V8_WARN_UNUSED_RESULT;
275  MaybeHandle<JSMap> ReadJSMap() V8_WARN_UNUSED_RESULT;
276  MaybeHandle<JSSet> ReadJSSet() V8_WARN_UNUSED_RESULT;
277  MaybeHandle<JSArrayBuffer> ReadJSArrayBuffer(bool is_shared)
278  V8_WARN_UNUSED_RESULT;
279  MaybeHandle<JSArrayBuffer> ReadTransferredJSArrayBuffer()
280  V8_WARN_UNUSED_RESULT;
281  MaybeHandle<JSArrayBufferView> ReadJSArrayBufferView(
282  Handle<JSArrayBuffer> buffer) V8_WARN_UNUSED_RESULT;
283  MaybeHandle<JSObject> ReadWasmModule() V8_WARN_UNUSED_RESULT;
284  MaybeHandle<JSObject> ReadWasmModuleTransfer() V8_WARN_UNUSED_RESULT;
285  MaybeHandle<WasmMemoryObject> ReadWasmMemory() V8_WARN_UNUSED_RESULT;
286  MaybeHandle<JSObject> ReadHostObject() V8_WARN_UNUSED_RESULT;
287 
288  /*
289  * Reads key-value pairs into the object until the specified end tag is
290  * encountered. If successful, returns the number of properties read.
291  */
292  Maybe<uint32_t> ReadJSObjectProperties(Handle<JSObject> object,
293  SerializationTag end_tag,
294  bool can_use_transitions);
295 
296  // Manipulating the map from IDs to reified objects.
297  bool HasObjectWithID(uint32_t id);
298  MaybeHandle<JSReceiver> GetObjectWithID(uint32_t id);
299  void AddObjectWithID(uint32_t id, Handle<JSReceiver> object);
300 
301  Isolate* const isolate_;
302  v8::ValueDeserializer::Delegate* const delegate_;
303  const uint8_t* position_;
304  const uint8_t* const end_;
305  PretenureFlag pretenure_;
306  uint32_t version_ = 0;
307  uint32_t next_id_ = 0;
308  bool expect_inline_wasm_ = false;
309 
310  // Always global handles.
311  Handle<FixedArray> id_map_;
312  MaybeHandle<SimpleNumberDictionary> array_buffer_transfer_map_;
313 
314  DISALLOW_COPY_AND_ASSIGN(ValueDeserializer);
315 };
316 
317 } // namespace internal
318 } // namespace v8
319 
320 #endif // V8_VALUE_SERIALIZER_H_
Definition: v8.h:56
Definition: libplatform.h:13