Document Compute Pressure API

[Elchi3]

Description

This pull request documents the Compute Pressure API.

Technical reviewers: @kenchris, @arskama

Additional details

This PR creates the following pages:

• Overview page for the Compute Pressure API
• Reference pages: PressureObserver, PressureRecord, compute-pressure permission policy directive.

A more hands-on "Using the Compute Pressure API" guide page could be added in a follow-up PR.

Related issues and pull requests

• BCD: Add Compute Pressure API browser-compat-data#22687

[github-actions]

Preview URLs (16 pages)

• /en-US/docs/Web/API/Compute_Pressure_API
• /en-US/docs/Web/API/Permissions_API
• /en-US/docs/Web/API/PressureObserver/PressureObserver
• /en-US/docs/Web/API/PressureObserver/disconnect
• /en-US/docs/Web/API/PressureObserver/knownSources_static
• /en-US/docs/Web/API/PressureObserver/observe
• /en-US/docs/Web/API/PressureObserver/takeRecords
• /en-US/docs/Web/API/PressureObserver/unobserve
• /en-US/docs/Web/API/PressureObserver
• /en-US/docs/Web/API/PressureRecord/source
• /en-US/docs/Web/API/PressureRecord/state
• /en-US/docs/Web/API/PressureRecord/time
• /en-US/docs/Web/API/PressureRecord/toJSON
• /en-US/docs/Web/API/PressureRecord
• /en-US/docs/Web/HTTP/Headers/Permissions-Policy/compute-pressure
• /en-US/docs/Web/HTTP/Headers/Permissions-Policy

Flaws (14)

Note! 2 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/API/Compute_Pressure_API
Title: Compute Pressure API
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: api.PressureObserver

---

URL: /en-US/docs/Web/API/PressureRecord
Title: PressureRecord
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: api.PressureRecord

---

URL: /en-US/docs/Web/API/PressureRecord/toJSON
Title: PressureRecord: toJSON() method
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: api.PressureRecord.toJSON

---

URL: /en-US/docs/Web/API/PressureRecord/state
Title: PressureRecord: state property
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: api.PressureRecord.state

---

URL: /en-US/docs/Web/API/PressureRecord/source
Title: PressureRecord: source property
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: api.PressureRecord.source

---

URL: /en-US/docs/Web/API/PressureRecord/time
Title: PressureRecord: time property
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: api.PressureRecord.time

---

URL: /en-US/docs/Web/API/PressureObserver
Title: PressureObserver
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: api.PressureObserver

---

URL: /en-US/docs/Web/API/PressureObserver/unobserve
Title: PressureObserver: unobserve() method
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: api.PressureObserver.unobserve

---

URL: /en-US/docs/Web/API/PressureObserver/knownSources_static
Title: PressureObserver: knownSources static property
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: api.PressureObserver.knownSources_static

---

URL: /en-US/docs/Web/API/PressureObserver/observe
Title: PressureObserver: observe() method
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: api.PressureObserver.observe

---

URL: /en-US/docs/Web/API/PressureObserver/takeRecords
Title: PressureObserver: takeRecords() method
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: api.PressureObserver.takeRecords

---

URL: /en-US/docs/Web/API/PressureObserver/disconnect
Title: PressureObserver: disconnect() method
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: api.PressureObserver.disconnect

---

URL: /en-US/docs/Web/API/PressureObserver/PressureObserver
Title: PressureObserver: PressureObserver() constructor
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: api.PressureObserver.PressureObserver

---

URL: /en-US/docs/Web/HTTP/Headers/Permissions-Policy/compute-pressure
Title: Permissions-Policy: compute-pressure
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: http.headers.Permissions-Policy.compute-pressure

External URLs (4)

URL: /en-US/docs/Web/API/Compute_Pressure_API
Title: Compute Pressure API

• https://w3c.github.io/compute-pressure/ (1 time) (Note! This may be a new URL 👀)
• https://w3c.github.io/compute-pressure/demo/ (1 time) (Note! This may be a new URL 👀)
• https://www.brendangregg.com/blog/2017-05-09/cpu-utilization-is-wrong.html (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/API/PressureRecord/state
Title: PressureRecord: state property

• https://w3c.github.io/compute-pressure/ (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2024-05-13 08:12:57)

[tomayac]

Just left a couple of comments. Looks pretty good already, thanks for documenting this!

[wbamberg]

Thanks Florian!

[Elchi3]

Thanks everyone, I went through all the comments. I think the outstanding questions are:

• The explainer says that rAF could only be used to mitigate issues (by triggering less frequently) and the Compute Pressure API proactively prevents pressure. How is that meant exactly? (or maybe I should remove this sentence if it doesn't help anyone) comment

• Will observe() have a promise or not? comment

• Why can observe() throw a NotAllowedError, wouldn't the constructor throw before anyway? comment

• What is takeRecords() for? Does anyone have a good example? comment

• When "cpu" is the source it watches the thread in which this observer is running, right? comment

• Epoch timestamps will be changed to document/worker creation timestamps in Chromium or what is the status? comment

• TODOs:

  • need to rename supportedSources to knownSources

[Elchi3]

I've addressed the review feedback and updated the docs per the latest spec change (supportedSources -> knownSources). I've also merged the BCD so that we can have spec and compat sections in the docs.

Marking as ready for final review.

[wbamberg]

Thanks for the updates Florian. I had some tiny comments.

[wbamberg]

👍 thank you Florian!