v8-promise.h 5.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174
  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_PROMISE_H_
  5. #define INCLUDE_V8_PROMISE_H_
  6. #include "v8-local-handle.h" // NOLINT(build/include_directory)
  7. #include "v8-object.h" // NOLINT(build/include_directory)
  8. #include "v8config.h" // NOLINT(build/include_directory)
  9. namespace v8 {
  10. class Context;
  11. #ifndef V8_PROMISE_INTERNAL_FIELD_COUNT
  12. // The number of required internal fields can be defined by embedder.
  13. #define V8_PROMISE_INTERNAL_FIELD_COUNT 0
  14. #endif
  15. /**
  16. * An instance of the built-in Promise constructor (ES6 draft).
  17. */
  18. class V8_EXPORT Promise : public Object {
  19. public:
  20. /**
  21. * State of the promise. Each value corresponds to one of the possible values
  22. * of the [[PromiseState]] field.
  23. */
  24. enum PromiseState { kPending, kFulfilled, kRejected };
  25. class V8_EXPORT Resolver : public Object {
  26. public:
  27. /**
  28. * Create a new resolver, along with an associated promise in pending state.
  29. */
  30. static V8_WARN_UNUSED_RESULT MaybeLocal<Resolver> New(
  31. Local<Context> context);
  32. /**
  33. * Extract the associated promise.
  34. */
  35. Local<Promise> GetPromise();
  36. /**
  37. * Resolve/reject the associated promise with a given value.
  38. * Ignored if the promise is no longer pending.
  39. */
  40. V8_WARN_UNUSED_RESULT Maybe<bool> Resolve(Local<Context> context,
  41. Local<Value> value);
  42. V8_WARN_UNUSED_RESULT Maybe<bool> Reject(Local<Context> context,
  43. Local<Value> value);
  44. V8_INLINE static Resolver* Cast(Value* value) {
  45. #ifdef V8_ENABLE_CHECKS
  46. CheckCast(value);
  47. #endif
  48. return static_cast<Promise::Resolver*>(value);
  49. }
  50. private:
  51. Resolver();
  52. static void CheckCast(Value* obj);
  53. };
  54. /**
  55. * Register a resolution/rejection handler with a promise.
  56. * The handler is given the respective resolution/rejection value as
  57. * an argument. If the promise is already resolved/rejected, the handler is
  58. * invoked at the end of turn.
  59. */
  60. V8_WARN_UNUSED_RESULT MaybeLocal<Promise> Catch(Local<Context> context,
  61. Local<Function> handler);
  62. V8_WARN_UNUSED_RESULT MaybeLocal<Promise> Then(Local<Context> context,
  63. Local<Function> handler);
  64. V8_WARN_UNUSED_RESULT MaybeLocal<Promise> Then(Local<Context> context,
  65. Local<Function> on_fulfilled,
  66. Local<Function> on_rejected);
  67. /**
  68. * Returns true if the promise has at least one derived promise, and
  69. * therefore resolve/reject handlers (including default handler).
  70. */
  71. bool HasHandler() const;
  72. /**
  73. * Returns the content of the [[PromiseResult]] field. The Promise must not
  74. * be pending.
  75. */
  76. Local<Value> Result();
  77. /**
  78. * Returns the value of the [[PromiseState]] field.
  79. */
  80. PromiseState State();
  81. /**
  82. * Marks this promise as handled to avoid reporting unhandled rejections.
  83. */
  84. void MarkAsHandled();
  85. /**
  86. * Marks this promise as silent to prevent pausing the debugger when the
  87. * promise is rejected.
  88. */
  89. void MarkAsSilent();
  90. V8_INLINE static Promise* Cast(Value* value) {
  91. #ifdef V8_ENABLE_CHECKS
  92. CheckCast(value);
  93. #endif
  94. return static_cast<Promise*>(value);
  95. }
  96. static const int kEmbedderFieldCount = V8_PROMISE_INTERNAL_FIELD_COUNT;
  97. private:
  98. Promise();
  99. static void CheckCast(Value* obj);
  100. };
  101. /**
  102. * PromiseHook with type kInit is called when a new promise is
  103. * created. When a new promise is created as part of the chain in the
  104. * case of Promise.then or in the intermediate promises created by
  105. * Promise.{race, all}/AsyncFunctionAwait, we pass the parent promise
  106. * otherwise we pass undefined.
  107. *
  108. * PromiseHook with type kResolve is called at the beginning of
  109. * resolve or reject function defined by CreateResolvingFunctions.
  110. *
  111. * PromiseHook with type kBefore is called at the beginning of the
  112. * PromiseReactionJob.
  113. *
  114. * PromiseHook with type kAfter is called right at the end of the
  115. * PromiseReactionJob.
  116. */
  117. enum class PromiseHookType { kInit, kResolve, kBefore, kAfter };
  118. using PromiseHook = void (*)(PromiseHookType type, Local<Promise> promise,
  119. Local<Value> parent);
  120. // --- Promise Reject Callback ---
  121. enum PromiseRejectEvent {
  122. kPromiseRejectWithNoHandler = 0,
  123. kPromiseHandlerAddedAfterReject = 1,
  124. kPromiseRejectAfterResolved = 2,
  125. kPromiseResolveAfterResolved = 3,
  126. };
  127. class PromiseRejectMessage {
  128. public:
  129. PromiseRejectMessage(Local<Promise> promise, PromiseRejectEvent event,
  130. Local<Value> value)
  131. : promise_(promise), event_(event), value_(value) {}
  132. V8_INLINE Local<Promise> GetPromise() const { return promise_; }
  133. V8_INLINE PromiseRejectEvent GetEvent() const { return event_; }
  134. V8_INLINE Local<Value> GetValue() const { return value_; }
  135. private:
  136. Local<Promise> promise_;
  137. PromiseRejectEvent event_;
  138. Local<Value> value_;
  139. };
  140. using PromiseRejectCallback = void (*)(PromiseRejectMessage message);
  141. } // namespace v8
  142. #endif // INCLUDE_V8_PROMISE_H_