include/node/v8-promise.h

0001 // Copyright 2021 the V8 project authors. All rights reserved.
0002 // Use of this source code is governed by a BSD-style license that can be
0003 // found in the LICENSE file.
0004
0005 #ifndef INCLUDE_V8_PROMISE_H_
0006 #define INCLUDE_V8_PROMISE_H_
0007
0008 #include "v8-local-handle.h"  // NOLINT(build/include_directory)
0009 #include "v8-object.h"        // NOLINT(build/include_directory)
0010 #include "v8config.h"         // NOLINT(build/include_directory)
0011
0012 namespace v8 {
0013
0014 class Context;
0015
0016 #ifndef V8_PROMISE_INTERNAL_FIELD_COUNT
0017 // Defined using gn arg `v8_promise_internal_field_count`.
0018 #define V8_PROMISE_INTERNAL_FIELD_COUNT 0
0019 #endif
0020
0021 /**
0022  * An instance of the built-in Promise constructor.
0023  */
0024 class V8_EXPORT Promise : public Object {
0025  public:
0026   /**
0027    * State of the promise. Each value corresponds to one of the possible values
0028    * of the [[PromiseState]] field.
0029    */
0030   enum PromiseState { kPending, kFulfilled, kRejected };
0031
0032   class V8_EXPORT Resolver : public Object {
0033    public:
0034     /**
0035      * Create a new resolver, along with an associated promise in pending state.
0036      */
0037     static V8_WARN_UNUSED_RESULT MaybeLocal<Resolver> New(
0038         Local<Context> context);
0039
0040     /**
0041      * Extract the associated promise.
0042      */
0043     Local<Promise> GetPromise();
0044
0045     /**
0046      * Resolve/reject the associated promise with a given value.
0047      * Ignored if the promise is no longer pending.
0048      */
0049     V8_WARN_UNUSED_RESULT Maybe<bool> Resolve(Local<Context> context,
0050                                               Local<Value> value);
0051
0052     V8_WARN_UNUSED_RESULT Maybe<bool> Reject(Local<Context> context,
0053                                              Local<Value> value);
0054
0055     V8_INLINE static Resolver* Cast(Value* value) {
0056 #ifdef V8_ENABLE_CHECKS
0057       CheckCast(value);
0058 #endif
0059       return static_cast<Promise::Resolver*>(value);
0060     }
0061
0062    private:
0063     Resolver();
0064     static void CheckCast(Value* obj);
0065   };
0066
0067   /**
0068    * Register a resolution/rejection handler with a promise. The handler is
0069    * given the respective resolution/rejection value as an argument. If the
0070    * promise is already resolved/rejected, the handler is invoked at the end of
0071    * turn.
0072    *
0073    * This performs the PerformPromiseThen abstract operation with a fresh native
0074    * promise as result, rather than the similar Promise.prototype.then
0075    * operation. In particular, it does not do species lookup on the Promise
0076    * constructor, and is therefore guaranteed to return a Promise.
0077    *
0078    * https://tc39.es/ecma262/#sec-performpromisethen
0079    *
0080    * This is consistent with Promise reactions in WebIDL:
0081    *
0082    * https://webidl.spec.whatwg.org/#dfn-perform-steps-once-promise-is-settled
0083    */
0084   V8_WARN_UNUSED_RESULT MaybeLocal<Promise> Catch(Local<Context> context,
0085                                                   Local<Function> handler);
0086
0087   V8_WARN_UNUSED_RESULT MaybeLocal<Promise> Then(Local<Context> context,
0088                                                  Local<Function> handler);
0089
0090   V8_WARN_UNUSED_RESULT MaybeLocal<Promise> Then(Local<Context> context,
0091                                                  Local<Function> on_fulfilled,
0092                                                  Local<Function> on_rejected);
0093
0094   /**
0095    * Returns true if the promise has at least one derived promise, and
0096    * therefore resolve/reject handlers (including default handler).
0097    */
0098   bool HasHandler() const;
0099
0100   /**
0101    * Returns the content of the [[PromiseResult]] field. The Promise must not
0102    * be pending.
0103    */
0104   Local<Value> Result();
0105
0106   /**
0107    * Returns the value of the [[PromiseState]] field.
0108    */
0109   PromiseState State();
0110
0111   /**
0112    * Marks this promise as handled to avoid reporting unhandled rejections.
0113    */
0114   void MarkAsHandled();
0115
0116   /**
0117    * Marks this promise as silent to prevent pausing the debugger when the
0118    * promise is rejected.
0119    */
0120   void MarkAsSilent();
0121
0122   V8_INLINE static Promise* Cast(Value* value) {
0123 #ifdef V8_ENABLE_CHECKS
0124     CheckCast(value);
0125 #endif
0126     return static_cast<Promise*>(value);
0127   }
0128
0129   static constexpr int kEmbedderFieldCount = V8_PROMISE_INTERNAL_FIELD_COUNT;
0130
0131  private:
0132   Promise();
0133   static void CheckCast(Value* obj);
0134 };
0135
0136 /**
0137  * PromiseHook with type kInit is called when a new promise is
0138  * created. When a new promise is created as part of the chain in the
0139  * case of Promise.then or in the intermediate promises created by
0140  * Promise.{race, all}/AsyncFunctionAwait, we pass the parent promise
0141  * otherwise we pass undefined.
0142  *
0143  * PromiseHook with type kResolve is called at the beginning of
0144  * resolve or reject function defined by CreateResolvingFunctions.
0145  *
0146  * PromiseHook with type kBefore is called at the beginning of the
0147  * PromiseReactionJob.
0148  *
0149  * PromiseHook with type kAfter is called right at the end of the
0150  * PromiseReactionJob.
0151  */
0152 enum class PromiseHookType { kInit, kResolve, kBefore, kAfter };
0153
0154 using PromiseHook = void (*)(PromiseHookType type, Local<Promise> promise,
0155                              Local<Value> parent);
0156
0157 // --- Promise Reject Callback ---
0158 enum PromiseRejectEvent {
0159   kPromiseRejectWithNoHandler = 0,
0160   kPromiseHandlerAddedAfterReject = 1,
0161   kPromiseRejectAfterResolved = 2,
0162   kPromiseResolveAfterResolved = 3,
0163 };
0164
0165 class PromiseRejectMessage {
0166  public:
0167   PromiseRejectMessage(Local<Promise> promise, PromiseRejectEvent event,
0168                        Local<Value> value)
0169       : promise_(promise), event_(event), value_(value) {}
0170
0171   V8_INLINE Local<Promise> GetPromise() const { return promise_; }
0172   V8_INLINE PromiseRejectEvent GetEvent() const { return event_; }
0173   V8_INLINE Local<Value> GetValue() const { return value_; }
0174
0175  private:
0176   Local<Promise> promise_;
0177   PromiseRejectEvent event_;
0178   Local<Value> value_;
0179 };
0180
0181 using PromiseRejectCallback = void (*)(PromiseRejectMessage message);
0182
0183 }  // namespace v8
0184
0185 #endif  // INCLUDE_V8_PROMISE_H_