V8 API Reference, 7.2.502.16 (for Deno 0.2.4)
js-array-buffer.h
1 // Copyright 2018 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_OBJECTS_JS_ARRAY_BUFFER_H_
6 #define V8_OBJECTS_JS_ARRAY_BUFFER_H_
7 
8 #include "src/objects/js-objects.h"
9 
10 // Has to be the last include (doesn't have include guards):
11 #include "src/objects/object-macros.h"
12 
13 namespace v8 {
14 namespace internal {
15 
16 // Whether a JSArrayBuffer is a SharedArrayBuffer or not.
17 enum class SharedFlag : uint32_t { kNotShared, kShared };
18 
19 class JSArrayBuffer : public JSObject {
20  public:
21 // The maximum length for JSArrayBuffer's supported by V8.
22 // On 32-bit architectures we limit this to 2GiB, so that
23 // we can continue to use CheckBounds with the Unsigned31
24 // restriction for the length.
25 #if V8_HOST_ARCH_32_BIT
26  static constexpr size_t kMaxByteLength = kMaxInt;
27 #else
28  static constexpr size_t kMaxByteLength = kMaxSafeInteger;
29 #endif
30 
31  // [byte_length]: length in bytes
32  DECL_PRIMITIVE_ACCESSORS(byte_length, size_t)
33 
34  // [backing_store]: backing memory for this array
35  DECL_ACCESSORS(backing_store, void)
36 
37  // For non-wasm, allocation_length and allocation_base are byte_length and
38  // backing_store, respectively.
39  inline size_t allocation_length() const;
40  inline void* allocation_base() const;
41 
42  // [bit_field]: boolean flags
43  DECL_PRIMITIVE_ACCESSORS(bit_field, uint32_t)
44 
45  // Clear uninitialized padding space. This ensures that the snapshot content
46  // is deterministic. Depending on the V8 build mode there could be no padding.
47  V8_INLINE void clear_padding();
48 
49 // Bit positions for [bit_field].
50 #define JS_ARRAY_BUFFER_BIT_FIELD_FIELDS(V, _) \
51  V(IsExternalBit, bool, 1, _) \
52  V(IsNeuterableBit, bool, 1, _) \
53  V(WasNeuteredBit, bool, 1, _) \
54  V(IsSharedBit, bool, 1, _) \
55  V(IsGrowableBit, bool, 1, _) \
56  V(IsWasmMemoryBit, bool, 1, _)
57  DEFINE_BIT_FIELDS(JS_ARRAY_BUFFER_BIT_FIELD_FIELDS)
58 #undef JS_ARRAY_BUFFER_BIT_FIELD_FIELDS
59 
60  // [is_external]: true indicates that the embedder is in charge of freeing the
61  // backing_store, while is_external == false means that v8 will free the
62  // memory block once all ArrayBuffers referencing it are collected by the GC.
63  DECL_BOOLEAN_ACCESSORS(is_external)
64 
65  // [is_neuterable]: false indicates that this buffer cannot be detached.
66  DECL_BOOLEAN_ACCESSORS(is_neuterable)
67 
68  // [was_neutered]: true if the buffer was previously detached.
69  DECL_BOOLEAN_ACCESSORS(was_neutered)
70 
71  // [is_shared]: tells whether this is an ArrayBuffer or a SharedArrayBuffer.
72  DECL_BOOLEAN_ACCESSORS(is_shared)
73 
74  // [is_growable]: indicates whether it's possible to grow this buffer.
75  DECL_BOOLEAN_ACCESSORS(is_growable)
76 
77  // [is_wasm_memory]: whether the buffer is tracked by the WasmMemoryTracker.
78  DECL_BOOLEAN_ACCESSORS(is_wasm_memory)
79 
80  DECL_CAST(JSArrayBuffer)
81 
82  void Neuter();
83 
84  struct Allocation {
85  Allocation(void* allocation_base, size_t length, void* backing_store,
86  bool is_wasm_memory)
87  : allocation_base(allocation_base),
88  length(length),
89  backing_store(backing_store),
90  is_wasm_memory(is_wasm_memory) {}
91 
92  void* allocation_base;
93  size_t length;
94  void* backing_store;
95  bool is_wasm_memory;
96  };
97 
98  void FreeBackingStoreFromMainThread();
99  static void FreeBackingStore(Isolate* isolate, Allocation allocation);
100 
101  V8_EXPORT_PRIVATE static void Setup(
102  Handle<JSArrayBuffer> array_buffer, Isolate* isolate, bool is_external,
103  void* data, size_t allocated_length,
104  SharedFlag shared_flag = SharedFlag::kNotShared,
105  bool is_wasm_memory = false);
106 
107  // Initialize the object as empty one to avoid confusing heap verifier if
108  // the failure happened in the middle of JSArrayBuffer construction.
109  V8_EXPORT_PRIVATE static void SetupAsEmpty(Handle<JSArrayBuffer> array_buffer,
110  Isolate* isolate);
111 
112  // Returns false if array buffer contents could not be allocated.
113  // In this case, |array_buffer| will not be set up.
114  static bool SetupAllocatingData(
115  Handle<JSArrayBuffer> array_buffer, Isolate* isolate,
116  size_t allocated_length, bool initialize = true,
117  SharedFlag shared_flag = SharedFlag::kNotShared) V8_WARN_UNUSED_RESULT;
118 
119  // Dispatched behavior.
120  DECL_PRINTER(JSArrayBuffer)
121  DECL_VERIFIER(JSArrayBuffer)
122 
123 // Layout description.
124 #define JS_ARRAY_BUFFER_FIELDS(V) \
125  V(kEndOfTaggedFieldsOffset, 0) \
126  /* Raw data fields. */ \
127  V(kByteLengthOffset, kUIntptrSize) \
128  V(kBackingStoreOffset, kSystemPointerSize) \
129  V(kBitFieldOffset, kInt32Size) \
130  /* Pads header size to be a multiple of kTaggedSize. */ \
131  V(kOptionalPaddingOffset, OBJECT_POINTER_PADDING(kOptionalPaddingOffset)) \
132  /* Header size. */ \
133  V(kHeaderSize, 0)
134 
135  DEFINE_FIELD_OFFSET_CONSTANTS(JSObject::kHeaderSize, JS_ARRAY_BUFFER_FIELDS)
136 #undef JS_ARRAY_BUFFER_FIELDS
137 
138  static const int kSizeWithEmbedderFields =
139  kHeaderSize +
140  v8::ArrayBuffer::kEmbedderFieldCount * kEmbedderDataSlotSize;
141 
142  class BodyDescriptor;
143 
144  private:
145  DISALLOW_IMPLICIT_CONSTRUCTORS(JSArrayBuffer);
146 };
147 
148 class JSArrayBufferView : public JSObject {
149  public:
150  // [buffer]: ArrayBuffer that this typed array views.
151  DECL_ACCESSORS(buffer, Object)
152 
153  // [byte_offset]: offset of typed array in bytes.
154  DECL_PRIMITIVE_ACCESSORS(byte_offset, size_t)
155 
156  // [byte_length]: length of typed array in bytes.
157  DECL_PRIMITIVE_ACCESSORS(byte_length, size_t)
158 
159  DECL_CAST(JSArrayBufferView)
160 
161  DECL_VERIFIER(JSArrayBufferView)
162 
163  inline bool WasNeutered() const;
164 
165 // Layout description.
166 #define JS_ARRAY_BUFFER_VIEW_FIELDS(V) \
167  V(kBufferOffset, kTaggedSize) \
168  V(kEndOfTaggedFieldsOffset, 0) \
169  /* Raw data fields. */ \
170  V(kByteOffsetOffset, kUIntptrSize) \
171  V(kByteLengthOffset, kUIntptrSize) \
172  /* Header size. */ \
173  V(kHeaderSize, 0)
174 
175  DEFINE_FIELD_OFFSET_CONSTANTS(JSObject::kHeaderSize,
176  JS_ARRAY_BUFFER_VIEW_FIELDS)
177 #undef JS_ARRAY_BUFFER_VIEW_FIELDS
178 
179  class BodyDescriptor;
180 
181  private:
182  DISALLOW_IMPLICIT_CONSTRUCTORS(JSArrayBufferView);
183 };
184 
186  public:
187  // [length]: length of typed array in elements.
188  DECL_ACCESSORS(length, Object)
189  inline size_t length_value() const;
190 
191  // ES6 9.4.5.3
192  V8_WARN_UNUSED_RESULT static Maybe<bool> DefineOwnProperty(
194  PropertyDescriptor* desc, ShouldThrow should_throw);
195 
196  DECL_CAST(JSTypedArray)
197 
198  ExternalArrayType type();
199  V8_EXPORT_PRIVATE size_t element_size();
200 
201  Handle<JSArrayBuffer> GetBuffer();
202 
203  // Whether the buffer's backing store is on-heap or off-heap.
204  inline bool is_on_heap() const;
205 
206  static inline MaybeHandle<JSTypedArray> Validate(Isolate* isolate,
207  Handle<Object> receiver,
208  const char* method_name);
209 
210  // Dispatched behavior.
211  DECL_PRINTER(JSTypedArray)
212  DECL_VERIFIER(JSTypedArray)
213 
214 // Layout description.
215 #define JS_TYPED_ARRAY_FIELDS(V) \
216  /* Raw data fields. */ \
217  V(kLengthOffset, kSystemPointerSize) \
218  /* Header size. */ \
219  V(kHeaderSize, 0)
220 
221  DEFINE_FIELD_OFFSET_CONSTANTS(JSArrayBufferView::kHeaderSize,
222  JS_TYPED_ARRAY_FIELDS)
223 #undef JS_TYPED_ARRAY_FIELDS
224 
225  static const int kSizeWithEmbedderFields =
226  kHeaderSize +
227  v8::ArrayBufferView::kEmbedderFieldCount * kEmbedderDataSlotSize;
228 
229  private:
230  static Handle<JSArrayBuffer> MaterializeArrayBuffer(
231  Handle<JSTypedArray> typed_array);
232 #ifdef VERIFY_HEAP
233  DECL_ACCESSORS(raw_length, Object)
234 #endif
235 
236  DISALLOW_IMPLICIT_CONSTRUCTORS(JSTypedArray);
237 };
238 
240  public:
241  DECL_CAST(JSDataView)
242 
243  // Dispatched behavior.
244  DECL_PRINTER(JSDataView)
245  DECL_VERIFIER(JSDataView)
246 
247  // Layout description.
248  static const int kSizeWithEmbedderFields =
249  kHeaderSize +
250  v8::ArrayBufferView::kEmbedderFieldCount * kEmbedderDataSlotSize;
251 
252  private:
253  DISALLOW_IMPLICIT_CONSTRUCTORS(JSDataView);
254 };
255 
256 } // namespace internal
257 } // namespace v8
258 
259 #include "src/objects/object-macros-undef.h"
260 
261 #endif // V8_OBJECTS_JS_ARRAY_BUFFER_H_
Definition: v8.h:56
Definition: libplatform.h:13