1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
|
// Copyright 2021 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#ifndef THIRD_PARTY_BLINK_RENDERER_PLATFORM_BINDINGS_OBSERVABLE_ARRAY_H_
#define THIRD_PARTY_BLINK_RENDERER_PLATFORM_BINDINGS_OBSERVABLE_ARRAY_H_
#include "third_party/blink/renderer/platform/bindings/script_wrappable.h"
#include "third_party/blink/renderer/platform/heap/heap_traits.h"
#include "third_party/blink/renderer/platform/heap/member.h"
#include "v8/include/v8-forward.h"
// Overview of Blink implementation of Web IDL observable arrays
//
// Observable arrays are implemented with two objects:
// 1) backing list object
// https://webidl.spec.whatwg.org/#observable-array-attribute-backing-list
// and 2) exotic object.
// https://webidl.spec.whatwg.org/#backing-observable-array-exotic-object
// As DOM objects are implemented with a ScriptWrappable and its V8 wrappers,
// there are a ScriptWrappable of a backing list object and its V8 wrappers,
// also a ScriptWrappable of a exotic object and its (pseudo) V8 wrappers.
//
// By definition, observable array exotic object is a JS Proxy in ECMAScript
// binding.
//
// let exotic_object = new Proxy(backing_list_object, handler_object);
//
// For web developers, the JS Proxy object is the only visible object. Web
// developers cannot access the backing list object directly.
//
// For Blink developers, the backing list object looks the primary object.
// However, when exposing an observable array to web developers, the exotic
// object must be exposed instead of the backing list object. This is done in
// auto-generated bindings (generated bindings automatically call
// GetExoticObject()).
//
// class MyIdlInterface : public ScriptWrappable {
// public:
// V8ObservableArrayNode* myAttr() const {
// return my_observable_array_;
// }
// private:
// // my_observable_array_ is a backing list object.
// Member<V8ObservableArrayNode> my_observable_array_;
// };
//
// Class hierarchy and relationship:
// bindings::ObservableArrayBase -- the base class of backing list objects
// +-- bindings::ObservableArrayImplHelper<T> -- just a helper
// +-- V8ObservableArrayNode -- generated implementation of IDL
// ObservableArray<Node>. Bindings code generator produces this
// class from *.idl files.
// ObservableArrayExoticObject -- the implementation of exotic objects
//
// v8_exotic_object (= JS Proxy)
// --(proxy target)--> v8_array (= JS Array)
// --(private property)--> v8_backing_list_object
// --(internal field)--> blink_backing_list_object
// --(data member)--> blink_exotic_object
// --(ToV8Traits)--> v8_exotic_object
namespace blink {
class ObservableArrayExoticObject;
namespace bindings {
// ObservableArrayBase is the common base class of all the observable array
// classes, and represents the backing list for an IDL attribute of an
// observable array type (but the actual implementation lives in
// bindings/core/v8/).
// https://webidl.spec.whatwg.org/#observable-array-attribute-backing-list
class PLATFORM_EXPORT ObservableArrayBase : public ScriptWrappable {
public:
ObservableArrayBase(
GarbageCollectedMixin* platform_object,
ObservableArrayExoticObject* observable_array_exotic_object);
~ObservableArrayBase() override = default;
// Returns the observable array exotic object, which is the value to be
// returned as the IDL attribute value. Do not use `this` object (= the
// observable array backing list object) as the IDL attribute value.
ObservableArrayExoticObject* GetExoticObject() const {
return observable_array_exotic_object_.Get();
}
v8::Local<v8::Object> GetProxyHandlerObject(ScriptState* script_state);
void Trace(Visitor* visitor) const override;
protected:
GarbageCollectedMixin* GetPlatformObject() { return platform_object_.Get(); }
virtual v8::Local<v8::FunctionTemplate> GetProxyHandlerFunctionTemplate(
ScriptState* script_state) = 0;
private:
Member<GarbageCollectedMixin> platform_object_; // IDL attribute owner
Member<ObservableArrayExoticObject> observable_array_exotic_object_;
};
template <typename ElementType>
class ObservableArrayImplHelper : public bindings::ObservableArrayBase {
public:
using BackingListType = VectorOf<ElementType>;
using size_type = typename BackingListType::size_type;
using value_type = typename BackingListType::value_type;
using reference = typename BackingListType::reference;
using const_reference = typename BackingListType::const_reference;
using pointer = typename BackingListType::pointer;
using const_pointer = typename BackingListType::const_pointer;
using iterator = typename BackingListType::iterator;
using const_iterator = typename BackingListType::const_iterator;
using reverse_iterator = typename BackingListType::reverse_iterator;
using const_reverse_iterator =
typename BackingListType::const_reverse_iterator;
explicit ObservableArrayImplHelper(GarbageCollectedMixin* platform_object)
: bindings::ObservableArrayBase(
platform_object,
MakeGarbageCollected<ObservableArrayExoticObject>(this)) {}
~ObservableArrayImplHelper() override = default;
// Returns the observable array exotic object, which is the value to be
// returned as the IDL attribute value. Do not use `this` object (= the
// observable array backing list object) as the IDL attribute value.
using bindings::ObservableArrayBase::GetExoticObject;
// Vector-compatible APIs (accessors)
size_type size() const { return backing_list_.size(); }
size_type capacity() const { return backing_list_.capacity(); }
bool empty() const { return backing_list_.empty(); }
void reserve(size_type new_capacity) { backing_list_.reserve(new_capacity); }
void ReserveInitialCapacity(size_type initial_capacity) {
backing_list_.ReserveInitialCapacity(initial_capacity);
}
reference at(size_type index) { return backing_list_.at(index); }
const_reference at(size_type index) const { return backing_list_.at(index); }
reference operator[](size_type index) { return backing_list_[index]; }
const_reference operator[](size_type index) const {
return backing_list_[index];
}
value_type* data() { return backing_list_.data(); }
const value_type* data() const { return backing_list_.data(); }
iterator begin() { return backing_list_.begin(); }
iterator end() { return backing_list_.end(); }
const_iterator begin() const { return backing_list_.begin(); }
const_iterator end() const { return backing_list_.end(); }
reverse_iterator rbegin() { return backing_list_.rbegin(); }
reverse_iterator rend() { return backing_list_.rend(); }
const_reverse_iterator rbegin() const { return backing_list_.rbegin(); }
const_reverse_iterator rend() const { return backing_list_.rend(); }
reference front() { return backing_list_.front(); }
reference back() { return backing_list_.back(); }
const_reference front() const { return backing_list_.front(); }
const_reference back() const { return backing_list_.back(); }
// Vector-compatible APIs (modifiers)
void resize(size_type size) { backing_list_.resize(size); }
void clear() { backing_list_.clear(); }
template <typename T>
void push_back(T&& value) {
backing_list_.push_back(std::forward<T>(value));
}
void pop_back() { backing_list_.pop_back(); }
template <typename... Args>
reference emplace_back(Args&&... args) {
return backing_list_.emplace_back(std::forward<Args>(args)...);
}
template <typename T>
void insert(iterator position, T&& value) {
backing_list_.InsertAt(position, std::forward<T>(value));
}
iterator erase(iterator position) { return backing_list_.erase(position); }
iterator erase(iterator first, iterator last) {
return backing_list_.erase(first, last);
}
void Trace(Visitor* visitor) const override {
ObservableArrayBase::Trace(visitor);
TraceIfNeeded<BackingListType>::Trace(visitor, backing_list_);
}
private:
BackingListType backing_list_;
};
} // namespace bindings
// Represents a backing observable array exotic object.
// https://webidl.spec.whatwg.org/#backing-observable-array-exotic-object
class PLATFORM_EXPORT ObservableArrayExoticObject final
: public ScriptWrappable {
DEFINE_WRAPPERTYPEINFO();
public:
// Returns the backing list object extracted from the proxy target object
// of type JS Array.
template <typename T>
static T* ProxyTargetToObservableArray(v8::Isolate* isolate,
v8::Local<v8::Array> v8_proxy_target) {
return ToScriptWrappable<T>(
isolate, GetBackingObjectFromProxyTarget(isolate, v8_proxy_target));
}
explicit ObservableArrayExoticObject(
bindings::ObservableArrayBase* observable_array_backing_list_object);
~ObservableArrayExoticObject() final = default;
bindings::ObservableArrayBase* GetBackingListObject() const {
return observable_array_backing_list_object_.Get();
}
// ScriptWrappable overrides:
v8::Local<v8::Value> Wrap(ScriptState* script_state) final;
[[nodiscard]] v8::Local<v8::Object> AssociateWithWrapper(
v8::Isolate* isolate,
const WrapperTypeInfo* wrapper_type_info,
v8::Local<v8::Object> wrapper) final;
void Trace(Visitor* visitor) const final;
private:
static v8::Local<v8::Object> GetBackingObjectFromProxyTarget(
v8::Isolate*,
v8::Local<v8::Array> v8_proxy_target);
Member<bindings::ObservableArrayBase> observable_array_backing_list_object_;
};
} // namespace blink
#endif // THIRD_PARTY_BLINK_RENDERER_PLATFORM_BINDINGS_OBSERVABLE_ARRAY_H_
|
