Skip to content

Commit ee1b655

Browse files
bfgeekbfgeek
committed
[worklets] Refactored out setting up environment settings object to
match workers spec. Removed Base64 helpers.
1 parent 1c36aa1 commit ee1b655

File tree

1 file changed

+118
-61
lines changed

1 file changed

+118
-61
lines changed

‎worklets/Overview.bs

+118-61
Original file line numberDiff line numberDiff line change
@@ -30,17 +30,23 @@ urlPrefix: https://html.spec.whatwg.org/multipage/workers.html; type: dfn;
3030
urlPrefix: https://html.spec.whatwg.org/multipage/webappapis.html; type: dfn;
3131
text: api base url
3232
text: api url character encoding
33+
text: browsing context
3334
text: code entry-point
3435
text: create a script
36+
text: creation url
3537
text: document environment
3638
text: environment settings object
3739
text: event loop
3840
text: global object
41+
text: https state
3942
text: incumbent settings object
43+
text: microtask queue
44+
text: realm execution context
4045
text: responsible browsing context
4146
text: responsible document
4247
text: responsible event loop
4348
text: script execution environment
49+
text: task queues
4450
urlPrefix: https://html.spec.whatwg.org/multipage/infrastructure.html; type: dfn;
4551
text: in parallel
4652
text: javascript global environment
@@ -54,6 +60,7 @@ urlPrefix: https://www.w3.org/2001/tag/doc/promises-guide; type: dfn;
5460
urlPrefix: http://www.ecma-international.org/ecma-262/6.0/#sec-; type: dfn;
5561
text: Construct
5662
text: FunctionCreate
63+
text: InitializeHostDefinedRealm
5764
text: Invoke
5865
text: NewObjectEnvironment
5966
text: strict mode code
@@ -68,44 +75,55 @@ Motivations {#motivations}
6875

6976
<em>This section is not normative.</em>
7077

71-
Allowing extension points defined in the <a>document environment</a>
72-
is difficult, as rendering engines would need to abandon previously held assumptions for what could happen in the middle of a phase.
78+
Allowing extension points defined in the <a>document environment</a> is difficult, as rendering
79+
engines would need to abandon previously held assumptions for what could happen in the middle of a
80+
phase.
7381

7482
For example, during the layout phase the rendering engine assumes that no DOM will be modified.
7583

76-
Additionally defining extension points in the <a>document environment</a>
77-
would restrict rendering engines to performing work in the same thread as the <a>document environment</a>.
78-
(Unless rendering engines added complex, high-overhead infrastructure to allow thread-safe APIs in addition to thread joining guarantees).
84+
Additionally defining extension points in the <a>document environment</a> would restrict rendering
85+
engines to performing work in the same thread as the <a>document environment</a>. (Unless rendering
86+
engines added complex, high-overhead infrastructure to allow thread-safe APIs in addition to thread
87+
joining guarantees).
7988

80-
The worklet is designed to allow such extension points in rendering engines, while keeping guarantees which rendering engines rely currently on.
89+
The worklet is designed to allow such extension points in rendering engines, while keeping
90+
guarantees which rendering engines rely currently on.
8191

8292
Worklets are similar to <a>web workers</a> however they:
83-
- Are thread-agnostic. That is, they are not defined to run on a particular thread. Rendering engines may run them wherever they choose.
84-
- Are able to have multiple duplicate instances of the global scope created for the purpose of parallelism.
85-
- Are not event API based. Instead classes are registered on the global scope, whose methods are to be invoked by the user agent.
93+
- Are thread-agnostic. That is, they are not defined to run on a particular thread. Rendering
94+
engines may run them wherever they choose.
95+
- Are able to have multiple duplicate instances of the global scope created for the purpose of
96+
parallelism.
97+
- Are not event API based. Instead classes are registered on the global scope, whose methods are to
98+
be invoked by the user agent.
8699
- Have a reduced API surface on the <a>javascript global environment</a> (global scope).
87100
- Have a lifetime tied to running a method or set of methods on a class.
88101

89-
As worklets have a relatively high overhead, they should be used sparingly. Due to this worklets are expected to be shared between separate scripts.
90-
This is similar to the <a>document environment</a>.
102+
As worklets have a relatively high overhead, they should be used sparingly. Due to this worklets are
103+
expected to be shared between separate scripts. This is similar to the <a>document environment</a>.
91104

92105
Code Idempotency {#code-idempotency}
93106
------------------------------------
94107

95108
<em>This section is not normative.</em>
96109

97-
Multiple instances of {{WorkletGlobalScope}} can be created for each {{Worklet}} that they belong to.
98-
User agents may choose to do this in order to parallelize work over multiple threads, or to move work between threads as required.
110+
Multiple instances of {{WorkletGlobalScope}} can be created for each {{Worklet}} that they belong
111+
to. User agents may choose to do this in order to parallelize work over multiple threads, or to move
112+
work between threads as required.
99113

100-
Additionally different user agents may invoke a method on a class in a different order to other user agents.
114+
Additionally different user agents may invoke a method on a class in a different order to other user
115+
agents.
101116

102-
Due to this, in order to prevent this compatibility risk between user agents, authors who register classes on the global scope should make their code idempotent.
103-
That is, a method or set of methods on a class should produce the same output given a particular input.
117+
As a result of this, to prevent this compatibility risk between user agents, authors who register
118+
classes on the global scope should make their code idempotent. That is, a method or set of methods
119+
on a class should produce the same output given a particular input.
104120

105-
The following techniques should be used in order to encourage authors to write code in an idempotent way:
121+
The following techniques should be used in order to encourage authors to write code in an idempotent
122+
way:
106123
- No reference to the global object, e.g. <a>self</a> on a {{DedicatedWorkerGlobalScope}}.
107-
- Code is loaded similar to how ES6 Modules are loaded, in <a>strict mode code</a> inside an anonymous function.
108-
This prevents two different scripts sharing state by referencing shared objects on the global scope.
124+
- Code is loaded similar to how ES6 Modules are loaded, in <a>strict mode code</a> inside an
125+
anonymous function. This prevents two different scripts sharing state by referencing shared
126+
objects on the global scope.
109127
- User agents may choose to always have at least two {{WorkletGlobalScope}}s per {{Worklet}} and
110128
randomly assign a method or set of methods on a class to a particular global scope.
111129
- User agents may create and destroy {{WorkletGlobalScope}}s at any time.
@@ -116,63 +134,106 @@ Infrastructure {#infrastructure}
116134
The Global Scope {#the-global-scope}
117135
------------------------------------
118136

119-
The {{WorkletGlobalScope}} object provides a <dfn>worklet global scope</dfn> which represents the global execution context of a {{Worklet}}.
137+
The {{WorkletGlobalScope}} object provides a <dfn>worklet global scope</dfn> which represents the
138+
global execution context of a {{Worklet}}.
120139

121140
<pre class='idl'>
122141
interface WorkletGlobalScope {
142+
attribute Console console;
123143
};
124-
WorkletGlobalScope implements WindowBase64;
125144
</pre>
126145

127-
A {{WorkletGlobalScope}} has an associated <a>environment settings object</a> <b>settings object</b>.
146+
A {{WorkletGlobalScope}} has an associated <a>environment settings object</a>
147+
<b>settings object</b>.
128148

129149
Note:
130-
The {{WorkletGlobalScope}} has a limited global scope when compared to a {{DedicatedWorkerGlobalScope}}.
131-
It is expected that other specifications will extend {{WorkletGlobalScope}} with <code class='lang-javascript'>registerAClass</code> methods which
150+
The {{WorkletGlobalScope}} has a limited global scope when compared to a
151+
{{DedicatedWorkerGlobalScope}}. It is expected that other specifications will extend
152+
{{WorkletGlobalScope}} with <code class='lang-javascript'>registerAClass</code> methods which
132153
will allow authors to register classes for the user agent create and invoke methods on.
133154

134-
Issue(w3c/css-houdini-drafts#15): Add console API to {{WorkletGlobalScope}} when it exists.
155+
### The event loop ### {#the-event-loop}
135156

136-
### Initializing a WorkletGlobalScope ### {#initializing-a-workletglobalscope}
157+
Each {{WorkletGlobalScope}} object has a distinct <a>event loop</a>. This <a>event loop</a> has no
158+
associated <a>browsing context</a>, and only its <a>microtask queue</a> is used (all other <a>task
159+
queues</a> are not used). The <a>event loop</a> is created by the <a>create a
160+
WorkletGlobalScope</a> algorithm.
137161

138-
When a user agent is to <dfn>initialize a {{WorkletGlobalScope}}</dfn>, for a given |workletGlobalScope| and |worklet|, it <em>must</em> run the following steps:
139-
1. Let |workerEventLoop| be a new <a>event loop</a>.
162+
### Creating a WorkletGlobalScope ### {#creating-a-workletglobalscope}
140163

141-
Let |inheritedResponsibleBrowsingContext| be the <a>responsible browsing context</a> specified by the <a>incumbent settings object</a>.
164+
When a user agent is to <dfn>create a WorkletGlobalScope</dfn>, for a given |workletGlobalScopeType|
165+
and |worklet|, it <em>must</em> run the following steps:
142166

143-
Let |inheritedAPIBaseURL| be the <a>API base URL</a> specified by the <a>incumbent settings object</a>.
167+
1. Call the JavaScript <a>InitializeHostDefinedRealm</a> abstract operation with the following
168+
customizations:
144169

145-
Let |inheritedOrigin| be the <a>origin</a> specified by the <a>incumbent settings object</a>.
170+
- For the global object, create a new |workletGlobalScopeType| object. Let
171+
|workletGlobalScope| be the created object.
146172

147-
2. Let |settingsObject| be a new environment settings object whose algorithms are defined as follows:
148-
: The <a>script execution environments</a>:
149-
:: When the <a>environment settings object</a> is created, for each language supported by the user agent, create an appropriate execution environment as defined by the relevant specification.
150-
:: When a <a>script execution environment</a> is needed, return the appropriate one from those created when the <a>environment settings object</a> was created.
173+
- Let |realmExecutionContext| be the created JavaScript execution context.
151174

152-
: The <a>global object</a>:
175+
- Do not obtain any source texts for scripts or modules.
176+
177+
2. Let |settingsObject| be the result of <a>set up a worklet environment settings object</a>
178+
with |realmExecutionContext|.
179+
180+
2. Associate the |settingsObject| with |workletGlobalScope|.
181+
182+
3. For each |script| in the given |worklet|'s <b>worklet's loaded scripts</b> run the |script|
183+
in the |workletGlobalScope|.
184+
185+
### Script settings for worklets ### {#script-settings-for-worklets}
186+
187+
When a user agent is to <dfn>set up a worklet environment settings object</dfn>, given a
188+
|executionContext|, it must run the following steps:
189+
1. Let |inheritedResponsibleBrowsingContext| be the <a>responsible browsing context</a>
190+
specified by the <a>incumbent settings object</a>.
191+
192+
2. Let |inheritedOrigin| be the <a>origin</a> specified by the <a>incumbent settings object</a>.
193+
194+
3. Let |inheritedAPIBaseURL| be the <a>API base URL</a> specified by the <a>incumbent settings object</a>.
195+
196+
4. Let |workletEventLoop| be a newly created <a>event loop</a>.
197+
198+
5. Let |workletGlobalScope| be |executionContext|'s <a>global object</a>.
199+
200+
6. Let |settingsObject| be a new <a>environment settings object</a> whose algorithms are
201+
defined as follows:
202+
203+
: The <a>realm execution context</a>
204+
:: Return |executionContext|.
205+
206+
: The <a>global object</a>
153207
:: Return |workletGlobalScope|.
154208

155-
: The <a>responsible browsing context</a>:
156-
:: Return |inheritedResponsibleBrowsingContext|.
209+
: The <a>responsible browsing context</a>
210+
:: Return |inheritedResponsibleBrowsingContext|.
157211

158-
: The <a>responsible event loop</a>:
159-
:: Return |workerEventLoop|.
212+
: The <a>responsible event loop</a>
213+
:: Return |workletEventLoop|.
160214

161-
: The <a>responsible document</a>:
162-
:: Not applicable (the responsible event loop is not a browsing context event loop).
215+
: The <a>responsible document</a>
216+
:: Not applicable (the <a>responsible event loop</a> is not a <a>browsing context</a>
217+
<a>event loop</a>).
163218

164-
: The <a>API URL character encoding</a>:
219+
: The <a>API URL character encoding</a>
165220
:: Return UTF-8.
166221

167-
: The <a>API base URL</a>:
222+
: The <a>API base URL</a>
168223
:: Return |inheritedAPIBaseURL|.
169224

170-
: The <a>origin</a> and <a>effective script origin</a>:
225+
: The <a>origin</a> and <a>effective script origin</a>
171226
:: Return |inheritedOrigin|.
172227

173-
3. Associate the |settingsObject| with |workletGlobalScope|.
228+
: The <a>creation URL</a>
229+
:: Not applicable.
174230

175-
4. For each |script| in the given |worklet|'s <b>worklet's loaded scripts</b> run the |script| in the |workletGlobalScope|.
231+
: The <a>HTTPS state</a>
232+
:: Return |workletGlobalScope|'s <a>HTTPS state</a>.
233+
234+
7. Return |settingsObject|.
235+
236+
Issue: Merge this with https://html.spec.whatwg.org/multipage/workers.html#set-up-a-worker-environment-settings-object
176237

177238
Worklet {#worklet-section}
178239
--------------------------
@@ -251,19 +312,17 @@ Issue(w3c/css-houdini-drafts#53): Worth adding dispose to classes to allow clean
251312
Processing Model {#processing-model}
252313
------------------------------------
253314

254-
The <a>invoke a method on a class inside a {{Worklet}}</a> has two hooks for algorithm steps that may be customized by any callers:
255-
- <dfn export>create a worklet global scope</dfn>
315+
The <a>invoke a method on a class inside a Worklet</a> has two hooks for algorithm steps that may be customized by any callers:
256316
- <dfn export>lookup a class instance on a worklet global scope</dfn>
257317

258-
When a user agent is to <dfn export>invoke a method on a class inside a {{Worklet}}</dfn> given a |methodPropertyKey|, some |arguments|,
259-
it must run the following steps:
318+
When a user agent is to <dfn export>invoke a method on a class inside a Worklet</dfn> given a
319+
|methodPropertyKey|, |workletGlobalScopeType|, some |arguments|, it must run the following steps:
260320

261321
1. Let |workletGlobalScope| be a {{WorkletGlobalScope}} from the list of the <b>worklet's {{WorkletGlobalScope}}s</b>.
262322

263323
If none exist or a new {{WorkletGlobalScope}} is required, the user agent <em>must</em> run the following substeps:
264-
1. Let |workletGlobalScope| be the result of <a>create a worklet global scope</a>.
265-
2. <a>Initialize a {{WorkletGlobalScope}}</a>, given |workletGlobalScope| and |worklet|.
266-
3. Add |workletGlobalScope| to the |worklet|'s list of the <b>worklet's {{WorkletGlobalScope}}s</b>.
324+
1. Let |workletGlobalScope| be the result of <a>Create a WorkletGlobalScope</a>, given |workletGlobalScopeType| and |worklet|.
325+
2. Add |workletGlobalScope| to the |worklet|'s list of the <b>worklet's {{WorkletGlobalScope}}s</b>.
267326

268327
2. Let |classInstance| be the result of <a>lookup a class instance on a worklet global scope</a> given |workletGlobalScope|.
269328
3. Let |result| be the result of <a>Invoke</a>(O=|classInstance|, P=|methodPropertyKey|, Arguments=|arguments|).
@@ -355,10 +414,8 @@ registerAnArbitaryClass('foo', class FooClass {
355414
</pre>
356415

357416
When the user agent wants to invoke <b>process</b> on an instance of class with key <b>foo</b> it will:
358-
1. Call <a>invoke a method on a class inside a {{Worklet}}</a> given <b>process</b> as the |methodPropertyKey| and some |arguments| with the following options:
359-
- To <a>create a worklet global scope</a> the user agent will:
360-
361-
Return a new {{FakeWorkletGlobalScope}}.
362-
- To <a>lookup a class instance on a worklet global scope</a> given a |workletGlobalScope|, the user agent will:
363-
1. Let |classConstructor| be the result of looking up <b>foo</b> on the |workletGlobalScope|'s map of <b>registered class constructors</b>.
364-
2. Return the result of <a>Construct</a>(|classConstructor|).
417+
1. Call <a>invoke a method on a class inside a {{Worklet}}</a> given <b>process</b> as the
418+
|methodPropertyKey|, FakeWorkletGlobalScope as |workletGlobalScopeType| and some |arguments| with the following options:
419+
- To <a>lookup a class instance on a worklet global scope</a> given a |workletGlobalScope|, the user agent will:
420+
1. Let |classConstructor| be the result of looking up <b>foo</b> on the |workletGlobalScope|'s map of <b>registered class constructors</b>.
421+
2. Return the result of <a>Construct</a>(|classConstructor|).

0 commit comments

Comments
 (0)