1// Copyright 2021 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 INCLUDE_V8_LOCAL_HANDLE_H_
6#define INCLUDE_V8_LOCAL_HANDLE_H_
7
8#include <stddef.h>
9
10#include <type_traits>
11
12#include "v8-internal.h"  // NOLINT(build/include_directory)
13
14namespace v8 {
15
16class Boolean;
17template <class T>
18class BasicTracedReference;
19class Context;
20class EscapableHandleScope;
21template <class F>
22class Eternal;
23template <class F>
24class FunctionCallbackInfo;
25class Isolate;
26template <class F>
27class MaybeLocal;
28template <class T>
29class NonCopyablePersistentTraits;
30class Object;
31template <class T, class M = NonCopyablePersistentTraits<T>>
32class Persistent;
33template <class T>
34class PersistentBase;
35template <class F1, class F2, class F3>
36class PersistentValueMapBase;
37template <class F1, class F2>
38class PersistentValueVector;
39class Primitive;
40class Private;
41template <class F>
42class PropertyCallbackInfo;
43template <class F>
44class ReturnValue;
45class String;
46template <class F>
47class Traced;
48template <class F>
49class TracedReference;
50class TracedReferenceBase;
51class Utils;
52
53namespace internal {
54template <typename T>
55class CustomArguments;
56}  // namespace internal
57
58namespace api_internal {
59// Called when ToLocalChecked is called on an empty Local.
60V8_EXPORT void ToLocalEmpty();
61}  // namespace api_internal
62
63/**
64 * A stack-allocated class that governs a number of local handles.
65 * After a handle scope has been created, all local handles will be
66 * allocated within that handle scope until either the handle scope is
67 * deleted or another handle scope is created.  If there is already a
68 * handle scope and a new one is created, all allocations will take
69 * place in the new handle scope until it is deleted.  After that,
70 * new handles will again be allocated in the original handle scope.
71 *
72 * After the handle scope of a local handle has been deleted the
73 * garbage collector will no longer track the object stored in the
74 * handle and may deallocate it.  The behavior of accessing a handle
75 * for which the handle scope has been deleted is undefined.
76 */
77class V8_EXPORT V8_NODISCARD HandleScope {
78 public:
79  explicit HandleScope(Isolate* isolate);
80
81  ~HandleScope();
82
83  /**
84   * Counts the number of allocated handles.
85   */
86  static int NumberOfHandles(Isolate* isolate);
87
88  V8_INLINE Isolate* GetIsolate() const {
89    return reinterpret_cast<Isolate*>(isolate_);
90  }
91
92  HandleScope(const HandleScope&) = delete;
93  void operator=(const HandleScope&) = delete;
94
95 protected:
96  V8_INLINE HandleScope() = default;
97
98  void Initialize(Isolate* isolate);
99
100  static internal::Address* CreateHandle(internal::Isolate* isolate,
101                                         internal::Address value);
102
103 private:
104  // Declaring operator new and delete as deleted is not spec compliant.
105  // Therefore declare them private instead to disable dynamic alloc
106  void* operator new(size_t size);
107  void* operator new[](size_t size);
108  void operator delete(void*, size_t);
109  void operator delete[](void*, size_t);
110
111  internal::Isolate* isolate_;
112  internal::Address* prev_next_;
113  internal::Address* prev_limit_;
114
115  // Local::New uses CreateHandle with an Isolate* parameter.
116  template <class F>
117  friend class Local;
118
119  // Object::GetInternalField and Context::GetEmbedderData use CreateHandle with
120  // a HeapObject in their shortcuts.
121  friend class Object;
122  friend class Context;
123};
124
125/**
126 * An object reference managed by the v8 garbage collector.
127 *
128 * All objects returned from v8 have to be tracked by the garbage collector so
129 * that it knows that the objects are still alive.  Also, because the garbage
130 * collector may move objects, it is unsafe to point directly to an object.
131 * Instead, all objects are stored in handles which are known by the garbage
132 * collector and updated whenever an object moves.  Handles should always be
133 * passed by value (except in cases like out-parameters) and they should never
134 * be allocated on the heap.
135 *
136 * There are two types of handles: local and persistent handles.
137 *
138 * Local handles are light-weight and transient and typically used in local
139 * operations.  They are managed by HandleScopes. That means that a HandleScope
140 * must exist on the stack when they are created and that they are only valid
141 * inside of the HandleScope active during their creation. For passing a local
142 * handle to an outer HandleScope, an EscapableHandleScope and its Escape()
143 * method must be used.
144 *
145 * Persistent handles can be used when storing objects across several
146 * independent operations and have to be explicitly deallocated when they're no
147 * longer used.
148 *
149 * It is safe to extract the object stored in the handle by dereferencing the
150 * handle (for instance, to extract the Object* from a Local<Object>); the value
151 * will still be governed by a handle behind the scenes and the same rules apply
152 * to these values as to their handles.
153 */
154template <class T>
155class Local {
156 public:
157  V8_INLINE Local() : val_(nullptr) {}
158  template <class S>
159  V8_INLINE Local(Local<S> that) : val_(reinterpret_cast<T*>(*that)) {
160    /**
161     * This check fails when trying to convert between incompatible
162     * handles. For example, converting from a Local<String> to a
163     * Local<Number>.
164     */
165    static_assert(std::is_base_of<T, S>::value, "type check");
166  }
167
168  /**
169   * Returns true if the handle is empty.
170   */
171  V8_INLINE bool IsEmpty() const { return val_ == nullptr; }
172
173  /**
174   * Sets the handle to be empty. IsEmpty() will then return true.
175   */
176  V8_INLINE void Clear() { val_ = nullptr; }
177
178  V8_INLINE T* operator->() const { return val_; }
179
180  V8_INLINE T* operator*() const { return val_; }
181
182  /**
183   * Checks whether two handles are the same.
184   * Returns true if both are empty, or if the objects to which they refer
185   * are identical.
186   *
187   * If both handles refer to JS objects, this is the same as strict equality.
188   * For primitives, such as numbers or strings, a `false` return value does not
189   * indicate that the values aren't equal in the JavaScript sense.
190   * Use `Value::StrictEquals()` to check primitives for equality.
191   */
192  template <class S>
193  V8_INLINE bool operator==(const Local<S>& that) const {
194    internal::Address* a = reinterpret_cast<internal::Address*>(this->val_);
195    internal::Address* b = reinterpret_cast<internal::Address*>(that.val_);
196    if (a == nullptr) return b == nullptr;
197    if (b == nullptr) return false;
198    return *a == *b;
199  }
200
201  template <class S>
202  V8_INLINE bool operator==(const PersistentBase<S>& that) const {
203    internal::Address* a = reinterpret_cast<internal::Address*>(this->val_);
204    internal::Address* b = reinterpret_cast<internal::Address*>(that.val_);
205    if (a == nullptr) return b == nullptr;
206    if (b == nullptr) return false;
207    return *a == *b;
208  }
209
210  /**
211   * Checks whether two handles are different.
212   * Returns true if only one of the handles is empty, or if
213   * the objects to which they refer are different.
214   *
215   * If both handles refer to JS objects, this is the same as strict
216   * non-equality. For primitives, such as numbers or strings, a `true` return
217   * value does not indicate that the values aren't equal in the JavaScript
218   * sense. Use `Value::StrictEquals()` to check primitives for equality.
219   */
220  template <class S>
221  V8_INLINE bool operator!=(const Local<S>& that) const {
222    return !operator==(that);
223  }
224
225  template <class S>
226  V8_INLINE bool operator!=(const Persistent<S>& that) const {
227    return !operator==(that);
228  }
229
230  /**
231   * Cast a handle to a subclass, e.g. Local<Value> to Local<Object>.
232   * This is only valid if the handle actually refers to a value of the
233   * target type.
234   */
235  template <class S>
236  V8_INLINE static Local<T> Cast(Local<S> that) {
237#ifdef V8_ENABLE_CHECKS
238    // If we're going to perform the type check then we have to check
239    // that the handle isn't empty before doing the checked cast.
240    if (that.IsEmpty()) return Local<T>();
241#endif
242    return Local<T>(T::Cast(*that));
243  }
244
245  /**
246   * Calling this is equivalent to Local<S>::Cast().
247   * In particular, this is only valid if the handle actually refers to a value
248   * of the target type.
249   */
250  template <class S>
251  V8_INLINE Local<S> As() const {
252    return Local<S>::Cast(*this);
253  }
254
255  /**
256   * Create a local handle for the content of another handle.
257   * The referee is kept alive by the local handle even when
258   * the original handle is destroyed/disposed.
259   */
260  V8_INLINE static Local<T> New(Isolate* isolate, Local<T> that) {
261    return New(isolate, that.val_);
262  }
263
264  V8_INLINE static Local<T> New(Isolate* isolate,
265                                const PersistentBase<T>& that) {
266    return New(isolate, that.val_);
267  }
268
269  V8_INLINE static Local<T> New(Isolate* isolate,
270                                const BasicTracedReference<T>& that) {
271    return New(isolate, *that);
272  }
273
274 private:
275  friend class TracedReferenceBase;
276  friend class Utils;
277  template <class F>
278  friend class Eternal;
279  template <class F>
280  friend class PersistentBase;
281  template <class F, class M>
282  friend class Persistent;
283  template <class F>
284  friend class Local;
285  template <class F>
286  friend class MaybeLocal;
287  template <class F>
288  friend class FunctionCallbackInfo;
289  template <class F>
290  friend class PropertyCallbackInfo;
291  friend class String;
292  friend class Object;
293  friend class Context;
294  friend class Isolate;
295  friend class Private;
296  template <class F>
297  friend class internal::CustomArguments;
298  friend Local<Primitive> Undefined(Isolate* isolate);
299  friend Local<Primitive> Null(Isolate* isolate);
300  friend Local<Boolean> True(Isolate* isolate);
301  friend Local<Boolean> False(Isolate* isolate);
302  friend class HandleScope;
303  friend class EscapableHandleScope;
304  template <class F1, class F2, class F3>
305  friend class PersistentValueMapBase;
306  template <class F1, class F2>
307  friend class PersistentValueVector;
308  template <class F>
309  friend class ReturnValue;
310  template <class F>
311  friend class Traced;
312  template <class F>
313  friend class BasicTracedReference;
314  template <class F>
315  friend class TracedReference;
316
317  explicit V8_INLINE Local(T* that) : val_(that) {}
318  V8_INLINE static Local<T> New(Isolate* isolate, T* that) {
319    if (that == nullptr) return Local<T>();
320    T* that_ptr = that;
321    internal::Address* p = reinterpret_cast<internal::Address*>(that_ptr);
322    return Local<T>(reinterpret_cast<T*>(HandleScope::CreateHandle(
323        reinterpret_cast<internal::Isolate*>(isolate), *p)));
324  }
325  T* val_;
326};
327
328#if !defined(V8_IMMINENT_DEPRECATION_WARNINGS)
329// Handle is an alias for Local for historical reasons.
330template <class T>
331using Handle = Local<T>;
332#endif
333
334/**
335 * A MaybeLocal<> is a wrapper around Local<> that enforces a check whether
336 * the Local<> is empty before it can be used.
337 *
338 * If an API method returns a MaybeLocal<>, the API method can potentially fail
339 * either because an exception is thrown, or because an exception is pending,
340 * e.g. because a previous API call threw an exception that hasn't been caught
341 * yet, or because a TerminateExecution exception was thrown. In that case, an
342 * empty MaybeLocal is returned.
343 */
344template <class T>
345class MaybeLocal {
346 public:
347  V8_INLINE MaybeLocal() : val_(nullptr) {}
348  template <class S>
349  V8_INLINE MaybeLocal(Local<S> that) : val_(reinterpret_cast<T*>(*that)) {
350    static_assert(std::is_base_of<T, S>::value, "type check");
351  }
352
353  V8_INLINE bool IsEmpty() const { return val_ == nullptr; }
354
355  /**
356   * Converts this MaybeLocal<> to a Local<>. If this MaybeLocal<> is empty,
357   * |false| is returned and |out| is left untouched.
358   */
359  template <class S>
360  V8_WARN_UNUSED_RESULT V8_INLINE bool ToLocal(Local<S>* out) const {
361    out->val_ = IsEmpty() ? nullptr : this->val_;
362    return !IsEmpty();
363  }
364
365  /**
366   * Converts this MaybeLocal<> to a Local<>. If this MaybeLocal<> is empty,
367   * V8 will crash the process.
368   */
369  V8_INLINE Local<T> ToLocalChecked() {
370    if (V8_UNLIKELY(val_ == nullptr)) api_internal::ToLocalEmpty();
371    return Local<T>(val_);
372  }
373
374  /**
375   * Converts this MaybeLocal<> to a Local<>, using a default value if this
376   * MaybeLocal<> is empty.
377   */
378  template <class S>
379  V8_INLINE Local<S> FromMaybe(Local<S> default_value) const {
380    return IsEmpty() ? default_value : Local<S>(val_);
381  }
382
383 private:
384  T* val_;
385};
386
387/**
388 * A HandleScope which first allocates a handle in the current scope
389 * which will be later filled with the escape value.
390 */
391class V8_EXPORT V8_NODISCARD EscapableHandleScope : public HandleScope {
392 public:
393  explicit EscapableHandleScope(Isolate* isolate);
394  V8_INLINE ~EscapableHandleScope() = default;
395
396  /**
397   * Pushes the value into the previous scope and returns a handle to it.
398   * Cannot be called twice.
399   */
400  template <class T>
401  V8_INLINE Local<T> Escape(Local<T> value) {
402    internal::Address* slot =
403        Escape(reinterpret_cast<internal::Address*>(*value));
404    return Local<T>(reinterpret_cast<T*>(slot));
405  }
406
407  template <class T>
408  V8_INLINE MaybeLocal<T> EscapeMaybe(MaybeLocal<T> value) {
409    return Escape(value.FromMaybe(Local<T>()));
410  }
411
412  EscapableHandleScope(const EscapableHandleScope&) = delete;
413  void operator=(const EscapableHandleScope&) = delete;
414
415 private:
416  // Declaring operator new and delete as deleted is not spec compliant.
417  // Therefore declare them private instead to disable dynamic alloc
418  void* operator new(size_t size);
419  void* operator new[](size_t size);
420  void operator delete(void*, size_t);
421  void operator delete[](void*, size_t);
422
423  internal::Address* Escape(internal::Address* escape_value);
424  internal::Address* escape_slot_;
425};
426
427/**
428 * A SealHandleScope acts like a handle scope in which no handle allocations
429 * are allowed. It can be useful for debugging handle leaks.
430 * Handles can be allocated within inner normal HandleScopes.
431 */
432class V8_EXPORT V8_NODISCARD SealHandleScope {
433 public:
434  explicit SealHandleScope(Isolate* isolate);
435  ~SealHandleScope();
436
437  SealHandleScope(const SealHandleScope&) = delete;
438  void operator=(const SealHandleScope&) = delete;
439
440 private:
441  // Declaring operator new and delete as deleted is not spec compliant.
442  // Therefore declare them private instead to disable dynamic alloc
443  void* operator new(size_t size);
444  void* operator new[](size_t size);
445  void operator delete(void*, size_t);
446  void operator delete[](void*, size_t);
447
448  internal::Isolate* const isolate_;
449  internal::Address* prev_limit_;
450  int prev_sealed_level_;
451};
452
453}  // namespace v8
454
455#endif  // INCLUDE_V8_LOCAL_HANDLE_H_
456