Skip to content

Mention certain ArrayBuffers have controlled detachment #40457

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.

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 4 commits into from
Jul 21, 2025

Conversation

Josh-Cena
Copy link
Member

Fix #39021.

The main change is made to the JS docs, but I'm updating GPUBuffer.getMappedRange as well, because this is not an exception of this method itself.

@Josh-Cena Josh-Cena requested review from a team as code owners July 20, 2025 16:57
@Josh-Cena Josh-Cena requested review from chrisdavidmills and sideshowbarker and removed request for a team July 20, 2025 16:57
@github-actions github-actions bot added Content:WebAPI Web API docs Content:JS JavaScript docs size/s [PR only] 6-50 LoC changed labels Jul 20, 2025
Copy link
Contributor

github-actions bot commented Jul 20, 2025

Copy link
Contributor

@chrisdavidmills chrisdavidmills left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @Josh-Cena; makes sense, but I've got a question, and a suggestion for clarity.

### Exceptions

- `TypeError` {{domxref("DOMException")}}
- : Thrown if an attempt is made to detach the {{jsxref("ArrayBuffer")}} in any way other than via {{domxref("GPUBuffer.unmap()")}}.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, so you've removed this from here because this isn't an exception of getMappedRange() itself?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes exactly

@@ -33,7 +33,7 @@ A new {{jsxref("ArrayBuffer")}} object. Its contents are initialized to the cont
- {{jsxref("RangeError")}}
- : Thrown if this `ArrayBuffer` is resizable and `newByteLength` is greater than the {{jsxref("ArrayBuffer/maxByteLength", "maxByteLength")}} of this `ArrayBuffer`.
- {{jsxref("TypeError")}}
- : Thrown if this `ArrayBuffer` is already detached.
- : Thrown if this `ArrayBuffer` is already detached, or if it can only be detached by designated operations. Currently, only certain web APIs are capable of creating such tracked `ArrayBuffer` objects, such as {{domxref("GPUBuffer.getMappedRange()")}} and [`WebAssembly.Memory.buffer`](/en-US/docs/WebAssembly/Reference/JavaScript_interface/Memory/buffer).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds a bit confusing, and unclear as to how this relates to the method page it appears on. Maybe something like:

Suggested change
- : Thrown if this `ArrayBuffer` is already detached, or if it can only be detached by designated operations. Currently, only certain web APIs are capable of creating such tracked `ArrayBuffer` objects, such as {{domxref("GPUBuffer.getMappedRange()")}} and [`WebAssembly.Memory.buffer`](/en-US/docs/WebAssembly/Reference/JavaScript_interface/Memory/buffer).
- : Thrown if this `ArrayBuffer` is already detached, or if it can't be detached using `transfer()` and can only be detached by designated operations. Currently, only certain methods are capable of detaching tracked `ArrayBuffer` objects, such as those produced by {{domxref("GPUBuffer.getMappedRange()")}} and [`WebAssembly.Memory.buffer`](/en-US/docs/WebAssembly/Reference/JavaScript_interface/Memory/buffer).

Copy link
Member Author

@Josh-Cena Josh-Cena Jul 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- : Thrown if this `ArrayBuffer` is already detached, or if it can only be detached by designated operations. Currently, only certain web APIs are capable of creating such tracked `ArrayBuffer` objects, such as {{domxref("GPUBuffer.getMappedRange()")}} and [`WebAssembly.Memory.buffer`](/en-US/docs/WebAssembly/Reference/JavaScript_interface/Memory/buffer).
- : Thrown if this `ArrayBuffer` is already detached, or if it can only be detached by designated operations. Currently, only certain web APIs are capable of creating such `ArrayBuffer` objects with designated detaching methods, such as {{domxref("GPUBuffer.getMappedRange()")}} and [`WebAssembly.Memory.buffer`](/en-US/docs/WebAssembly/Reference/JavaScript_interface/Memory/buffer).

The idea is that you can't create such buffers in userland, and if you have a random array buffer in hand, very likely you don't have to worry about it.

Copy link
Contributor

@chrisdavidmills chrisdavidmills left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, I get it now; thanks @Josh-Cena! I think this works, so approving. I've included a couple of minor language nitpicks for you to consider before merging.

Co-authored-by: Chris Mills <chrisdavidmills@gmail.com>
@Josh-Cena
Copy link
Member Author

Thanks for the review!

@Josh-Cena Josh-Cena merged commit 16f462e into mdn:main Jul 21, 2025
8 checks passed
@Josh-Cena Josh-Cena deleted the controlled-arraybuffer branch July 21, 2025 13:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Content:JS JavaScript docs Content:WebAPI Web API docs size/s [PR only] 6-50 LoC changed
Projects
None yet
Development

Successfully merging this pull request may close these issues.

ArrayBuffer.p.transfer: mention that certain buffers are created as non-transferable
2 participants