Skip to content

Commit

Permalink
Clean up task queuing and document management
Browse files Browse the repository at this point in the history 
* Removes uses of "responsible document". This term is on its way out, per whatwg/html#4335.

* The straightforward substitution of using the associated Document didn't always make sense, because in many cases there was no sensible settings object (e.g., the algorithms were consulting the "current settings object" but were in parallel, where there is no current settings object). So, this restructures the algorithms to be more clear about what work is done in parallel vs. what work is done in queued tasks.

* Similarly, a lot of work was done on main-thread data structures and objects while in parallel, e.g. creating WakeLockSentinel objects or consulting internal slots. That was moved to be done either up front, before the algorithms go in parallel, or in queued tasks. This includes user activation checking, which allows us to eliminate the wrapper "obtain permission" algorithm.
  • Loading branch information
@domenic
domenic committed Feb 24, 2021
1 parent 54f520c commit d273f04
Showing 1 changed file with 66 additions and 91 deletions.
157 changes: 66 additions & 91 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -203,8 +203,8 @@ <h2>
Wake Lock permission revocation algorithm</dfn>, run these steps:
</p>
<ol class="algorithm">
<li>Let |document:Document| be the [=environment settings object /
responsible document=] of the <a>current settings object</a>.
<li>Let |document:Document| the [=current settings object=]'s
[=associated Document=].
</li>
<li>Let |record| be the <a>platform wake lock</a>'s <a>state
record</a> associated with |document| and <a>wake lock type</a>
Expand All @@ -213,37 +213,11 @@ <h2>
<li>[=list/For each=] |lock:WakeLockSentinel| in
|record|.{{[[ActiveLocks]]}}:
<ol>
<li>Run <a>release a wake lock</a> with |lock| and
{{WakeLockType/"screen"}}.
<li>Run <a>release a wake lock</a> with |document| and |lock|.
</li>
</ol>
</li>
</ol>
<p>
To <dfn>obtain permission</dfn> for <a>wake lock type</a> |name|, run
these steps <a>in parallel</a>. This async algorithm returns either
{{PermissionState/"granted"}} or {{PermissionState/"denied"}}.
</p>
<aside class="note">
The following algorithm is defined in this specification because the
Permissions specification currently lacks integration with the
concept of user activation from [[HTML]]. See <a href=
"https://github.com/w3c/permissions/issues/194">this issue for more
information</a>.
</aside>
<ol class="algorithm">
<li>Let |state:PermissionState| be <a>permission state</a> of the
`"screen-wake-lock"` {{PermissionName}}.
</li>
<li>If |state| is not {{PermissionState/"prompt"}}, return |state|.
</li>
<li>If the <a>current global object</a> does not have [=transient
activation=], return {{PermissionState/"denied"}}.
</li>
<li>Otherwise, return the result of <a>requesting permission to
use</a> the `"screen-wake-lock"` {{PermissionName}}.
</li>
</ol>
</section>
</section>
<section>
Expand All @@ -266,8 +240,8 @@ <h3>
</p>
<p>
Each <a>platform wake lock</a> (one per <a>wake lock type</a>) has an
associated <dfn>state record</dfn> per [=environment settings object /
responsible document=] with the following <a data-cite=
associated <dfn>state record</dfn> per {{Document}} with the following
<a data-cite=
"ECMASCRIPT#sec-object-internal-methods-and-internal-slots">internal
slots</a>:
</p>
Expand Down Expand Up @@ -295,8 +269,7 @@ <h3>
</td>
<td>
A <a>list</a> of {{WakeLockSentinel}} objects, representing
active wake locks associated with the [=environment settings
object / responsible document=].
active wake locks associated with the {{Document}}.
</td>
</tr>
</tbody>
Expand Down Expand Up @@ -337,8 +310,8 @@ <h3>
|type:WakeLockType|:
</p>
<ol class="algorithm">
<li>Let |document:Document| be the [=environment settings object /
responsible document=] of the <a>current settings object</a>.
<li>Let |document:Document| the [=current settings object=]'s
[=associated Document=].
<ol>
<li data-tests=
"wakelock-disabled-by-feature-policy.https.sub.html">If
Expand Down Expand Up @@ -367,30 +340,36 @@ <h3>
return [=a promise rejected with=] {{"NotAllowedError"}}
{{DOMException}}.
</li>
<li>If the <a>current global object</a> does not have [=transient
activation=], return [=a promise rejected with=]
{{"NotAllowedError"}} {{DOMException}}.
</li>
<li>Let |promise:Promise| be [=a new promise=].
</li>
<li>Return |promise| and run the following steps <a>in parallel</a>:
<li>Run the following steps <a>in parallel</a>:
<ol>
<li>
<a>Abort when</a> the steps to <a>determine the visibility
state</a> return `hidden`.
</li>
<li>Let |state:PermissionState| be the result of awaiting
<a>obtain permission</a> steps with "`screen-wake-lock`":
<li>Let |state:PermissionState| be the result of <a>requesting
permission to use</a> the `"screen-wake-lock"`
{{PermissionName}}.
</li>
<li data-tests="wakelock-request-denied.https.html">If |state| is
{{PermissionState/"denied"}}, then:
<ol>
<li data-tests="wakelock-request-denied.https.html">If
|state| is {{PermissionState/"denied"}}, then reject
|promise| with a {{"NotAllowedError"}} {{DOMException}}, and
abort these steps.
<li>[=Queue a global task=] on the [=screen wake lock task
source=] given |document|'s [=relevant global object=] to
[=reject=] |promise| with a {{"NotAllowedError"}}
{{DOMException}}.
</li>
<li>Abort these steps.
</li>
</ol>
</li>
<li>Let |lock:WakeLockSentinel| be a new {{WakeLockSentinel}}
object with its {{WakeLockSentinel/type}} attribute set to
|type|.
</li>
<li>Invoke <a>acquire a wake lock</a> with |lock| and
{{WakeLockType/"screen"}}.
<li>Invoke <a>acquire a wake lock</a> with |document|, |type|,
and |promise|.
<aside class="note">
The <a>acquire a wake lock</a> algorithm may ultimately be
unable to acquire a lock from the operating system, but this
Expand All @@ -399,14 +378,14 @@ <h3>
indicate low battery levels, for example).
</aside>
</li>
<li>Resolve |promise| with |lock|.
</li>
</ol>
</li>
<li>
<a>If aborted</a>, reject |promise| with a {{"NotAllowedError"}}
{{DOMException}}.
</li>
<li>Return |promise|.
</li>
</ol>
</section>
</section>
Expand Down Expand Up @@ -509,20 +488,13 @@ <h3>
following steps:
</p>
<ol class="algorithm">
<li>If <a>this</a>' {{[[Released]]}} internal slot is `true`, return
<li>If <a>this</a>'s {{[[Released]]}} internal slot is `true`, return
<a>a promise resolved with</a> `undefined`.
</li>
<li>Otherwise, let |promise:Promise| be <a>a new promise</a>.
</li>
<li>Run the following steps <a>in parallel</a>:
<ol>
<li>Run <a>release a wake lock</a> with |lock:WakeLockSentinel|
set to <a>this</a> and |type:WakeLockType| set to the value of
<a>this</a>' {{WakeLockSentinel/type}} attribute.
</li>
<li>Resolve |promise|.
</li>
</ol>
<li>Run <a>release a wake lock</a> given the [=current global
object=]'s [=associated Document=], [=this=], and |promise|.
</li>
<li>Return |promise|.
</li>
Expand Down Expand Up @@ -640,23 +612,18 @@ <h3>
<dfn>Handling document loss of full activity</dfn>
</h3>
<p data-tests="wakelock-active-document.https.window.html">
When the user agent determines that a [=environment settings object /
responsible document=] of the <a>current settings object</a> is no
longer [=Document/fully active=], it must run these steps:
When a {{Document}} |document:Document| becomes no longer
[=Document/fully active=], the user agent must run these steps:
</p>
<ol class="algorithm">
<li>Let |document:Document| be the [=environment settings object /
responsible document=] of the <a>current settings object</a>.
</li>
<li>Let |screenRecord| be the <a>platform wake lock</a>'s <a>state
record</a> associated with |document| and <a>wake lock type</a>
{{WakeLockType/"screen"}}.
</li>
<li>[=list/For each=] |lock:WakeLockSentinel| in
|screenRecord|.{{[[ActiveLocks]]}}:
<ol>
<li>Run <a>release a wake lock</a> with |lock| and
{{WakeLockType/"screen"}}.
<li>Run <a>release a wake lock</a> with |document| and |lock|.
</li>
</ol>
</li>
Expand All @@ -675,23 +642,19 @@ <h3>
the latest TR, so we cannot reference them yet. -->
<p data-tests="wakelock-document-hidden-manual.https.html">
When the user agent determines that the [=Document/visibility state=]
of the <a>Document</a> of the <a>top-level browsing context</a> has
become `hidden`, the user agent MUST run the following steps after
the <a>now hidden algorithm</a>:
of a {{Document}} |document:Document| of a <a>top-level browsing
context</a> has become `hidden`, the user agent MUST run the
following steps after the <a>now hidden algorithm</a>:
</p>
<ol class="algorithm">
<li>Let |document:Document| be the [=environment settings object /
responsible document=] of the <a>current settings object</a>.
</li>
<li>Let |screenRecord| be the <a>platform wake lock</a>'s <a>state
record</a> associated with |document| and <a>wake lock type</a>
{{WakeLockType/"screen"}}.
</li>
<li>[=list/For each=] |lock:WakeLockSentinel| in
|screenRecord|.{{[[ActiveLocks]]}}:
<ol>
<li>Run <a>release a wake lock</a> with |lock| and
{{WakeLockType/"screen"}}.
<li>Run <a>release a wake lock</a> with |document| and |lock|.
</li>
</ol>
</li>
Expand All @@ -706,8 +669,8 @@ <h3>
Acquire wake lock algorithm
</h3>
<p>
To <dfn>acquire a wake lock</dfn> for a given |lock:WakeLockSentinel|
and |type:WakeLockType|, run these steps <a>in parallel</a>:
To <dfn>acquire a wake lock</dfn> given a |document:Document|, a
|type:WakeLockType|, and a |promise:Promise|:
</p>
<ol class="algorithm">
<li>If the wake lock for type |type| is not <a>applicable</a>, abort
Expand All @@ -719,13 +682,22 @@ <h3>
<li>Ask the underlying operating system to <a>acquire the wake
lock</a> of type |type|.
</li>
<li>Let |document:Document| be the [=environment settings object /
responsible document=] of the <a>current settings object</a>.
</li>
<li>Let |record| be the <a>platform wake lock</a>'s <a>state
record</a> associated with |document| and |type|.
</li>
<li>Add |lock| to |record|.{{[[ActiveLocks]]}}.
<li>[=Queue a global task=] on the [=screen wake lock task source=]
given |document|'s [=relevant global object=] to perform the
following steps:
<ol>
<li>Let |record| be the <a>platform wake lock</a>'s <a>state
record</a> associated with |document| and |type|.
</li>
<li>Let |lock:WakeLockSentinel| be a new {{WakeLockSentinel}}
object with its {{WakeLockSentinel/type}} attribute set to
|type|.
</li>
<li>Add |lock| to |record|.{{[[ActiveLocks]]}}.
</li>
<li>[=Resolve=] |promise| with |lock|.
</li>
</ol>
</li>
</ol>
</section>
Expand All @@ -734,12 +706,12 @@ <h3>
Release wake lock algorithm
</h3>
<p>
To <dfn>release a wake lock</dfn> for a given |lock:WakeLockSentinel|
and |type:WakeLockType|, run these steps <a>in parallel</a>:
To <dfn>release a wake lock</dfn> given a |document:Document|, a
|lock:WakeLockSentinel|, and an optional |promise:Promise|:
</p>
<ol class="algorithm">
<li>Let |document:Document| be the [=environment settings object /
responsible document=] of the <a>current settings object</a>.
<li>Let |type:WakeLockType| be the value of |lock|'s
{{WakeLockSentinel/type}} attribute.
</li>
<li>Let |record| be the <a>platform wake lock</a>'s <a>state
record</a> associated with |document| and |type|.
Expand Down Expand Up @@ -771,14 +743,17 @@ <h3>
</li>
</ol>
</li>
<li>
<a>Queue a task</a> to run the following steps:
<li>[=Queue a global task=] on the [=screen wake lock task source=]
given |document|'s [=relevant global object=] to run the following
steps:
<ol>
<li>Set |lock|'s {{[[Released]]}} internal slot to `true`.
</li>
<li>
<a>Fire an event</a> named "`release`" at |lock|.
</li>
<li>If |promise| was given, then [=resolve=] |promise|.
</li>
</ol>
</li>
</ol>
Expand Down

0 comments on commit d273f04

Please sign in to comment.