1// Copyright 2012 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_API_H_
6#define V8_API_H_
7
8#include "include/v8-testing.h"
9#include "src/contexts.h"
10#include "src/detachable-vector.h"
11#include "src/heap/factory.h"
12#include "src/isolate.h"
13#include "src/objects.h"
14#include "src/objects/bigint.h"
15#include "src/objects/js-collection.h"
16#include "src/objects/js-generator.h"
17#include "src/objects/js-promise.h"
18#include "src/objects/js-proxy.h"
19#include "src/objects/module.h"
20#include "src/objects/shared-function-info.h"
21
22#include "src/objects/templates.h"
23
24namespace v8 {
25
26namespace internal {
27class JSArrayBufferView;
28} // namespace internal
29
30namespace debug {
31class GeneratorObject;
32class Script;
33class WeakMap;
34} // namespace debug
35
36// Constants used in the implementation of the API. The most natural thing
37// would usually be to place these with the classes that use them, but
38// we want to keep them out of v8.h because it is an externally
39// visible file.
40class Consts {
41 public:
42 enum TemplateType {
43 FUNCTION_TEMPLATE = 0,
44 OBJECT_TEMPLATE = 1
45 };
46};
47
48template <typename T>
49inline T ToCData(v8::internal::Object obj);
50
51template <>
52inline v8::internal::Address ToCData(v8::internal::Object obj);
53
54template <typename T>
55inline v8::internal::Handle<v8::internal::Object> FromCData(
56 v8::internal::Isolate* isolate, T obj);
57
58template <>
59inline v8::internal::Handle<v8::internal::Object> FromCData(
60 v8::internal::Isolate* isolate, v8::internal::Address obj);
61
62class ApiFunction {
63 public:
64 explicit ApiFunction(v8::internal::Address addr) : addr_(addr) { }
65 v8::internal::Address address() { return addr_; }
66 private:
67 v8::internal::Address addr_;
68};
69
70
71
72class RegisteredExtension {
73 public:
74 static void Register(std::unique_ptr<Extension>);
75 static void UnregisterAll();
76 Extension* extension() const { return extension_.get(); }
77 RegisteredExtension* next() const { return next_; }
78 static RegisteredExtension* first_extension() { return first_extension_; }
79 private:
80 explicit RegisteredExtension(Extension*);
81 explicit RegisteredExtension(std::unique_ptr<Extension>);
82 std::unique_ptr<Extension> extension_;
83 RegisteredExtension* next_ = nullptr;
84 static RegisteredExtension* first_extension_;
85};
86
87#define OPEN_HANDLE_LIST(V) \
88 V(Template, TemplateInfo) \
89 V(FunctionTemplate, FunctionTemplateInfo) \
90 V(ObjectTemplate, ObjectTemplateInfo) \
91 V(Signature, FunctionTemplateInfo) \
92 V(AccessorSignature, FunctionTemplateInfo) \
93 V(Data, Object) \
94 V(RegExp, JSRegExp) \
95 V(Object, JSReceiver) \
96 V(Array, JSArray) \
97 V(Map, JSMap) \
98 V(Set, JSSet) \
99 V(ArrayBuffer, JSArrayBuffer) \
100 V(ArrayBufferView, JSArrayBufferView) \
101 V(TypedArray, JSTypedArray) \
102 V(Uint8Array, JSTypedArray) \
103 V(Uint8ClampedArray, JSTypedArray) \
104 V(Int8Array, JSTypedArray) \
105 V(Uint16Array, JSTypedArray) \
106 V(Int16Array, JSTypedArray) \
107 V(Uint32Array, JSTypedArray) \
108 V(Int32Array, JSTypedArray) \
109 V(Float32Array, JSTypedArray) \
110 V(Float64Array, JSTypedArray) \
111 V(DataView, JSDataView) \
112 V(SharedArrayBuffer, JSArrayBuffer) \
113 V(Name, Name) \
114 V(String, String) \
115 V(Symbol, Symbol) \
116 V(Script, JSFunction) \
117 V(UnboundModuleScript, SharedFunctionInfo) \
118 V(UnboundScript, SharedFunctionInfo) \
119 V(Module, Module) \
120 V(Function, JSReceiver) \
121 V(Message, JSMessageObject) \
122 V(Context, Context) \
123 V(External, Object) \
124 V(StackTrace, FixedArray) \
125 V(StackFrame, StackTraceFrame) \
126 V(Proxy, JSProxy) \
127 V(debug::GeneratorObject, JSGeneratorObject) \
128 V(debug::Script, Script) \
129 V(debug::WeakMap, JSWeakMap) \
130 V(Promise, JSPromise) \
131 V(Primitive, Object) \
132 V(PrimitiveArray, FixedArray) \
133 V(BigInt, BigInt) \
134 V(ScriptOrModule, Script)
135
136class Utils {
137 public:
138 static inline bool ApiCheck(bool condition,
139 const char* location,
140 const char* message) {
141 if (!condition) Utils::ReportApiFailure(location, message);
142 return condition;
143 }
144 static void ReportOOMFailure(v8::internal::Isolate* isolate,
145 const char* location, bool is_heap_oom);
146
147 static inline Local<Context> ToLocal(
148 v8::internal::Handle<v8::internal::Context> obj);
149 static inline Local<Value> ToLocal(
150 v8::internal::Handle<v8::internal::Object> obj);
151 static inline Local<Module> ToLocal(
152 v8::internal::Handle<v8::internal::Module> obj);
153 static inline Local<Name> ToLocal(
154 v8::internal::Handle<v8::internal::Name> obj);
155 static inline Local<String> ToLocal(
156 v8::internal::Handle<v8::internal::String> obj);
157 static inline Local<Symbol> ToLocal(
158 v8::internal::Handle<v8::internal::Symbol> obj);
159 static inline Local<RegExp> ToLocal(
160 v8::internal::Handle<v8::internal::JSRegExp> obj);
161 static inline Local<Object> ToLocal(
162 v8::internal::Handle<v8::internal::JSReceiver> obj);
163 static inline Local<Object> ToLocal(
164 v8::internal::Handle<v8::internal::JSObject> obj);
165 static inline Local<Function> ToLocal(
166 v8::internal::Handle<v8::internal::JSFunction> obj);
167 static inline Local<Array> ToLocal(
168 v8::internal::Handle<v8::internal::JSArray> obj);
169 static inline Local<Map> ToLocal(
170 v8::internal::Handle<v8::internal::JSMap> obj);
171 static inline Local<Set> ToLocal(
172 v8::internal::Handle<v8::internal::JSSet> obj);
173 static inline Local<Proxy> ToLocal(
174 v8::internal::Handle<v8::internal::JSProxy> obj);
175 static inline Local<ArrayBuffer> ToLocal(
176 v8::internal::Handle<v8::internal::JSArrayBuffer> obj);
177 static inline Local<ArrayBufferView> ToLocal(
178 v8::internal::Handle<v8::internal::JSArrayBufferView> obj);
179 static inline Local<DataView> ToLocal(
180 v8::internal::Handle<v8::internal::JSDataView> obj);
181 static inline Local<TypedArray> ToLocal(
182 v8::internal::Handle<v8::internal::JSTypedArray> obj);
183 static inline Local<Uint8Array> ToLocalUint8Array(
184 v8::internal::Handle<v8::internal::JSTypedArray> obj);
185 static inline Local<Uint8ClampedArray> ToLocalUint8ClampedArray(
186 v8::internal::Handle<v8::internal::JSTypedArray> obj);
187 static inline Local<Int8Array> ToLocalInt8Array(
188 v8::internal::Handle<v8::internal::JSTypedArray> obj);
189 static inline Local<Uint16Array> ToLocalUint16Array(
190 v8::internal::Handle<v8::internal::JSTypedArray> obj);
191 static inline Local<Int16Array> ToLocalInt16Array(
192 v8::internal::Handle<v8::internal::JSTypedArray> obj);
193 static inline Local<Uint32Array> ToLocalUint32Array(
194 v8::internal::Handle<v8::internal::JSTypedArray> obj);
195 static inline Local<Int32Array> ToLocalInt32Array(
196 v8::internal::Handle<v8::internal::JSTypedArray> obj);
197 static inline Local<Float32Array> ToLocalFloat32Array(
198 v8::internal::Handle<v8::internal::JSTypedArray> obj);
199 static inline Local<Float64Array> ToLocalFloat64Array(
200 v8::internal::Handle<v8::internal::JSTypedArray> obj);
201 static inline Local<BigInt64Array> ToLocalBigInt64Array(
202 v8::internal::Handle<v8::internal::JSTypedArray> obj);
203 static inline Local<BigUint64Array> ToLocalBigUint64Array(
204 v8::internal::Handle<v8::internal::JSTypedArray> obj);
205
206 static inline Local<SharedArrayBuffer> ToLocalShared(
207 v8::internal::Handle<v8::internal::JSArrayBuffer> obj);
208
209 static inline Local<Message> MessageToLocal(
210 v8::internal::Handle<v8::internal::Object> obj);
211 static inline Local<Promise> PromiseToLocal(
212 v8::internal::Handle<v8::internal::JSObject> obj);
213 static inline Local<StackTrace> StackTraceToLocal(
214 v8::internal::Handle<v8::internal::FixedArray> obj);
215 static inline Local<StackFrame> StackFrameToLocal(
216 v8::internal::Handle<v8::internal::StackTraceFrame> obj);
217 static inline Local<Number> NumberToLocal(
218 v8::internal::Handle<v8::internal::Object> obj);
219 static inline Local<Integer> IntegerToLocal(
220 v8::internal::Handle<v8::internal::Object> obj);
221 static inline Local<Uint32> Uint32ToLocal(
222 v8::internal::Handle<v8::internal::Object> obj);
223 static inline Local<BigInt> ToLocal(
224 v8::internal::Handle<v8::internal::BigInt> obj);
225 static inline Local<FunctionTemplate> ToLocal(
226 v8::internal::Handle<v8::internal::FunctionTemplateInfo> obj);
227 static inline Local<ObjectTemplate> ToLocal(
228 v8::internal::Handle<v8::internal::ObjectTemplateInfo> obj);
229 static inline Local<Signature> SignatureToLocal(
230 v8::internal::Handle<v8::internal::FunctionTemplateInfo> obj);
231 static inline Local<AccessorSignature> AccessorSignatureToLocal(
232 v8::internal::Handle<v8::internal::FunctionTemplateInfo> obj);
233 static inline Local<External> ExternalToLocal(
234 v8::internal::Handle<v8::internal::JSObject> obj);
235 static inline Local<Function> CallableToLocal(
236 v8::internal::Handle<v8::internal::JSReceiver> obj);
237 static inline Local<Primitive> ToLocalPrimitive(
238 v8::internal::Handle<v8::internal::Object> obj);
239 static inline Local<PrimitiveArray> ToLocal(
240 v8::internal::Handle<v8::internal::FixedArray> obj);
241 static inline Local<ScriptOrModule> ScriptOrModuleToLocal(
242 v8::internal::Handle<v8::internal::Script> obj);
243
244#define DECLARE_OPEN_HANDLE(From, To) \
245 static inline v8::internal::Handle<v8::internal::To> OpenHandle( \
246 const From* that, bool allow_empty_handle = false);
247
248 OPEN_HANDLE_LIST(DECLARE_OPEN_HANDLE)
249
250#undef DECLARE_OPEN_HANDLE
251
252 template <class From, class To>
253 static inline Local<To> Convert(v8::internal::Handle<From> obj);
254
255 template <class T>
256 static inline v8::internal::Handle<v8::internal::Object> OpenPersistent(
257 const v8::Persistent<T>& persistent) {
258 return v8::internal::Handle<v8::internal::Object>(
259 reinterpret_cast<v8::internal::Address*>(persistent.val_));
260 }
261
262 template <class T>
263 static inline v8::internal::Handle<v8::internal::Object> OpenPersistent(
264 v8::Persistent<T>* persistent) {
265 return OpenPersistent(*persistent);
266 }
267
268 template <class From, class To>
269 static inline v8::internal::Handle<To> OpenHandle(v8::Local<From> handle) {
270 return OpenHandle(*handle);
271 }
272
273 static inline CompiledWasmModule Convert(
274 std::shared_ptr<i::wasm::NativeModule> native_module) {
275 return CompiledWasmModule{std::move(native_module)};
276 }
277
278 private:
279 static void ReportApiFailure(const char* location, const char* message);
280};
281
282template <class T>
283inline T* ToApi(v8::internal::Handle<v8::internal::Object> obj) {
284 return reinterpret_cast<T*>(obj.location());
285}
286
287template <class T>
288inline v8::Local<T> ToApiHandle(
289 v8::internal::Handle<v8::internal::Object> obj) {
290 return Utils::Convert<v8::internal::Object, T>(obj);
291}
292
293
294template <class T>
295inline bool ToLocal(v8::internal::MaybeHandle<v8::internal::Object> maybe,
296 Local<T>* local) {
297 v8::internal::Handle<v8::internal::Object> handle;
298 if (maybe.ToHandle(&handle)) {
299 *local = Utils::Convert<v8::internal::Object, T>(handle);
300 return true;
301 }
302 return false;
303}
304
305namespace internal {
306
307class V8_EXPORT_PRIVATE DeferredHandles {
308 public:
309 ~DeferredHandles();
310
311 private:
312 DeferredHandles(Address* first_block_limit, Isolate* isolate)
313 : next_(nullptr),
314 previous_(nullptr),
315 first_block_limit_(first_block_limit),
316 isolate_(isolate) {
317 isolate->LinkDeferredHandles(this);
318 }
319
320 void Iterate(RootVisitor* v);
321
322 std::vector<Address*> blocks_;
323 DeferredHandles* next_;
324 DeferredHandles* previous_;
325 Address* first_block_limit_;
326 Isolate* isolate_;
327
328 friend class HandleScopeImplementer;
329 friend class Isolate;
330};
331
332
333// This class is here in order to be able to declare it a friend of
334// HandleScope. Moving these methods to be members of HandleScope would be
335// neat in some ways, but it would expose internal implementation details in
336// our public header file, which is undesirable.
337//
338// An isolate has a single instance of this class to hold the current thread's
339// data. In multithreaded V8 programs this data is copied in and out of storage
340// so that the currently executing thread always has its own copy of this
341// data.
342class HandleScopeImplementer {
343 public:
344 class EnteredContextRewindScope {
345 public:
346 explicit EnteredContextRewindScope(HandleScopeImplementer* hsi)
347 : hsi_(hsi), saved_entered_context_count_(hsi->EnteredContextCount()) {}
348
349 ~EnteredContextRewindScope() {
350 DCHECK_LE(saved_entered_context_count_, hsi_->EnteredContextCount());
351 while (saved_entered_context_count_ < hsi_->EnteredContextCount())
352 hsi_->LeaveContext();
353 }
354
355 private:
356 HandleScopeImplementer* hsi_;
357 size_t saved_entered_context_count_;
358 };
359
360 explicit HandleScopeImplementer(Isolate* isolate)
361 : isolate_(isolate),
362 spare_(nullptr),
363 call_depth_(0),
364 last_handle_before_deferred_block_(nullptr) {
365 }
366
367 ~HandleScopeImplementer() {
368 DeleteArray(spare_);
369 }
370
371 // Threading support for handle data.
372 static int ArchiveSpacePerThread();
373 char* RestoreThread(char* from);
374 char* ArchiveThread(char* to);
375 void FreeThreadResources();
376
377 // Garbage collection support.
378 V8_EXPORT_PRIVATE void Iterate(v8::internal::RootVisitor* v);
379 V8_EXPORT_PRIVATE static char* Iterate(v8::internal::RootVisitor* v,
380 char* data);
381
382 inline internal::Address* GetSpareOrNewBlock();
383 inline void DeleteExtensions(internal::Address* prev_limit);
384
385 // Call depth represents nested v8 api calls.
386 inline void IncrementCallDepth() {call_depth_++;}
387 inline void DecrementCallDepth() {call_depth_--;}
388 inline bool CallDepthIsZero() { return call_depth_ == 0; }
389
390 inline void EnterContext(Context context);
391 inline void LeaveContext();
392 inline bool LastEnteredContextWas(Context context);
393 inline size_t EnteredContextCount() const { return entered_contexts_.size(); }
394
395 inline void EnterMicrotaskContext(Context context);
396
397 // Returns the last entered context or an empty handle if no
398 // contexts have been entered.
399 inline Handle<Context> LastEnteredContext();
400 inline Handle<Context> LastEnteredOrMicrotaskContext();
401
402 inline void SaveContext(Context context);
403 inline Context RestoreContext();
404 inline bool HasSavedContexts();
405
406 inline DetachableVector<Address*>* blocks() { return &blocks_; }
407 Isolate* isolate() const { return isolate_; }
408
409 void ReturnBlock(Address* block) {
410 DCHECK_NOT_NULL(block);
411 if (spare_ != nullptr) DeleteArray(spare_);
412 spare_ = block;
413 }
414
415 static const size_t kEnteredContextsOffset;
416 static const size_t kIsMicrotaskContextOffset;
417
418 private:
419 void ResetAfterArchive() {
420 blocks_.detach();
421 entered_contexts_.detach();
422 is_microtask_context_.detach();
423 saved_contexts_.detach();
424 spare_ = nullptr;
425 last_handle_before_deferred_block_ = nullptr;
426 call_depth_ = 0;
427 }
428
429 void Free() {
430 DCHECK(blocks_.empty());
431 DCHECK(entered_contexts_.empty());
432 DCHECK(is_microtask_context_.empty());
433 DCHECK(saved_contexts_.empty());
434
435 blocks_.free();
436 entered_contexts_.free();
437 is_microtask_context_.free();
438 saved_contexts_.free();
439 if (spare_ != nullptr) {
440 DeleteArray(spare_);
441 spare_ = nullptr;
442 }
443 DCHECK_EQ(call_depth_, 0);
444 }
445
446 void BeginDeferredScope();
447 DeferredHandles* Detach(Address* prev_limit);
448
449 Isolate* isolate_;
450 DetachableVector<Address*> blocks_;
451
452 // Used as a stack to keep track of entered contexts.
453 // If |i|th item of |entered_contexts_| is added by EnterMicrotaskContext,
454 // `is_microtask_context_[i]` is 1.
455 // TODO(tzik): Remove |is_microtask_context_| after the deprecated
456 // v8::Isolate::GetEnteredContext() is removed.
457 DetachableVector<Context> entered_contexts_;
458 DetachableVector<int8_t> is_microtask_context_;
459
460 // Used as a stack to keep track of saved contexts.
461 DetachableVector<Context> saved_contexts_;
462 Address* spare_;
463 int call_depth_;
464
465 Address* last_handle_before_deferred_block_;
466 // This is only used for threading support.
467 HandleScopeData handle_scope_data_;
468
469 void IterateThis(RootVisitor* v);
470 char* RestoreThreadHelper(char* from);
471 char* ArchiveThreadHelper(char* to);
472
473 friend class DeferredHandles;
474 friend class DeferredHandleScope;
475 friend class HandleScopeImplementerOffsets;
476
477 DISALLOW_COPY_AND_ASSIGN(HandleScopeImplementer);
478};
479
480const int kHandleBlockSize = v8::internal::KB - 2; // fit in one page
481
482void HandleScopeImplementer::SaveContext(Context context) {
483 saved_contexts_.push_back(context);
484}
485
486Context HandleScopeImplementer::RestoreContext() {
487 Context last_context = saved_contexts_.back();
488 saved_contexts_.pop_back();
489 return last_context;
490}
491
492
493bool HandleScopeImplementer::HasSavedContexts() {
494 return !saved_contexts_.empty();
495}
496
497void HandleScopeImplementer::EnterContext(Context context) {
498 DCHECK_EQ(entered_contexts_.size(), is_microtask_context_.size());
499 entered_contexts_.push_back(context);
500 is_microtask_context_.push_back(0);
501}
502
503void HandleScopeImplementer::LeaveContext() {
504 DCHECK(!entered_contexts_.empty());
505 DCHECK_EQ(entered_contexts_.size(), is_microtask_context_.size());
506 entered_contexts_.pop_back();
507 is_microtask_context_.pop_back();
508}
509
510bool HandleScopeImplementer::LastEnteredContextWas(Context context) {
511 return !entered_contexts_.empty() && entered_contexts_.back() == context;
512}
513
514void HandleScopeImplementer::EnterMicrotaskContext(Context context) {
515 DCHECK_EQ(entered_contexts_.size(), is_microtask_context_.size());
516 entered_contexts_.push_back(context);
517 is_microtask_context_.push_back(1);
518}
519
520// If there's a spare block, use it for growing the current scope.
521internal::Address* HandleScopeImplementer::GetSpareOrNewBlock() {
522 internal::Address* block =
523 (spare_ != nullptr) ? spare_
524 : NewArray<internal::Address>(kHandleBlockSize);
525 spare_ = nullptr;
526 return block;
527}
528
529void HandleScopeImplementer::DeleteExtensions(internal::Address* prev_limit) {
530 while (!blocks_.empty()) {
531 internal::Address* block_start = blocks_.back();
532 internal::Address* block_limit = block_start + kHandleBlockSize;
533
534 // SealHandleScope may make the prev_limit to point inside the block.
535 // Cast possibly-unrelated pointers to plain Addres before comparing them
536 // to avoid undefined behavior.
537 if (reinterpret_cast<Address>(block_start) <=
538 reinterpret_cast<Address>(prev_limit) &&
539 reinterpret_cast<Address>(prev_limit) <=
540 reinterpret_cast<Address>(block_limit)) {
541#ifdef ENABLE_HANDLE_ZAPPING
542 internal::HandleScope::ZapRange(prev_limit, block_limit);
543#endif
544 break;
545 }
546
547 blocks_.pop_back();
548#ifdef ENABLE_HANDLE_ZAPPING
549 internal::HandleScope::ZapRange(block_start, block_limit);
550#endif
551 if (spare_ != nullptr) {
552 DeleteArray(spare_);
553 }
554 spare_ = block_start;
555 }
556 DCHECK((blocks_.empty() && prev_limit == nullptr) ||
557 (!blocks_.empty() && prev_limit != nullptr));
558}
559
560// Interceptor functions called from generated inline caches to notify
561// CPU profiler that external callbacks are invoked.
562void InvokeAccessorGetterCallback(
563 v8::Local<v8::Name> property,
564 const v8::PropertyCallbackInfo<v8::Value>& info,
565 v8::AccessorNameGetterCallback getter);
566
567void InvokeFunctionCallback(const v8::FunctionCallbackInfo<v8::Value>& info,
568 v8::FunctionCallback callback);
569
570class Testing {
571 public:
572 static v8::Testing::StressType stress_type() { return stress_type_; }
573 static void set_stress_type(v8::Testing::StressType stress_type) {
574 stress_type_ = stress_type;
575 }
576
577 private:
578 static v8::Testing::StressType stress_type_;
579};
580
581} // namespace internal
582} // namespace v8
583
584#endif // V8_API_H_
585