summaryrefslogtreecommitdiff
path: root/dom/webidl/PromiseDebugging.webidl
blob: 107b8bc6571e4903cc1890c2dac837718f3e5fa4 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this file,
 * You can obtain one at http://mozilla.org/MPL/2.0/.
 */

/* This is a utility namespace for promise-debugging functionality */


dictionary PromiseDebuggingStateHolder {
  PromiseDebuggingState state = "pending";
  any value;
  any reason;
};
enum PromiseDebuggingState { "pending", "fulfilled", "rejected" };

/**
 * An observer for Promise that _may_ be leaking uncaught rejections.
 *
 * It is generally a programming error to leave a Promise rejected and
 * not consume its rejection. The information exposed by this
 * interface is designed to allow clients to track down such Promise,
 * i.e. Promise that are currently
 * - in `rejected` state;
 * - last of their chain.
 *
 * Note, however, that a promise in such a state at the end of a tick
 * may eventually be consumed in some ulterior tick. Implementers of
 * this interface are responsible for presenting the information
 * in a meaningful manner.
 */
callback interface UncaughtRejectionObserver {
  /**
   * A Promise has been left in `rejected` state and is the
   * last in its chain.
   *
   * @param p A currently uncaught Promise. If `p` is is eventually
   * caught, i.e. if its `then` callback is called, `onConsumed` will
   * be called.
   */
#ifdef SPIDERMONKEY_PROMISE
  void onLeftUncaught(object p);
#else
  void onLeftUncaught(Promise<any> p);
#endif SPIDERMONKEY_PROMISE

  /**
   * A Promise previously left uncaught is not the last in its
   * chain anymore.
   *
   * @param p A Promise that was previously left in uncaught state is
   * now caught, i.e. it is not the last in its chain anymore.
   */
#ifdef SPIDERMONKEY_PROMISE
  void onConsumed(object p);
#else
  void onConsumed(Promise<any> p);
#endif SPIDERMONKEY_PROMISE
};

[ChromeOnly, Exposed=(Window,System)]
interface PromiseDebugging {
  /**
   * The various functions on this interface all expect to take promises but
   * don't want the WebIDL behavior of assimilating random passed-in objects
   * into promises.  They also want to treat Promise subclass instances as
   * promises instead of wrapping them in a vanilla Promise, which is what the
   * IDL spec says to do.  So we list all our arguments as "object" instead of
   * "Promise" and check for them being a Promise internally.
   */

  /**
   * Get the current state of the given promise.
   */
  [Throws]
  static PromiseDebuggingStateHolder getState(object p);

  /**
   * Return an identifier for a promise. This identifier is guaranteed
   * to be unique to the current process.
   */
  [Throws]
  static DOMString getPromiseID(object p);

  /**
   * Return the stack to the promise's allocation point.  This can
   * return null if the promise was not created from script.
   */
  [Throws]
  static object? getAllocationStack(object p);

  /**
   * Return the stack to the promise's rejection point, if the
   * rejection happened from script.  This can return null if the
   * promise has not been rejected or was not rejected from script.
   */
  [Throws]
  static object? getRejectionStack(object p);

  /**
   * Return the stack to the promise's fulfillment point, if the
   * fulfillment happened from script.  This can return null if the
   * promise has not been fulfilled or was not fulfilled from script.
   */
  [Throws]
  static object? getFullfillmentStack(object p);

#ifndef SPIDERMONKEY_PROMISE
  /**
   * Get the promises directly depending on a given promise.  These are:
   *
   * 1) Return values of then() calls on the promise
   * 2) Return values of Promise.all() if the given promise was passed in as one
   *    of the arguments.
   * 3) Return values of Promise.race() if the given promise was passed in as
   *    one of the arguments.
   *
   * Once a promise is settled, it will generally notify its dependent promises
   * and forget about them, so this is most useful on unsettled promises.
   *
   * Note that this function only returns the promises that directly depend on
   * p.  It does not recursively return promises that depend on promises that
   * depend on p.
   */
  [Throws]
  static sequence<Promise<any>> getDependentPromises(object p);

  /**
   * Get the number of milliseconds elapsed since the given promise was created.
   */
  [Throws]
  static DOMHighResTimeStamp getPromiseLifetime(object p);

  /*
   * Get the number of milliseconds elapsed between the promise being created
   * and being settled.  Throws NS_ERROR_UNEXPECTED if the promise has not
   * settled.
   */
  [Throws]
  static DOMHighResTimeStamp getTimeToSettle(object p);

#endif // SPIDERMONKEY_PROMISE

  /**
   * Watching uncaught rejections on the current thread.
   *
   * Adding an observer twice will cause it to be notified twice
   * of events.
   */
  static void addUncaughtRejectionObserver(UncaughtRejectionObserver o);
  static boolean removeUncaughtRejectionObserver(UncaughtRejectionObserver o);
};