Add specification for scheduler.yield() method (#88)

Author: shaseley

spec/controlling-tasks.md

@@ -194,6 +194,15 @@ object |signal|, [=set/append=] |algorithm| to |signal|'s [=TaskSignal/priority
   1. Set |signal|'s [=TaskSignal/priority changing=] to false.
 </div>
 
+<div algorithm>
+  To <dfn>create a fixed priority unabortable task signal</dfn> given {{TaskPriority}} |priority|
+  and a [=ECMAScript/realm=] |realm|.
+
+  1. Let |init| be a new {{TaskSignalAnyInit}}.
+  1. Set |init|["{{TaskSignalAnyInit/priority}}"] to |priority|.
+  1. Return the result of [=creating a dependent task signal=] from « », |init|, and |realm|.
+</div>
+
 ### Garbage Collection ### {#sec-task-signal-garbage-collection}
 
 A [=TaskSignal/dependent=] {{TaskSignal}} object must not be garbage collected while its

spec/introduction.md

@@ -53,11 +53,16 @@ some use cases, but this only applies to idle tasks and does not account for
 tasks whose priority can change, e.g. re-prioritizing off-screen content in
 response to user input, like scrolling.
 
-This document introduces a new interface for developers to schedule and control
-prioritized tasks.  The {{Scheduler}} interface exposes a
-{{Scheduler/postTask()}} method to schedule tasks, and the specification
-defines a number of {{TaskPriority|TaskPriorities}} that control execution
-order.  Additionally, a {{TaskController}} and its associated {{TaskSignal}}
-can be used to abort scheduled tasks and control their priorities.
+This specification introduces a new interface for developers to schedule and
+control prioritized tasks and continuations. A task in this context is a
+JavaScript callback that runs asynchronously in its own [=event loop=] [=task=].
+A continuation is the resumption of JavaScript code in a new [=event loop=]
+[=task=] after yielding control to the browser. The {{Scheduler}} interface
+exposes a {{Scheduler/postTask()}} method to schedule tasks and a
+{{Scheduler/yield()}} method to schedule continuations. The specification
+defines a number of {{TaskPriority|TaskPriorities}} to control task and
+continuation execution order. Additionally, a {{TaskController}} and its
+associated {{TaskSignal}} can be used to abort scheduled tasks and control their
+priorities.
 
 </div>

spec/patches.md

@@ -32,6 +32,9 @@ determine task execution order across [=scheduler task queues=] of the same {{Ta
 all {{Scheduler}}s associated with the same [=event loop=]. A timestamp would also suffice as long
 as it is guaranteed to be strictly increasing and unique.
 
+Add: An [=event loop=] has a <dfn for="event loop">current scheduling state</dfn> (a [=scheduling
+state=] or null), which is initialized to null.
+
 ### <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 2:
@@ -56,3 +59,48 @@ Issue: The |taskQueue| in this step will either be a [=set=] of [=tasks=] or a [
 [=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 involve a fair amount of refactoring.
+
+### <a href="https://html.spec.whatwg.org/multipage/webappapis.html#hostmakejobcallback">HostMakeJobCallback(callable)</a> ### {#sec-patches-html-hostmakejobcallback}
+
+Add the following before step 5:
+
+  1. Let |event loop| be <var ignore=''>incumbent settings<var>'s
+     [=environment settings object/realm=]'s [=realm/agent=]'s [=agent/event loop=].
+  1. Let |state| be |event loop|'s [=event loop/current scheduling state=].
+
+Modify step 5 to read:
+
+ 1. Return the <span>JobCallback Record</span> { \[[Callback]]: <var ignore=''>callable</var>,
+    \[[HostDefined]]: { \[[IncumbentSettings]]: <var ignore=''>incumbent settings</var>,
+    \[[ActiveScriptContext]]: <var ignore=''>script execution context</var>,
+    \[[SchedulingState]]: |state| } }.
+
+### <a href="https://html.spec.whatwg.org/multipage/webappapis.html#hostcalljobcallback">HostCallJobCallback(callback, V, argumentsList)</a> ### {#sec-patches-html-hostcalljobcallback}
+
+Add the following steps before step 5:
+
+  1. Let |event loop| be <var ignore=''>incumbent settings<var>'s
+     [=environment settings object/realm=]'s [=realm/agent=]'s [=agent/event loop=].
+  1. Set |event loop|'s [=event loop/current scheduling state=] to
+     <var ignore=''>callback</var>.\[[HostDefined]].\[[SchedulingState]].
+
+Add the following after step 7:
+
+  1. Set |event loop|'s [=event loop/current scheduling state=] to null.
+
+## <a href="https://w3c.github.io/requestidlecallback/">`requestIdleCallback()`</a> ## {#sec-patches-requestidlecallback}
+
+### <a href="https://w3c.github.io/requestidlecallback/#invoke-idle-callbacks-algorithm">Invoke idle callbacks algorithm</a> ### {#sec-patches-invoke-idle-callbacks}
+
+Add the following step before step 3.3:
+
+  1. Let |realm| be the [=relevant realm=] for <var ignore=''>window</var>.
+  1. Let |state| be a new [=scheduling state=].
+  1. Set |state|'s [=scheduling state/priority source=] to the result of [=creating a fixed priority
+     unabortable task signal=] given "{{TaskPriority/background}}" and |realm|.
+  1. Let |event loop| be |realm|'s [=realm/agent=]'s [=agent/event loop=].
+  1. Set |event loop|'s [=event loop/current scheduling state=] to |state|.
+
+Add the following after step 3.3:
+
+  1. Set |event loop|'s [=event loop/current scheduling state=] to null.