Skip to content

Editorial: Clean up spec markdown #75

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Apr 4, 2024
Merged

Editorial: Clean up spec markdown #75

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
16bccb7
Editorial: Clean up controlling tasks section of the spec
shaseley Jul 24, 2023
daa4bb0
cr: clelland
shaseley Apr 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 44 additions & 51 deletions spec/controlling-tasks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,12 @@
Controlling Tasks {#sec-controlling-tasks}
=====================
# Controlling Tasks # {#sec-controlling-tasks}

Tasks scheduled through the {{Scheduler}} interface can be controlled with a
{{TaskController}} by passing the {{TaskSignal}} provided by
{{AbortController/signal|controller.signal}} as the
{{SchedulerPostTaskOptions/signal|option}} when calling {{Scheduler/postTask()}}.
The {{TaskController}} interface supports aborting and changing the priority of
a task or group of tasks.
Tasks scheduled through the {{Scheduler}} interface can be controlled with a {{TaskController}} by
passing the {{TaskSignal}} provided by {{AbortController/signal|controller.signal}} as the
{{SchedulerPostTaskOptions/signal|option}} when calling {{Scheduler/postTask()}}. The
{{TaskController}} interface supports aborting and changing the priority of a task or group of
tasks.

The `TaskPriorityChangeEvent` Interface {#sec-task-priority-change-event}
---------------------
## The `TaskPriorityChangeEvent` Interface ## {#sec-task-priority-change-event}

<pre class='idl'>
[Exposed=(Window, Worker)]
Expand All @@ -27,19 +24,17 @@ The `TaskPriorityChangeEvent` Interface {#sec-task-priority-change-event}
<dl class="domintro non-normative">
<dt><code>event . {{TaskPriorityChangeEvent/previousPriority}}</code></dt>
<dd>
<p>Returns the {{TaskPriority}} of the corresponding {{TaskSignal}} prior to
this `prioritychange` event.
<p>Returns the {{TaskPriority}} of the corresponding {{TaskSignal}} prior to this
`prioritychange` event.

<p>The new {{TaskPriority}} can be read with `event.target.priority`.
</dd>
</dl>

The <dfn attribute for=TaskPriorityChangeEvent>previousPriority</dfn> getter
steps are to return the value that the corresponding attribute was initialized
to.
The <dfn attribute for=TaskPriorityChangeEvent>previousPriority</dfn> getter steps are to return the
value that the corresponding attribute was initialized to.

The `TaskController` Interface {#sec-task-controller}
---------------------
## The `TaskController` Interface ## {#sec-task-controller}

<pre class='idl'>
dictionary TaskControllerInit {
Expand All @@ -54,22 +49,21 @@ The `TaskController` Interface {#sec-task-controller}
};
</pre>

Note: {{TaskController}}'s {{AbortController/signal}} getter, which is
inherited from {{AbortController}}, returns a {{TaskSignal}} object.
Note: {{TaskController}}'s {{AbortController/signal}} getter, which is inherited from
{{AbortController}}, returns a {{TaskSignal}} object.

<dl class="domintro non-normative">
<dt><code>controller = new {{TaskController/TaskController()|TaskController}}( |init| )</code>
<dd>
<p> Returns a new {{TaskController}} whose {{AbortController/signal}} is
set to a newly created {{TaskSignal}} with its {{TaskSignal/priority}}
initialized to |init|'s {{TaskControllerInit/priority}}.
<p> Returns a new {{TaskController}} whose {{AbortController/signal}} is set to a newly created
{{TaskSignal}} with its {{TaskSignal/priority}} initialized to |init|'s
{{TaskControllerInit/priority}}.
</dd>

<dt><code>controller . {{TaskController/setPriority()|setPriority}}( |priority| )</code>
<dd>
<p>Invoking this method will change the associated {{TaskSignal}}'s
[=TaskSignal/priority=], signal the priority change to any observers, and
cause `prioritychange` events to be dispatched.
<p>Invoking this method will change the associated {{TaskSignal}}'s [=TaskSignal/priority=],
signal the priority change to any observers, and cause `prioritychange` events to be dispatched.
</dd>
</dl>

Expand All @@ -82,12 +76,10 @@ inherited from {{AbortController}}, returns a {{TaskSignal}} object.
1. Set [=this's=] [=AbortController/signal=] to |signal|.
</div>

The <dfn method for=TaskController><code>setPriority(|priority|)</code></dfn>
method steps are to [=TaskSignal/signal priority change=] on [=this=]'s
[=AbortController/signal=] given |priority|.
The <dfn method for=TaskController><code>setPriority(|priority|)</code></dfn> method steps are to
[=TaskSignal/signal priority change=] on [=this=]'s [=AbortController/signal=] given |priority|.

The `TaskSignal` Interface {#sec-task-signal}
---------------------
## The `TaskSignal` Interface ## {#sec-task-signal}

<pre class='idl'>
dictionary TaskSignalAnyInit {
Expand All @@ -104,9 +96,9 @@ The `TaskSignal` Interface {#sec-task-signal}
};
</pre>

Note: {{TaskSignal}} inherits from {{AbortSignal}} and can be used in APIs that
accept an {{AbortSignal}}. Additionally, {{Scheduler/postTask()}} accepts an
{{AbortSignal}}, which can be useful if dynamic prioritization is not needed.
Note: {{TaskSignal}} inherits from {{AbortSignal}} and can be used in APIs that accept an
{{AbortSignal}}. Additionally, {{Scheduler/postTask()}} accepts an {{AbortSignal}}, which can be
useful if dynamic prioritization is not needed.

<dl class="domintro non-normative">
<dt><code>TaskSignal . <a method for=TaskSignal lt="any(signals, init)">any</a>(|signals|, |init|)</code>
Expand Down Expand Up @@ -137,30 +129,32 @@ A {{TaskSignal}} object has associated <dfn for=TaskSignal>dependent signals</df
of {{TaskSignal}} objects that are dependent on the object for their [=TaskSignal/priority=]), which
is initially empty.

A {{TaskSignal}} object has an associated <dfn for=TaskSignal>dependent</dfn> (a
boolean), which is initially false.
A {{TaskSignal}} object has an associated <dfn for=TaskSignal>dependent</dfn> (a boolean), which is
initially false.

<br>
<hr>

The <dfn attribute for="TaskSignal">priority</dfn> getter steps are to return
[=this=]'s [=TaskSignal/priority=].
The <dfn attribute for="TaskSignal">priority</dfn> getter steps are to return [=this=]'s
[=TaskSignal/priority=].

The <dfn attribute for=TaskSignal><code>onprioritychange</code></dfn> attribute
is an [=event handler IDL attribute=] for the `onprioritychange`
[=event handler=], whose [=event handler event type=] is
<dfn event for=TaskSignal>prioritychange</dfn>.
The <dfn attribute for=TaskSignal><code>onprioritychange</code></dfn> attribute is an [=event
handler IDL attribute=] for the `onprioritychange` [=event handler=], whose [=event handler event
type=] is <dfn event for=TaskSignal>prioritychange</dfn>.

To <dfn for="TaskSignal">add a priority change algorithm</dfn> |algorithm| to a
{{TaskSignal}} object |signal|, [=set/append=] |algorithm| to |signal|'s
[=TaskSignal/priority change algorithms=].
The static <dfn method for=TaskSignal><code>any(|signals|, |init|)</code></dfn> method steps are to
return the result of [=creating a dependent task signal=] from |signals| and |init|.

<br>
<hr>

A {{TaskSignal}} <dfn for=TaskSignal lt="has fixed priority|have fixed priority">has fixed priority</dfn>
if it is a [=TaskSignal/dependent=] signal with a null [=TaskSignal/source signal=].

To <dfn for="TaskSignal">add a priority change algorithm</dfn> |algorithm| to a {{TaskSignal}}
object |signal|, [=set/append=] |algorithm| to |signal|'s [=TaskSignal/priority change algorithms=].

<div algorithm>
The static <dfn method for=TaskSignal><code>any(|signals|, |init|)</code></dfn> method steps are:
To <dfn>create a dependent task signal</dfn> from a [=list=] of {{AbortSignal}} objects |signals|
and a {{TaskSignalAnyInit}} |init|:

1. Let |resultSignal| be the result of <a for=AbortSignal>creating a dependent signal</a> from
|signals| using the {{TaskSignal}} interface and the [=current realm=].
Expand All @@ -180,8 +174,8 @@ if it is a [=TaskSignal/dependent=] signal with a null [=TaskSignal/source signa
</div>

<div algorithm>
To <dfn for="TaskSignal">signal priority change</dfn> on a {{TaskSignal}}
object |signal|, given a {{TaskPriority}} |priority|:
To <dfn for="TaskSignal">signal priority change</dfn> on a {{TaskSignal}} object |signal|, given a
{{TaskPriority}} |priority|:

1. If |signal|'s [=TaskSignal/priority changing=] is true, then [=exception/throw=]
a "{{NotAllowedError!!exception}}" {{DOMException}}.
Expand All @@ -205,7 +199,6 @@ A [=TaskSignal/dependent=] {{TaskSignal}} object must not be garbage collected w
[=TaskSignal/source signal=] is non-null and it has registered event listeners for its
{{TaskSignal/prioritychange}} event or its [=TaskSignal/priority change algorithms=] is non-empty.

Examples {#sec-controlling-tasks-examples}
---------------------
## Examples ## {#sec-controlling-tasks-examples}

**TODO**(shaseley): Add examples.
13 changes: 13 additions & 0 deletions spec/index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,19 @@ Include MDN Panels: maybe
top: -0.8em;
left: -0.8em;
}

/* WHATWG-style <hr>s, instead of WICG-style. Specific selector is necessary to override WICG styles. */
:not(.head) > :not(.head) + hr {
display: block;
background: none;
border: none;
padding: 0;
margin: 2em 0;
height: auto;
}
:not(.head) > :not(.head) + hr::before {
content: none;
}
</style>

<pre class=link-defaults>
Expand Down
3 changes: 1 addition & 2 deletions spec/introduction.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
Introduction {#intro}
=====================
# Introduction # {#intro}

<div class="non-normative">

Expand Down
62 changes: 27 additions & 35 deletions spec/patches.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,58 +1,50 @@
Modifications to Other Standards {#sec-patches}
=====================
# Modifications to Other Standards # {#sec-patches}

The HTML Standard {#sec-patches-html}
---------------------
## The HTML Standard ## {#sec-patches-html}

### `WindowOrWorkerGlobalScope` ### {#sec-patches-html-windoworworkerglobalscope}

Each object implementing the {{WindowOrWorkerGlobalScope}} mixin has a
corresponding <dfn for="WindowOrWorkerGlobalScope">scheduler</dfn>, which
is initialized as a new {{Scheduler}}.
Each object implementing the {{WindowOrWorkerGlobalScope}} mixin has a corresponding
<dfn for="WindowOrWorkerGlobalScope">scheduler</dfn>, which is initialized as a new {{Scheduler}}.

<pre class='idl'>
partial interface mixin WindowOrWorkerGlobalScope {
[Replaceable] readonly attribute Scheduler scheduler;
};
</pre>

The <dfn attribute for="WindowOrWorkerGlobalScope">scheduler</dfn> attribute's
getter steps are to return [=this=]'s [=WindowOrWorkerGlobalScope/scheduler=].

The <dfn attribute for="WindowOrWorkerGlobalScope">scheduler</dfn> attribute's getter steps are to
return [=this=]'s [=WindowOrWorkerGlobalScope/scheduler=].

### <a href="https://html.spec.whatwg.org/multipage/webappapis.html#definitions-3">Event loop: definitions</a> ### {#sec-patches-html-event-loop-definitions}

Replace: For each [=event loop=], every [=task source=] must be associated with
a specific [=task queue=].
Replace: For each [=event loop=], every [=task source=] must be associated with a specific [=task
queue=].

With: For each [=event loop=], every [=task source=] that is not a
[=scheduler task source=] must be associated with a specific [=task queue=].
With: For each [=event loop=], every [=task source=] that is not a [=scheduler task source=] must be
associated with a specific [=task queue=].

### <a href="https://html.spec.whatwg.org/multipage/webappapis.html#event-loop-processing-model">Event loop: processing model</a> ### {#sec-patches-html-event-loop-processing}

Add the following steps to the event loop processing steps, before step 1:

1. Let |queues| be the [=set=] of the [=event loop=]'s [=task queues=] that
contain at least one <a for="task">runnable</a> <a for="/">task</a>.
1. Let |schedulers| be the [=set=] of all {{Scheduler}} objects whose
[=relevant agent's=] [=agent/event loop=] is this event loop and that
[=have a runnable task=].
1. If |schedulers| and |queues| are both [=list/empty=], skip to the
<code>microtasks</code> step below.
1. Let |queues| be the [=set=] of the [=event loop=]'s [=task queues=] that contain at least one
<a for="task">runnable</a> <a for="/">task</a>.
1. Let |schedulers| be the [=set=] of all {{Scheduler}} objects whose [=relevant agent's=]
[=agent/event loop=] is this event loop and that [=have a runnable task=].
1. If |schedulers| and |queues| are both [=list/empty=], skip to the <code>microtasks</code> step
below.

Modify step 1 to read:

1. Let |taskQueue| be one of the following, chosen in an
[=implementation-defined=] manner:
* If |queues| is not [=list/empty=], one of the [=task queues=] in |queues|,
chosen in an [=implementation-defined=] manner.
* If |schedulers| is not [=list/empty=], the result of
[=selecting the task queue of the next scheduler task=] from one of the
{{Scheduler}}s in |schedulers|, chosen in an [=implementation-defined=]
manner.

Issue: The |taskQueue| in this step will either be a [=set=] of [=tasks=] or a
[=set=] of [=scheduler tasks=]. The steps that follow only [=set/remove=] an
[=set/item=], so they are *roughly* compatible. Ideally, there would be a
common task queue interface that supports a `pop()` method that would return a
plain [=task=], but that would invlove a fair amount of refactoring.
1. Let |taskQueue| be one of the following, chosen in an [=implementation-defined=] manner:
* If |queues| is not [=list/empty=], one of the [=task queues=] in |queues|, chosen in an
[=implementation-defined=] manner.
* If |schedulers| is not [=list/empty=], the result of [=selecting the task queue of the next
scheduler task=] from one of the {{Scheduler}}s in |schedulers|, chosen in an
[=implementation-defined=] manner.

Issue: The |taskQueue| in this step will either be a [=set=] of [=tasks=] or a [=set=] of
[=scheduler tasks=]. The steps that follow only [=set/remove=] an [=set/item=], so they are
*roughly* compatible. Ideally, there would be a common task queue interface that supports a `pop()`
method that would return a plain [=task=], but that would invlove a fair amount of refactoring.
3 changes: 1 addition & 2 deletions spec/privacy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
Privacy Considerations {#sec-privacy}
=====================
# Privacy Considerations # {#sec-privacy}

<div class="non-normative">

Expand Down
Loading