v8-locker.h 4.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149
  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_LOCKER_H_
  5. #define INCLUDE_V8_LOCKER_H_
  6. #include "v8config.h" // NOLINT(build/include_directory)
  7. namespace v8 {
  8. namespace internal {
  9. class Isolate;
  10. } // namespace internal
  11. class Isolate;
  12. /**
  13. * Multiple threads in V8 are allowed, but only one thread at a time is allowed
  14. * to use any given V8 isolate, see the comments in the Isolate class. The
  15. * definition of 'using a V8 isolate' includes accessing handles or holding onto
  16. * object pointers obtained from V8 handles while in the particular V8 isolate.
  17. * It is up to the user of V8 to ensure, perhaps with locking, that this
  18. * constraint is not violated. In addition to any other synchronization
  19. * mechanism that may be used, the v8::Locker and v8::Unlocker classes must be
  20. * used to signal thread switches to V8.
  21. *
  22. * v8::Locker is a scoped lock object. While it's active, i.e. between its
  23. * construction and destruction, the current thread is allowed to use the locked
  24. * isolate. V8 guarantees that an isolate can be locked by at most one thread at
  25. * any time. In other words, the scope of a v8::Locker is a critical section.
  26. *
  27. * Sample usage:
  28. * \code
  29. * ...
  30. * {
  31. * v8::Locker locker(isolate);
  32. * v8::Isolate::Scope isolate_scope(isolate);
  33. * ...
  34. * // Code using V8 and isolate goes here.
  35. * ...
  36. * } // Destructor called here
  37. * \endcode
  38. *
  39. * If you wish to stop using V8 in a thread A you can do this either by
  40. * destroying the v8::Locker object as above or by constructing a v8::Unlocker
  41. * object:
  42. *
  43. * \code
  44. * {
  45. * isolate->Exit();
  46. * v8::Unlocker unlocker(isolate);
  47. * ...
  48. * // Code not using V8 goes here while V8 can run in another thread.
  49. * ...
  50. * } // Destructor called here.
  51. * isolate->Enter();
  52. * \endcode
  53. *
  54. * The Unlocker object is intended for use in a long-running callback from V8,
  55. * where you want to release the V8 lock for other threads to use.
  56. *
  57. * The v8::Locker is a recursive lock, i.e. you can lock more than once in a
  58. * given thread. This can be useful if you have code that can be called either
  59. * from code that holds the lock or from code that does not. The Unlocker is
  60. * not recursive so you can not have several Unlockers on the stack at once, and
  61. * you cannot use an Unlocker in a thread that is not inside a Locker's scope.
  62. *
  63. * An unlocker will unlock several lockers if it has to and reinstate the
  64. * correct depth of locking on its destruction, e.g.:
  65. *
  66. * \code
  67. * // V8 not locked.
  68. * {
  69. * v8::Locker locker(isolate);
  70. * Isolate::Scope isolate_scope(isolate);
  71. * // V8 locked.
  72. * {
  73. * v8::Locker another_locker(isolate);
  74. * // V8 still locked (2 levels).
  75. * {
  76. * isolate->Exit();
  77. * v8::Unlocker unlocker(isolate);
  78. * // V8 not locked.
  79. * }
  80. * isolate->Enter();
  81. * // V8 locked again (2 levels).
  82. * }
  83. * // V8 still locked (1 level).
  84. * }
  85. * // V8 Now no longer locked.
  86. * \endcode
  87. */
  88. class V8_EXPORT Unlocker {
  89. public:
  90. /**
  91. * Initialize Unlocker for a given Isolate.
  92. */
  93. V8_INLINE explicit Unlocker(Isolate* isolate) { Initialize(isolate); }
  94. ~Unlocker();
  95. private:
  96. void Initialize(Isolate* isolate);
  97. internal::Isolate* isolate_;
  98. };
  99. class V8_EXPORT Locker {
  100. public:
  101. /**
  102. * Initialize Locker for a given Isolate.
  103. */
  104. V8_INLINE explicit Locker(Isolate* isolate) { Initialize(isolate); }
  105. ~Locker();
  106. /**
  107. * Returns whether or not the locker for a given isolate, is locked by the
  108. * current thread.
  109. */
  110. static bool IsLocked(Isolate* isolate);
  111. /**
  112. * Returns whether any v8::Locker has ever been used in this process.
  113. * TODO(cbruni, chromium:1240851): Fix locking checks on a per-thread basis.
  114. * The current implementation is quite confusing and leads to unexpected
  115. * results if anybody uses v8::Locker in the current process.
  116. */
  117. V8_DEPRECATE_SOON("This method will be removed.")
  118. static bool WasEverUsed();
  119. V8_DEPRECATED("Use WasEverUsed instead")
  120. static bool IsActive();
  121. // Disallow copying and assigning.
  122. Locker(const Locker&) = delete;
  123. void operator=(const Locker&) = delete;
  124. private:
  125. void Initialize(Isolate* isolate);
  126. bool has_lock_;
  127. bool top_level_;
  128. internal::Isolate* isolate_;
  129. };
  130. } // namespace v8
  131. #endif // INCLUDE_V8_LOCKER_H_