v8-traced-handle.h 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420
  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. #ifndef INCLUDE_V8_TRACED_HANDLE_H_
  5. #define INCLUDE_V8_TRACED_HANDLE_H_
  6. #include <stddef.h>
  7. #include <stdint.h>
  8. #include <stdio.h>
  9. #include <atomic>
  10. #include <memory>
  11. #include <type_traits>
  12. #include <utility>
  13. #include "v8-internal.h" // NOLINT(build/include_directory)
  14. #include "v8-local-handle.h" // NOLINT(build/include_directory)
  15. #include "v8-weak-callback-info.h" // NOLINT(build/include_directory)
  16. #include "v8config.h" // NOLINT(build/include_directory)
  17. namespace v8 {
  18. class Value;
  19. namespace internal {
  20. class BasicTracedReferenceExtractor;
  21. enum class GlobalHandleStoreMode {
  22. kInitializingStore,
  23. kAssigningStore,
  24. };
  25. V8_EXPORT internal::Address* GlobalizeTracedReference(
  26. internal::Isolate* isolate, internal::Address* handle,
  27. internal::Address* slot, GlobalHandleStoreMode store_mode);
  28. V8_EXPORT void MoveTracedReference(internal::Address** from,
  29. internal::Address** to);
  30. V8_EXPORT void CopyTracedReference(const internal::Address* const* from,
  31. internal::Address** to);
  32. V8_EXPORT void DisposeTracedReference(internal::Address* global_handle);
  33. } // namespace internal
  34. class TracedReferenceBase {
  35. public:
  36. /**
  37. * Returns true if the reference is empty, i.e., has not been assigned
  38. * object.
  39. */
  40. bool IsEmpty() const { return val_ == nullptr; }
  41. /**
  42. * If non-empty, destroy the underlying storage cell. |IsEmpty| will return
  43. * true after this call.
  44. */
  45. V8_INLINE void Reset();
  46. /**
  47. * Construct a Local<Value> from this handle.
  48. */
  49. V8_INLINE v8::Local<v8::Value> Get(v8::Isolate* isolate) const {
  50. if (IsEmpty()) return Local<Value>();
  51. return Local<Value>::New(isolate, reinterpret_cast<Value*>(val_));
  52. }
  53. /**
  54. * Returns true if this TracedReference is empty, i.e., has not been
  55. * assigned an object. This version of IsEmpty is thread-safe.
  56. */
  57. bool IsEmptyThreadSafe() const {
  58. return this->GetSlotThreadSafe() == nullptr;
  59. }
  60. /**
  61. * Assigns a wrapper class ID to the handle.
  62. */
  63. V8_INLINE void SetWrapperClassId(uint16_t class_id);
  64. /**
  65. * Returns the class ID previously assigned to this handle or 0 if no class ID
  66. * was previously assigned.
  67. */
  68. V8_INLINE uint16_t WrapperClassId() const;
  69. protected:
  70. /**
  71. * Update this reference in a thread-safe way.
  72. */
  73. void SetSlotThreadSafe(void* new_val) {
  74. reinterpret_cast<std::atomic<void*>*>(&val_)->store(
  75. new_val, std::memory_order_relaxed);
  76. }
  77. /**
  78. * Get this reference in a thread-safe way
  79. */
  80. const void* GetSlotThreadSafe() const {
  81. return reinterpret_cast<std::atomic<const void*> const*>(&val_)->load(
  82. std::memory_order_relaxed);
  83. }
  84. V8_EXPORT void CheckValue() const;
  85. // val_ points to a GlobalHandles node.
  86. internal::Address* val_ = nullptr;
  87. friend class internal::BasicTracedReferenceExtractor;
  88. template <typename F>
  89. friend class Local;
  90. template <typename U>
  91. friend bool operator==(const TracedReferenceBase&, const Local<U>&);
  92. friend bool operator==(const TracedReferenceBase&,
  93. const TracedReferenceBase&);
  94. };
  95. /**
  96. * A traced handle with copy and move semantics. The handle is to be used
  97. * together with |v8::EmbedderHeapTracer| or as part of GarbageCollected objects
  98. * (see v8-cppgc.h) and specifies edges from C++ objects to JavaScript.
  99. *
  100. * The exact semantics are:
  101. * - Tracing garbage collections use |v8::EmbedderHeapTracer| or cppgc.
  102. * - Non-tracing garbage collections refer to
  103. * |v8::EmbedderRootsHandler::IsRoot()| whether the handle should
  104. * be treated as root or not.
  105. *
  106. * Note that the base class cannot be instantiated itself, use |TracedReference|
  107. * instead.
  108. */
  109. template <typename T>
  110. class BasicTracedReference : public TracedReferenceBase {
  111. public:
  112. /**
  113. * Construct a Local<T> from this handle.
  114. */
  115. Local<T> Get(Isolate* isolate) const { return Local<T>::New(isolate, *this); }
  116. template <class S>
  117. V8_INLINE BasicTracedReference<S>& As() const {
  118. return reinterpret_cast<BasicTracedReference<S>&>(
  119. const_cast<BasicTracedReference<T>&>(*this));
  120. }
  121. T* operator->() const {
  122. #ifdef V8_ENABLE_CHECKS
  123. CheckValue();
  124. #endif // V8_ENABLE_CHECKS
  125. return reinterpret_cast<T*>(val_);
  126. }
  127. T* operator*() const {
  128. #ifdef V8_ENABLE_CHECKS
  129. CheckValue();
  130. #endif // V8_ENABLE_CHECKS
  131. return reinterpret_cast<T*>(val_);
  132. }
  133. private:
  134. /**
  135. * An empty BasicTracedReference without storage cell.
  136. */
  137. BasicTracedReference() = default;
  138. V8_INLINE static internal::Address* New(
  139. Isolate* isolate, T* that, void* slot,
  140. internal::GlobalHandleStoreMode store_mode);
  141. friend class EmbedderHeapTracer;
  142. template <typename F>
  143. friend class Local;
  144. friend class Object;
  145. template <typename F>
  146. friend class TracedReference;
  147. template <typename F>
  148. friend class BasicTracedReference;
  149. template <typename F>
  150. friend class ReturnValue;
  151. };
  152. /**
  153. * A traced handle without destructor that clears the handle. The embedder needs
  154. * to ensure that the handle is not accessed once the V8 object has been
  155. * reclaimed. This can happen when the handle is not passed through the
  156. * EmbedderHeapTracer. For more details see BasicTracedReference.
  157. *
  158. * The reference assumes the embedder has precise knowledge about references at
  159. * all times. In case V8 needs to separately handle on-stack references, the
  160. * embedder is required to set the stack start through
  161. * |EmbedderHeapTracer::SetStackStart|.
  162. */
  163. template <typename T>
  164. class TracedReference : public BasicTracedReference<T> {
  165. public:
  166. using BasicTracedReference<T>::Reset;
  167. /**
  168. * An empty TracedReference without storage cell.
  169. */
  170. TracedReference() : BasicTracedReference<T>() {}
  171. /**
  172. * Construct a TracedReference from a Local.
  173. *
  174. * When the Local is non-empty, a new storage cell is created
  175. * pointing to the same object.
  176. */
  177. template <class S>
  178. TracedReference(Isolate* isolate, Local<S> that) : BasicTracedReference<T>() {
  179. this->val_ = this->New(isolate, that.val_, &this->val_,
  180. internal::GlobalHandleStoreMode::kInitializingStore);
  181. static_assert(std::is_base_of<T, S>::value, "type check");
  182. }
  183. /**
  184. * Move constructor initializing TracedReference from an
  185. * existing one.
  186. */
  187. V8_INLINE TracedReference(TracedReference&& other) noexcept {
  188. // Forward to operator=.
  189. *this = std::move(other);
  190. }
  191. /**
  192. * Move constructor initializing TracedReference from an
  193. * existing one.
  194. */
  195. template <typename S>
  196. V8_INLINE TracedReference(TracedReference<S>&& other) noexcept {
  197. // Forward to operator=.
  198. *this = std::move(other);
  199. }
  200. /**
  201. * Copy constructor initializing TracedReference from an
  202. * existing one.
  203. */
  204. V8_INLINE TracedReference(const TracedReference& other) {
  205. // Forward to operator=;
  206. *this = other;
  207. }
  208. /**
  209. * Copy constructor initializing TracedReference from an
  210. * existing one.
  211. */
  212. template <typename S>
  213. V8_INLINE TracedReference(const TracedReference<S>& other) {
  214. // Forward to operator=;
  215. *this = other;
  216. }
  217. /**
  218. * Move assignment operator initializing TracedReference from an existing one.
  219. */
  220. V8_INLINE TracedReference& operator=(TracedReference&& rhs) noexcept;
  221. /**
  222. * Move assignment operator initializing TracedReference from an existing one.
  223. */
  224. template <class S>
  225. V8_INLINE TracedReference& operator=(TracedReference<S>&& rhs) noexcept;
  226. /**
  227. * Copy assignment operator initializing TracedReference from an existing one.
  228. */
  229. V8_INLINE TracedReference& operator=(const TracedReference& rhs);
  230. /**
  231. * Copy assignment operator initializing TracedReference from an existing one.
  232. */
  233. template <class S>
  234. V8_INLINE TracedReference& operator=(const TracedReference<S>& rhs);
  235. /**
  236. * If non-empty, destroy the underlying storage cell and create a new one with
  237. * the contents of other if other is non empty
  238. */
  239. template <class S>
  240. V8_INLINE void Reset(Isolate* isolate, const Local<S>& other);
  241. template <class S>
  242. V8_INLINE TracedReference<S>& As() const {
  243. return reinterpret_cast<TracedReference<S>&>(
  244. const_cast<TracedReference<T>&>(*this));
  245. }
  246. };
  247. // --- Implementation ---
  248. template <class T>
  249. internal::Address* BasicTracedReference<T>::New(
  250. Isolate* isolate, T* that, void* slot,
  251. internal::GlobalHandleStoreMode store_mode) {
  252. if (that == nullptr) return nullptr;
  253. internal::Address* p = reinterpret_cast<internal::Address*>(that);
  254. return internal::GlobalizeTracedReference(
  255. reinterpret_cast<internal::Isolate*>(isolate), p,
  256. reinterpret_cast<internal::Address*>(slot), store_mode);
  257. }
  258. void TracedReferenceBase::Reset() {
  259. if (IsEmpty()) return;
  260. internal::DisposeTracedReference(reinterpret_cast<internal::Address*>(val_));
  261. SetSlotThreadSafe(nullptr);
  262. }
  263. V8_INLINE bool operator==(const TracedReferenceBase& lhs,
  264. const TracedReferenceBase& rhs) {
  265. v8::internal::Address* a = reinterpret_cast<v8::internal::Address*>(lhs.val_);
  266. v8::internal::Address* b = reinterpret_cast<v8::internal::Address*>(rhs.val_);
  267. if (a == nullptr) return b == nullptr;
  268. if (b == nullptr) return false;
  269. return *a == *b;
  270. }
  271. template <typename U>
  272. V8_INLINE bool operator==(const TracedReferenceBase& lhs,
  273. const v8::Local<U>& rhs) {
  274. v8::internal::Address* a = reinterpret_cast<v8::internal::Address*>(lhs.val_);
  275. v8::internal::Address* b = reinterpret_cast<v8::internal::Address*>(*rhs);
  276. if (a == nullptr) return b == nullptr;
  277. if (b == nullptr) return false;
  278. return *a == *b;
  279. }
  280. template <typename U>
  281. V8_INLINE bool operator==(const v8::Local<U>& lhs,
  282. const TracedReferenceBase& rhs) {
  283. return rhs == lhs;
  284. }
  285. V8_INLINE bool operator!=(const TracedReferenceBase& lhs,
  286. const TracedReferenceBase& rhs) {
  287. return !(lhs == rhs);
  288. }
  289. template <typename U>
  290. V8_INLINE bool operator!=(const TracedReferenceBase& lhs,
  291. const v8::Local<U>& rhs) {
  292. return !(lhs == rhs);
  293. }
  294. template <typename U>
  295. V8_INLINE bool operator!=(const v8::Local<U>& lhs,
  296. const TracedReferenceBase& rhs) {
  297. return !(rhs == lhs);
  298. }
  299. template <class T>
  300. template <class S>
  301. void TracedReference<T>::Reset(Isolate* isolate, const Local<S>& other) {
  302. static_assert(std::is_base_of<T, S>::value, "type check");
  303. this->Reset();
  304. if (other.IsEmpty()) return;
  305. this->SetSlotThreadSafe(
  306. this->New(isolate, other.val_, &this->val_,
  307. internal::GlobalHandleStoreMode::kAssigningStore));
  308. }
  309. template <class T>
  310. template <class S>
  311. TracedReference<T>& TracedReference<T>::operator=(
  312. TracedReference<S>&& rhs) noexcept {
  313. static_assert(std::is_base_of<T, S>::value, "type check");
  314. *this = std::move(rhs.template As<T>());
  315. return *this;
  316. }
  317. template <class T>
  318. template <class S>
  319. TracedReference<T>& TracedReference<T>::operator=(
  320. const TracedReference<S>& rhs) {
  321. static_assert(std::is_base_of<T, S>::value, "type check");
  322. *this = rhs.template As<T>();
  323. return *this;
  324. }
  325. template <class T>
  326. TracedReference<T>& TracedReference<T>::operator=(
  327. TracedReference&& rhs) noexcept {
  328. if (this != &rhs) {
  329. internal::MoveTracedReference(
  330. reinterpret_cast<internal::Address**>(&rhs.val_),
  331. reinterpret_cast<internal::Address**>(&this->val_));
  332. }
  333. return *this;
  334. }
  335. template <class T>
  336. TracedReference<T>& TracedReference<T>::operator=(const TracedReference& rhs) {
  337. if (this != &rhs) {
  338. this->Reset();
  339. if (rhs.val_ != nullptr) {
  340. internal::CopyTracedReference(
  341. reinterpret_cast<const internal::Address* const*>(&rhs.val_),
  342. reinterpret_cast<internal::Address**>(&this->val_));
  343. }
  344. }
  345. return *this;
  346. }
  347. void TracedReferenceBase::SetWrapperClassId(uint16_t class_id) {
  348. using I = internal::Internals;
  349. if (IsEmpty()) return;
  350. internal::Address* obj = reinterpret_cast<internal::Address*>(val_);
  351. uint8_t* addr = reinterpret_cast<uint8_t*>(obj) + I::kNodeClassIdOffset;
  352. *reinterpret_cast<uint16_t*>(addr) = class_id;
  353. }
  354. uint16_t TracedReferenceBase::WrapperClassId() const {
  355. using I = internal::Internals;
  356. if (IsEmpty()) return 0;
  357. internal::Address* obj = reinterpret_cast<internal::Address*>(val_);
  358. uint8_t* addr = reinterpret_cast<uint8_t*>(obj) + I::kNodeClassIdOffset;
  359. return *reinterpret_cast<uint16_t*>(addr);
  360. }
  361. } // namespace v8
  362. #endif // INCLUDE_V8_TRACED_HANDLE_H_