зеркало из https://github.com/mozilla/gecko-dev.git
Bug 1328820 - Add documentation comment to Promise.h, AsyncFunction.h, and AsyncIteration.h r=anba DONTBUILD comment-only
This commit is contained in:
Tooru Fujisawa
Родитель
544b61c613
Коммит
1e093ed64e
|
|
@ -15,18 +15,53 @@
|
|||
namespace js {
|
||||
|
||||
enum PromiseSlots {
|
||||
// Int32 value with PROMISE_FLAG_* flags below.
|
||||
PromiseSlot_Flags = 0,
|
||||
|
||||
// * if this promise is pending, reaction objects
|
||||
// * undefined if there's no reaction
|
||||
// * maybe-wrapped PromiseReactionRecord if there's only one reacion
|
||||
// * dense array if there are two or more more reactions
|
||||
// * if this promise is fulfilled, the resolution value
|
||||
// * if this promise is rejected, the reason for the rejection
|
||||
PromiseSlot_ReactionsOrResult,
|
||||
|
||||
// * if this promise is pending, resolve/reject functions.
|
||||
// This slot holds only the reject function. The resolve function is
|
||||
// reachable from the reject function's extended slot.
|
||||
// * if this promise is either fulfilled or rejected, undefined
|
||||
// * (special case) if this promise is the return value of an async function
|
||||
// invocation, the generator object for the function's internal generator
|
||||
PromiseSlot_RejectFunction,
|
||||
PromiseSlot_AwaitGenerator = PromiseSlot_RejectFunction,
|
||||
|
||||
// Promise object's debug info, which is created on demand.
|
||||
// * if this promise has no debug info, undefined
|
||||
// * if this promise contains only its process-unique ID, the ID's number
|
||||
// value
|
||||
// * otherwise a PromiseDebugInfo object
|
||||
PromiseSlot_DebugInfo,
|
||||
|
||||
PromiseSlots,
|
||||
};
|
||||
|
||||
// This promise is either fulfilled or rejected.
|
||||
// If this flag is not set, this promise is pending.
|
||||
#define PROMISE_FLAG_RESOLVED 0x1
|
||||
|
||||
// If this flag and PROMISE_FLAG_RESOLVED are set, this promise is fulfilled.
|
||||
// If only PROMISE_FLAG_RESOLVED is set, this promise is rejected.
|
||||
#define PROMISE_FLAG_FULFILLED 0x2
|
||||
|
||||
// Indicates the promise has ever had a fulfillment or rejection handler;
|
||||
// used in unhandled rejection tracking.
|
||||
#define PROMISE_FLAG_HANDLED 0x4
|
||||
|
||||
// This promise uses the default resolving functions.
|
||||
// The PromiseSlot_RejectFunction slot is not used.
|
||||
#define PROMISE_FLAG_DEFAULT_RESOLVING_FUNCTIONS 0x08
|
||||
|
||||
// This promise is the return value of an async function invocation.
|
||||
#define PROMISE_FLAG_ASYNC 0x10
|
||||
|
||||
class AutoSetNewObjectMetadata;
|
||||
|
|
@ -92,7 +127,10 @@ class PromiseObject : public NativeObject
|
|||
return resolutionTime() - allocationTime();
|
||||
}
|
||||
MOZ_MUST_USE bool dependentPromises(JSContext* cx, MutableHandle<GCVector<Value>> values);
|
||||
|
||||
// Return the process-unique ID of this promise. Only used by the debugger.
|
||||
uint64_t getID();
|
||||
|
||||
bool isUnhandled() {
|
||||
MOZ_ASSERT(state() == JS::PromiseState::Rejected);
|
||||
return !(flags() & PROMISE_FLAG_HANDLED);
|
||||
|
|
@ -113,9 +151,18 @@ class PromiseObject : public NativeObject
|
|||
MOZ_MUST_USE JSObject*
|
||||
GetWaitForAllPromise(JSContext* cx, const JS::AutoObjectVector& promises);
|
||||
|
||||
// Whether to create a promise as the return value of Promise#{then,catch}.
|
||||
// If the return value is known to be unused, and if the operation is known
|
||||
// to be unobservable, we can skip creating the promise.
|
||||
enum class CreateDependentPromise {
|
||||
// The return value is not known to be unused.
|
||||
Always,
|
||||
|
||||
// The return value is known to be unused.
|
||||
SkipIfCtorUnobservable,
|
||||
|
||||
// The return value is known to be unused, and the operation is known
|
||||
// to be unobservable.
|
||||
Never
|
||||
};
|
||||
|
||||
|
|
@ -144,9 +191,17 @@ MOZ_MUST_USE JSObject*
|
|||
PromiseResolve(JSContext* cx, HandleObject constructor, HandleValue value);
|
||||
|
||||
|
||||
/**
|
||||
* Create the promise object which will be used as the return value of an async
|
||||
* function.
|
||||
*/
|
||||
MOZ_MUST_USE PromiseObject*
|
||||
CreatePromiseObjectForAsync(JSContext* cx, HandleValue generatorVal);
|
||||
|
||||
/**
|
||||
* Returns true if the given object is a promise created by
|
||||
* CreatePromiseObjectForAsync function.
|
||||
*/
|
||||
MOZ_MUST_USE bool
|
||||
IsPromiseForAsync(JSObject* promise);
|
||||
|
||||
|
|
|
|||
|
|
@ -12,21 +12,44 @@
|
|||
|
||||
namespace js {
|
||||
|
||||
// An async function is implemented using two function objects, which are
|
||||
// referred to as the "unwrapped" and the "wrapped" async function object.
|
||||
// The unwrapped function is a generator function compiled from the async
|
||||
// function's script. |await| expressions within the async function are
|
||||
// compiled like |yield| expression for the generator function with dedicated
|
||||
// opcode,. The unwrapped function is never exposed to user script.
|
||||
// The wrapped function is a native function which wraps the generator function,
|
||||
// hence its name, and is the publicly exposed object of the async function.
|
||||
//
|
||||
// The unwrapped async function is created while compiling the async function,
|
||||
// and the wrapped async function is created while executing the async function
|
||||
// declaration or expression.
|
||||
|
||||
// Returns a wrapped async function from an unwrapped async function.
|
||||
JSFunction*
|
||||
GetWrappedAsyncFunction(JSFunction* unwrapped);
|
||||
|
||||
// Returns an unwrapped async function from a wrapped async function.
|
||||
JSFunction*
|
||||
GetUnwrappedAsyncFunction(JSFunction* wrapped);
|
||||
|
||||
// Returns true if the given function is a wrapped async function.
|
||||
bool
|
||||
IsWrappedAsyncFunction(JSFunction* fun);
|
||||
|
||||
// Create a wrapped async function from unwrapped async function with given
|
||||
// prototype object.
|
||||
JSObject*
|
||||
WrapAsyncFunctionWithProto(JSContext* cx, HandleFunction unwrapped, HandleObject proto);
|
||||
|
||||
// Create a wrapped async function from unwrapped async function with default
|
||||
// prototype object.
|
||||
JSObject*
|
||||
WrapAsyncFunction(JSContext* cx, HandleFunction unwrapped);
|
||||
|
||||
// Resume the async function when the `await` operand resolves.
|
||||
// Split into two functions depending on whether the awaited value was
|
||||
// fulfilled or rejected.
|
||||
MOZ_MUST_USE bool
|
||||
AsyncFunctionAwaitedFulfilled(JSContext* cx, Handle<PromiseObject*> resultPromise,
|
||||
HandleValue generatorVal, HandleValue value);
|
||||
|
|
|
|||
|
|
@ -14,33 +14,55 @@
|
|||
|
||||
namespace js {
|
||||
|
||||
// Async generator consists of 2 functions, |wrapped| and |unwrapped|.
|
||||
// |unwrapped| is a generator function compiled from async generator script,
|
||||
// |await| behaves just like |yield| there. |unwrapped| isn't exposed to user
|
||||
// script.
|
||||
// |wrapped| is a native function that is the value of async generator.
|
||||
// An async generator is implemented using two function objects, which are
|
||||
// referred to as the "unwrapped" and the "wrapped" async generator object.
|
||||
// The unwrapped function is a generator function compiled from the async
|
||||
// generator's script. |await| expressions within the async generator are
|
||||
// compiled like |yield| expression for the generator function with dedicated
|
||||
// opcode. The unwrapped function is never exposed to user script.
|
||||
// The wrapped function is a native function which wraps the generator function,
|
||||
// hence its name, and is the publicly exposed object of the async generator.
|
||||
//
|
||||
// The unwrapped async generator is created while compiling the async generator,
|
||||
// and the wrapped async generator is created while executing the async
|
||||
// generator declaration or expression.
|
||||
|
||||
// Create a wrapped async generator from an unwrapped async generator with given
|
||||
// prototype object.
|
||||
JSObject*
|
||||
WrapAsyncGeneratorWithProto(JSContext* cx, HandleFunction unwrapped, HandleObject proto);
|
||||
|
||||
// Create a wrapped async generator from an unwrapped async generator
|
||||
// with default prototype object.
|
||||
JSObject*
|
||||
WrapAsyncGenerator(JSContext* cx, HandleFunction unwrapped);
|
||||
|
||||
// Returns true if the given function is a wrapped async generator.
|
||||
bool
|
||||
IsWrappedAsyncGenerator(JSFunction* fun);
|
||||
|
||||
// Returns a wrapped async generator from an unwrapped async generator.
|
||||
JSFunction*
|
||||
GetWrappedAsyncGenerator(JSFunction* unwrapped);
|
||||
|
||||
// Return an unwrapped async generator from a wrapped async generator.
|
||||
JSFunction*
|
||||
GetUnwrappedAsyncGenerator(JSFunction* wrapped);
|
||||
|
||||
// Resume the async generator when the `await` operand fulfills to `value`.
|
||||
MOZ_MUST_USE bool
|
||||
AsyncGeneratorAwaitedFulfilled(JSContext* cx, Handle<AsyncGeneratorObject*> asyncGenObj,
|
||||
HandleValue value);
|
||||
|
||||
// Resume the async generator when the `await` operand rejects with `reason`.
|
||||
MOZ_MUST_USE bool
|
||||
AsyncGeneratorAwaitedRejected(JSContext* cx, Handle<AsyncGeneratorObject*> asyncGenObj,
|
||||
HandleValue reason);
|
||||
|
||||
// Resume the async generator after awaiting on the value passed to
|
||||
// AsyncGenerator#return, when the async generator was still executing.
|
||||
// Split into two functions depending on whether the awaited value was
|
||||
// fulfilled or rejected.
|
||||
MOZ_MUST_USE bool
|
||||
AsyncGeneratorYieldReturnAwaitedFulfilled(JSContext* cx,
|
||||
Handle<AsyncGeneratorObject*> asyncGenObj,
|
||||
|
|
@ -52,13 +74,27 @@ AsyncGeneratorYieldReturnAwaitedRejected(JSContext* cx,
|
|||
|
||||
class AsyncGeneratorObject;
|
||||
|
||||
// AsyncGeneratorRequest record in the spec.
|
||||
// Stores the info from AsyncGenerator#{next,return,throw}.
|
||||
//
|
||||
// This object is reused across multiple requests as an optimization, and
|
||||
// stored in the Slot_CachedRequest slot.
|
||||
class AsyncGeneratorRequest : public NativeObject
|
||||
{
|
||||
private:
|
||||
enum AsyncGeneratorRequestSlots {
|
||||
// Int32 value with CompletionKind.
|
||||
// Normal: next
|
||||
// Return: return
|
||||
// Throw: throw
|
||||
Slot_CompletionKind = 0,
|
||||
|
||||
// The value passed to AsyncGenerator#{next,return,throw}.
|
||||
Slot_CompletionValue,
|
||||
|
||||
// The promise returned by AsyncGenerator#{next,return,throw}.
|
||||
Slot_Promise,
|
||||
|
||||
Slots,
|
||||
};
|
||||
|
||||
|
|
@ -68,6 +104,7 @@ class AsyncGeneratorRequest : public NativeObject
|
|||
setFixedSlot(Slot_Promise, ObjectValue(*promise));
|
||||
}
|
||||
|
||||
// Clear the request data for reuse.
|
||||
void clearData() {
|
||||
setFixedSlot(Slot_CompletionValue, NullValue());
|
||||
setFixedSlot(Slot_Promise, NullValue());
|
||||
|
|
@ -97,23 +134,50 @@ class AsyncGeneratorObject : public NativeObject
|
|||
{
|
||||
private:
|
||||
enum AsyncGeneratorObjectSlots {
|
||||
// Int32 value containing one of the |State| fields from below.
|
||||
Slot_State = 0,
|
||||
|
||||
// Generator object for the unwrapped async generator.
|
||||
Slot_Generator,
|
||||
|
||||
// * null value if this async generator has no requests
|
||||
// * AsyncGeneratorRequest if this async generator has only one request
|
||||
// * list object if this async generator has 2 or more requests
|
||||
Slot_QueueOrRequest,
|
||||
|
||||
// Cached AsyncGeneratorRequest for later use.
|
||||
// undefined if there's no cache.
|
||||
Slot_CachedRequest,
|
||||
|
||||
Slots
|
||||
};
|
||||
|
||||
enum State {
|
||||
// "suspendedStart" in the spec.
|
||||
// Suspended after invocation.
|
||||
State_SuspendedStart,
|
||||
|
||||
// "suspendedYield" in the spec
|
||||
// Suspended with `yield` expression.
|
||||
State_SuspendedYield,
|
||||
|
||||
// "executing" in the spec.
|
||||
// Resumed from initial suspend or yield, and either running the script
|
||||
// or awaiting for `await` expression.
|
||||
State_Executing,
|
||||
// State_AwaitingYieldReturn corresponds to the case that
|
||||
// AsyncGenerator#return is called while State_Executing,
|
||||
// just like the case that AsyncGenerator#return is called
|
||||
// while State_Completed.
|
||||
|
||||
// Part of "executing" in the spec.
|
||||
// Awaiting on the value passed by AsyncGenerator#return which is called
|
||||
// while executing.
|
||||
State_AwaitingYieldReturn,
|
||||
|
||||
// Part of "executing" in the spec.
|
||||
// Awaiting on the value passed by AsyncGenerator#return which is called
|
||||
// after completed.
|
||||
State_AwaitingReturn,
|
||||
|
||||
// "completed" in the spec.
|
||||
// The generator is completed.
|
||||
State_Completed
|
||||
};
|
||||
|
||||
|
|
@ -129,8 +193,8 @@ class AsyncGeneratorObject : public NativeObject
|
|||
}
|
||||
|
||||
// Queue is implemented in 2 ways. If only one request is queued ever,
|
||||
// request is stored directly to the slot. Once 2 requests are queued, an
|
||||
// array is created and requests are pushed into it, and the array is
|
||||
// request is stored directly to the slot. Once 2 requests are queued, a
|
||||
// list is created and requests are appended into it, and the list is
|
||||
// stored to the slot.
|
||||
|
||||
bool isSingleQueue() const {
|
||||
|
|
@ -267,8 +331,12 @@ class AsyncFromSyncIteratorObject : public NativeObject
|
|||
{
|
||||
private:
|
||||
enum AsyncFromSyncIteratorObjectSlots {
|
||||
// Object that implements the sync iterator protocol.
|
||||
Slot_Iterator = 0,
|
||||
|
||||
// The `next` property of the iterator object.
|
||||
Slot_NextMethod = 1,
|
||||
|
||||
Slots
|
||||
};
|
||||
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче