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
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*-
* vim: set ts=8 sts=2 et sw=2 tw=80:
* 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/. */
#ifndef vm_OffThreadPromiseRuntimeState_h
#define vm_OffThreadPromiseRuntimeState_h
#include <stddef.h> // size_t
#include "jstypes.h" // JS_PUBLIC_API
#include "ds/Fifo.h" // js::Fifo
#include "js/AllocPolicy.h" // js::SystemAllocPolicy
#include "js/HashTable.h" // js::DefaultHasher, js::HashSet
#include "js/Promise.h" // JS::Dispatchable, JS::Dispatchable::MaybeShuttingDown, JS::DispatchToEventLoopCallback
#include "js/RootingAPI.h" // JS::Handle, JS::PersistentRooted
#include "threading/ConditionVariable.h" // js::ConditionVariable
#include "vm/PromiseObject.h" // js::PromiseObject
struct JS_PUBLIC_API JSContext;
struct JS_PUBLIC_API JSRuntime;
namespace js {
class OffThreadPromiseRuntimeState;
// [SMDOC] OffThreadPromiseTask: an off-main-thread task that resolves a promise
//
// An OffThreadPromiseTask is an abstract base class holding a JavaScript
// promise that will be resolved (fulfilled or rejected) with the results of a
// task possibly performed by some other thread.
//
// An OffThreadPromiseTask's lifecycle is as follows:
//
// - Some JavaScript native wishes to return a promise of the result of some
// computation that might be performed by other threads (say, helper threads
// or the embedding's I/O threads), so it creates a PromiseObject to represent
// the result, and an OffThreadPromiseTask referring to it. After handing the
// OffThreadPromiseTask to the code doing the actual work, the native is free
// to return the PromiseObject to its caller.
//
// - When the computation is done, successfully or otherwise, it populates the
// OffThreadPromiseTask—which is actually an instance of some concrete
// subclass specific to the task—with the information needed to resolve the
// promise, and calls OffThreadPromiseTask::dispatchResolveAndDestroy. This
// enqueues a runnable on the JavaScript thread to which the promise belongs.
//
// - When it gets around to the runnable, the JavaScript thread calls the
// OffThreadPromiseTask's `resolve` method, which the concrete subclass has
// overriden to resolve the promise appropriately. This probably enqueues a
// promise reaction job.
//
// - The JavaScript thread then deletes the OffThreadPromiseTask.
//
// During shutdown, the process is slightly different. Enqueuing runnables to
// the JavaScript thread begins to fail. JSRuntime shutdown waits for all
// outstanding tasks to call dispatchResolveAndDestroy, and then deletes them on
// the main thread, without calling `resolve`.
//
// For example, the JavaScript function WebAssembly.compile uses
// OffThreadPromiseTask to manage the result of a helper thread task, accepting
// binary WebAssembly code and returning a promise of a compiled
// WebAssembly.Module. It would like to do this compilation work on a helper
// thread. When called by JavaScript, WebAssembly.compile creates a promise,
// builds a CompileBufferTask (the OffThreadPromiseTask concrete subclass) to
// keep track of it, and then hands that to a helper thread. When the helper
// thread is done, successfully or otherwise, it calls the CompileBufferTask's
// dispatchResolveAndDestroy method, which enqueues a runnable to the JavaScript
// thread to resolve the promise and delete the CompileBufferTask.
// (CompileBufferTask actually implements PromiseHelperTask, which implements
// OffThreadPromiseTask; PromiseHelperTask is what our helper thread scheduler
// requires.)
//
// OffThreadPromiseTasks are not limited to use with helper threads. For
// example, a function returning a promise of the result of a network operation
// could provide the code collecting the incoming data with an
// OffThreadPromiseTask for the promise, and let the embedding's network I/O
// threads call dispatchResolveAndDestroy.
//
// OffThreadPromiseTask may also be used purely on the main thread, as a way to
// "queue a task" in HTML terms. Note that a "task" is not the same as a
// "microtask" and there are separate queues for tasks and microtasks that are
// drained at separate times in the browser. The task queue is implemented by
// the browser's main event loop. The microtask queue is implemented
// by JS::JobQueue, used for promises and gets drained before returning to
// the event loop. Thus OffThreadPromiseTask can only be used when the spec
// says "queue a task", as the WebAssembly APIs do.
//
// An OffThreadPromiseTask has a JSContext, and must be constructed and have its
// 'init' method called on that JSContext's thread. Once initialized, its
// dispatchResolveAndDestroy method may be called from any thread. This is the
// only safe way to destruct an OffThreadPromiseTask; doing so ensures the
// OffThreadPromiseTask's destructor will run on the JSContext's thread, either
// from the event loop or during shutdown.
//
// OffThreadPromiseTask::dispatchResolveAndDestroy uses the
// JS::DispatchToEventLoopCallback provided by the embedding to enqueue
// runnables on the JavaScript thread. See the comments for
// DispatchToEventLoopCallback for details.
class OffThreadPromiseTask : public JS::Dispatchable {
friend class OffThreadPromiseRuntimeState;
JSRuntime* runtime_;
JS::PersistentRooted<PromiseObject*> promise_;
bool registered_;
void operator=(const OffThreadPromiseTask&) = delete;
OffThreadPromiseTask(const OffThreadPromiseTask&) = delete;
void unregister(OffThreadPromiseRuntimeState& state);
protected:
OffThreadPromiseTask(JSContext* cx, JS::Handle<PromiseObject*> promise);
// To be called by OffThreadPromiseTask and implemented by the derived class.
virtual bool resolve(JSContext* cx, JS::Handle<PromiseObject*> promise) = 0;
// JS::Dispatchable implementation. Ends with 'delete this'.
void run(JSContext* cx, MaybeShuttingDown maybeShuttingDown) final;
public:
~OffThreadPromiseTask() override;
// Initializing an OffThreadPromiseTask informs the runtime that it must
// wait on shutdown for this task to rejoin the active JSContext by calling
// dispatchResolveAndDestroy().
bool init(JSContext* cx);
// An initialized OffThreadPromiseTask can be dispatched to an active
// JSContext of its Promise's JSRuntime from any thread. Normally, this will
// lead to resolve() being called on JSContext thread, given the Promise.
// However, if shutdown interrupts, resolve() may not be called, though the
// OffThreadPromiseTask will be destroyed on a JSContext thread.
void dispatchResolveAndDestroy();
void dispatchResolveAndDestroy(const AutoLockHelperThreadState& lock);
};
using OffThreadPromiseTaskSet =
HashSet<OffThreadPromiseTask*, DefaultHasher<OffThreadPromiseTask*>,
SystemAllocPolicy>;
using DispatchableFifo = Fifo<JS::Dispatchable*, 0, SystemAllocPolicy>;
class OffThreadPromiseRuntimeState {
friend class OffThreadPromiseTask;
// These fields are initialized once before any off-thread usage and thus do
// not require a lock.
JS::DispatchToEventLoopCallback dispatchToEventLoopCallback_;
void* dispatchToEventLoopClosure_;
// A set of all OffThreadPromiseTasks that have successfully called 'init'.
// OffThreadPromiseTask's destructor removes them from the set.
HelperThreadLockData<OffThreadPromiseTaskSet> live_;
// The allCanceled_ condition is waited on and notified during engine
// shutdown, communicating when all off-thread tasks in live_ are safe to be
// destroyed from the (shutting down) main thread. This condition is met when
// live_.count() == numCanceled_ where "canceled" means "the
// DispatchToEventLoopCallback failed after this task finished execution".
HelperThreadLockData<ConditionVariable> allCanceled_;
HelperThreadLockData<size_t> numCanceled_;
// The queue of JS::Dispatchables used by the DispatchToEventLoopCallback that
// calling js::UseInternalJobQueues installs.
HelperThreadLockData<DispatchableFifo> internalDispatchQueue_;
HelperThreadLockData<ConditionVariable> internalDispatchQueueAppended_;
HelperThreadLockData<bool> internalDispatchQueueClosed_;
OffThreadPromiseTaskSet& live() { return live_.ref(); }
ConditionVariable& allCanceled() { return allCanceled_.ref(); }
DispatchableFifo& internalDispatchQueue() {
return internalDispatchQueue_.ref();
}
ConditionVariable& internalDispatchQueueAppended() {
return internalDispatchQueueAppended_.ref();
}
static bool internalDispatchToEventLoop(void*, JS::Dispatchable*);
bool usingInternalDispatchQueue() const;
void operator=(const OffThreadPromiseRuntimeState&) = delete;
OffThreadPromiseRuntimeState(const OffThreadPromiseRuntimeState&) = delete;
public:
OffThreadPromiseRuntimeState();
~OffThreadPromiseRuntimeState();
void init(JS::DispatchToEventLoopCallback callback, void* closure);
void initInternalDispatchQueue();
bool initialized() const;
// If initInternalDispatchQueue() was called, internalDrain() can be
// called to periodically drain the dispatch queue before shutdown.
void internalDrain(JSContext* cx);
bool internalHasPending();
// shutdown() must be called by the JSRuntime while the JSRuntime is valid.
void shutdown(JSContext* cx);
};
} // namespace js
#endif // vm_OffThreadPromiseRuntimeState_h
|
