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 // The number of required internal fields can be defined by embedder.
0018 #define V8_PROMISE_INTERNAL_FIELD_COUNT 0
0019 #endif
0020
0021 /**
0022  * An instance of the built-in Promise constructor (ES6 draft).
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.
0069    * The handler is given the respective resolution/rejection value as
0070    * an argument. If the promise is already resolved/rejected, the handler is
0071    * invoked at the end of turn.
0072    */
0073   V8_WARN_UNUSED_RESULT MaybeLocal<Promise> Catch(Local<Context> context,
0074                                                   Local<Function> handler);
0075
0076   V8_WARN_UNUSED_RESULT MaybeLocal<Promise> Then(Local<Context> context,
0077                                                  Local<Function> handler);
0078
0079   V8_WARN_UNUSED_RESULT MaybeLocal<Promise> Then(Local<Context> context,
0080                                                  Local<Function> on_fulfilled,
0081                                                  Local<Function> on_rejected);
0082
0083   /**
0084    * Returns true if the promise has at least one derived promise, and
0085    * therefore resolve/reject handlers (including default handler).
0086    */
0087   bool HasHandler() const;
0088
0089   /**
0090    * Returns the content of the [[PromiseResult]] field. The Promise must not
0091    * be pending.
0092    */
0093   Local<Value> Result();
0094
0095   /**
0096    * Returns the value of the [[PromiseState]] field.
0097    */
0098   PromiseState State();
0099
0100   /**
0101    * Marks this promise as handled to avoid reporting unhandled rejections.
0102    */
0103   void MarkAsHandled();
0104
0105   /**
0106    * Marks this promise as silent to prevent pausing the debugger when the
0107    * promise is rejected.
0108    */
0109   void MarkAsSilent();
0110
0111   V8_INLINE static Promise* Cast(Value* value) {
0112 #ifdef V8_ENABLE_CHECKS
0113     CheckCast(value);
0114 #endif
0115     return static_cast<Promise*>(value);
0116   }
0117
0118   static const int kEmbedderFieldCount = V8_PROMISE_INTERNAL_FIELD_COUNT;
0119
0120  private:
0121   Promise();
0122   static void CheckCast(Value* obj);
0123 };
0124
0125 /**
0126  * PromiseHook with type kInit is called when a new promise is
0127  * created. When a new promise is created as part of the chain in the
0128  * case of Promise.then or in the intermediate promises created by
0129  * Promise.{race, all}/AsyncFunctionAwait, we pass the parent promise
0130  * otherwise we pass undefined.
0131  *
0132  * PromiseHook with type kResolve is called at the beginning of
0133  * resolve or reject function defined by CreateResolvingFunctions.
0134  *
0135  * PromiseHook with type kBefore is called at the beginning of the
0136  * PromiseReactionJob.
0137  *
0138  * PromiseHook with type kAfter is called right at the end of the
0139  * PromiseReactionJob.
0140  */
0141 enum class PromiseHookType { kInit, kResolve, kBefore, kAfter };
0142
0143 using PromiseHook = void (*)(PromiseHookType type, Local<Promise> promise,
0144                              Local<Value> parent);
0145
0146 // --- Promise Reject Callback ---
0147 enum PromiseRejectEvent {
0148   kPromiseRejectWithNoHandler = 0,
0149   kPromiseHandlerAddedAfterReject = 1,
0150   kPromiseRejectAfterResolved = 2,
0151   kPromiseResolveAfterResolved = 3,
0152 };
0153
0154 class PromiseRejectMessage {
0155  public:
0156   PromiseRejectMessage(Local<Promise> promise, PromiseRejectEvent event,
0157                        Local<Value> value)
0158       : promise_(promise), event_(event), value_(value) {}
0159
0160   V8_INLINE Local<Promise> GetPromise() const { return promise_; }
0161   V8_INLINE PromiseRejectEvent GetEvent() const { return event_; }
0162   V8_INLINE Local<Value> GetValue() const { return value_; }
0163
0164  private:
0165   Local<Promise> promise_;
0166   PromiseRejectEvent event_;
0167   Local<Value> value_;
0168 };
0169
0170 using PromiseRejectCallback = void (*)(PromiseRejectMessage message);
0171
0172 }  // namespace v8
0173
0174 #endif  // INCLUDE_V8_PROMISE_H_