{"id":13526992,"url":"https://github.com/WICG/scheduling-apis","last_synced_at":"2025-04-01T09:30:55.358Z","repository":{"id":40000613,"uuid":"149356704","full_name":"WICG/scheduling-apis","owner":"WICG","description":"APIs for scheduling and controlling prioritized tasks.","archived":false,"fork":false,"pushed_at":"2024-07-12T16:10:10.000Z","size":651,"stargazers_count":902,"open_issues_count":24,"forks_count":42,"subscribers_count":57,"default_branch":"main","last_synced_at":"2024-07-30T05:18:24.015Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://wicg.github.io/scheduling-apis/","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WICG.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-09-18T21:54:41.000Z","updated_at":"2024-07-30T05:18:27.088Z","dependencies_parsed_at":"2024-01-06T01:10:25.980Z","dependency_job_id":"aa1e2bbc-d035-4b85-80ab-c8b451d0b05b","html_url":"https://github.com/WICG/scheduling-apis","commit_stats":null,"previous_names":["wicg/main-thread-scheduling"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WICG%2Fscheduling-apis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WICG%2Fscheduling-apis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WICG%2Fscheduling-apis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WICG%2Fscheduling-apis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WICG","download_url":"https://codeload.github.com/WICG/scheduling-apis/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222715348,"owners_count":17027693,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T06:01:38.938Z","updated_at":"2024-11-02T12:30:19.632Z","avatar_url":"https://github.com/WICG.png","language":"HTML","funding_links":[],"categories":["HTML"],"sub_categories":[],"readme":"# Scheduling APIs\n\nThis document outlines the motivation for working on various scheduling\nAPIs\u003csup\u003e1\u003c/sup\u003e, discusses some of the problems that apps and userspace\nschedulers face when writing scheduling code, and links to [various\nproposals](#scheduling-apis-and-status) we are working on in this space.\n\n(\u003csup\u003e1\u003c/sup\u003eThe scope of this work was previously restricted to main-thread\nscheduling, and while main-thread scheduling remains the primary focus, the\nrepository and some accompanying text has been renamed to \"scheduling-apis\" to\nreflect the inclusion of APIs like\n[`scheduler.postTask()`](explainers/prioritized-post-task.md) on workers.)\n\n## Motivation: Main-thread Contention\n\nApplications may experience main-thread contention at various points in their\nexecution, e.g. during page load or as a result of user interaction. This\ncontention can negatively affect user experience in terms of responsiveness and\nlatency. For example, a busy main thread can prevent the UA from servicing\ninput, leading to poor responsiveness. Similarly, tasks (e.g. fetch\ncompletions, rendering, etc.) can experience large queuing durations during\ntimes of contention, which increases task latency and can result in degraded\nquality of experience.\n\nConsider a \"search-as-you-type\" application. This app needs to be responsive to\nuser input, i.e. users typing in the search-box. At the same time, any\nanimations on the page must be rendered smoothly, and the work for fetching and\npreparing search results and updating the page must also progress quickly.\nThere are a lot of different deadlines to meet for the app developer. It is\neasy for any long running script work to hold up the main thread and cause\nresponsiveness issues for typing, rendering animations, or updating search\nresults.\n\nAnother example pinch-zooming in a map application. The app needs to\ncontinuously respond to the input, update the rendering, and potentially fetch\nnew content to be displayed. Similar to the search-as-you-type example, long\nrunning script work could block other tasks, making the application feel laggy.\n\n## Current Solutions, Their Limitations, and APIs to Fill the Gaps\n\nDealing with contention is largely a scheduling problem: to the degree that\nwork can be reordered in an more optimal way, scheduling can have a positive\nimpact. What makes this problem more pronounced on the web is that tasks run to\ncompletion\u0026mdash;the UA cannot preempt a task to run high priority work\nlike processing user input. This problem is generally tackled in userspace by\nsystematically chunking and scheduling main-thread work. Since long tasks and\nresponsiveness are at odds, breaking up long tasks can help keep an app\nresponsive when also *yielding to the browser's event loop*.\n\n[Userspace schedulers](./misc/userspace-schedulers.md) have evolved to manage\nthese chunks of work\u0026mdash;prioritizing and executing work async at an\nappropriate time relative to current situation of user and browser. And while\nuserspace schedulers have been effective in improving responsiveness, there are\nseveral problems they still face:\n\n 1. **Coordination between (cooperating) actors**: Most userspace schedulers\n    have a notion of priority that allows tasks to be ordered in a way that\n    improves user experience. But this is limited since userspace schedulers\n    *do not control all tasks on the page*.\n\n    Apps can consist of 1P, 1P library, 3P, and (one or more) framework script\n    each of which competes for the main thread. At the same time, the browser\n    also has tasks to run on the main thread, such as `fetch()` and IDB tasks\n    and garbage collection.\n\n    Having a shared notion of priority can help the browser make better\n    scheduling decisions, which in turn can help improve user experience.\n    We propose adding a [prioritized task scheduling\n    API](./explainers/prioritized-post-task.md) to address this problem.\n\n 1. **A disparate set of scheduling APIs**: Despite the need to schedule chunks\n    of script, the Platform lacks a unified API to do so. Developers can choose\n    `setTimeout`, `postMessage`, `requestAnimationFrame`, or\n    `requestIdleCallback`, when choosing to schedule tasks.\n  \n    This disparate set of scheduling APIs makes it even more difficult for\n    developers to write scheduling code and requires expert knowledge of the\n    browser's event loop to do so. Creating a unified native scheduling API\n    \u0026mdash;[`scheduler.postTask()`](./explainers/prioritized-post-task.md)\n    \u0026mdash;will alleviate this.\n\n 1. **Determining when to yield to the browser**: yielding has overhead\u0026mdash;the\n    overhead of posting a task and context switching, the cost of regaining\n    control, etc. This can lead to increased task latency.\n\n    Making intelligent decisions about when to yield is difficult with limited\n    knowledge. Scheduling primitives can help userspace schedulers make better\n    decisions, e.g. [`isInputPending()`](https://github.com/WICG/is-input-pending)\n    and [`isFramePending()`](https://github.com/szager-chromium/isFramePending/blob/master/explainer.md).\n\n 1. **Regaining control after yielding**: chunking work and yielding is\n    necessary for improving responsiveness, but it comes at a cost: when\n    yielding to the event loop, a task that yields has no way to *continue*\n    without arbitrary work of the *same priority* running first, e.g. other\n    script. This disincentivizes yielding from a script that requires low task\n    latency. Providing a primitive like [`scheduler.yield()`](./explainers/yield-and-continuation.md)\n    that is designed to take into account this async userspace task model can\n    help, as the scheduler can prioritize these continuations more fairly.\n\n## Additional Scheduling Problems\n\nThe problem as described above only covers part of the scheduling problem\nspace. Additionally, there are developer needs for things like detecting when\na frame is pending, throttling the frame rate, and avoiding layout thrashing.\nSome of the other APIs we are considering in this space are noted [here](./misc/low-level-apis.md).\n\n## APIs and Status\n\n | API | Abstract | Status | Links |\n | --- | --- | --- | --- |\n | `scheduler.postTask()` | An API for scheduling and controlling prioritizing tasks. | This feature shipped in Chromium M94 | [Explainer](./explainers/prioritized-post-task.md) \u003cbr/\u003e [Spec](https://wicg.github.io/scheduling-apis/) \u003cbr/\u003e [Polyfill](https://github.com/WICG/scheduling-apis/issues/37) |\n | `scheduler.yield()` | An API for breaking up long tasks by yielding to the browser, continuing after being rescheduled by the scheduler. | This feature is available [behind a flag](./implementation-status.md) in Chromium M113. | [Explainer](./explainers/yield-and-continuation.md) |\n | `scheduler.wait()` | This enables tasks to yield and resume after some amount of time, or perhaps after an event has occurred. | This feature is currently being co-designed with `scheduler.yield()`. | [Related Discussion](https://github.com/WICG/scheduling-apis/issues/19) |\n | `scheduler.currentTaskSignal` | This API provides a way to get the currently running task's `TaskSignal`, which can be used to schedule dependent tasks. | This API is currently being re-evaluating in the context of `scheduler.yield()`. | [Explainer](./explainers/post-task-propagation.md) |\n | Prioritized Fetch Scheduling | Using a `TaskSignal` or `postTask` priorities for resource fetching would enable developers to prioritize critical resources, or deprioritize less critical ones. | This feature is actively being designed. | [Early Proposal](https://docs.google.com/document/d/1107Vk7csYTf_lIapd2mipVQiO73JfX1uIkOA5Rbu3k8/view) |\n | `isInputPending()` | An API for determining if the current task is blocking input events. | This API shipped in Chrome M87. | [Explainer](https://github.com/WICG/is-input-pending) \u003cbr/\u003e [Spec](https://wicg.github.io/is-input-pending/) \u003cbr/\u003e [web.dev](https://web.dev/isinputpending/) |\n\n## Further Reading / Viewing\n\n * TPAC / WebPerfWG Presentation - October 2020 [[slides](https://docs.google.com/presentation/d/1KqfH0j-OMY6kOsAyh4impB9q4OwSfX--waenzF8iFX4/edit?usp=sharing), [video](https://www.youtube.com/watch?v=LLNewXxHJfs)]: updates on various APIs are presented\n * WebPerfWG F2F Presentation - June 2019 [[slides](https://docs.google.com/presentation/d/1GUB081FTpvFEwEkfePagFEkiqcLKKnIHkhym-I8tTd8/edit#slide=id.g5b43bd1ecf_0_508), [video](https://www.youtube.com/watch?v=eyAW4FuSgyE\u0026t=14387)]: `scheduler.yield()` and `scheduler.postTask()` are presented and discussed\n * Detailed [Scheduling API Proposal](https://docs.google.com/document/d/1xU7HyNsEsbXhTgt0ZnXDbeSXm5-m5FzkLJAT6LTizEI/edit#heading=h.iw2lczs6xwe6) for `scheduler.yield()` and `scheduler.postTask()`\n * Scheduling API [MVP Proposal](https://docs.google.com/document/d/1AATlW1ohLUgjSdqukgDx3C0P6rnJFgZavmKoZxGb8Rw/edit?usp=sharing)\n * [Priority-Based Web Scheduling](https://docs.google.com/document/d/1AATlW1ohLUgjSdqukgDx3C0P6rnJFgZavmKoZxGb8Rw/edit?usp=sharing) dives into various scheduling priority systems\n * [Scheduling Overview - TPAC 2018](https://docs.google.com/presentation/d/12lkTrTwGedKSFqOFhQTsEdcLI3ydRiAdom_9uQ2FgsM/edit?usp=sharing)\n * [Talk from Chrome Dev Summit - 2018](https://youtu.be/mDdgfyRB5kg) covers the problem and larger direction\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FWICG%2Fscheduling-apis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FWICG%2Fscheduling-apis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FWICG%2Fscheduling-apis/lists"}