Skip to content
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

reader.cancel([ reason ]) "behaves the same as stream.cancel(reason)" is confusing #1287

Open
jedwards1211 opened this issue Jul 7, 2023 · 1 comment
Labels
clarification Standard could be clearer

Comments

@jedwards1211
Copy link

jedwards1211 commented Jul 7, 2023

I know it's a non-normative comment, but what https://streams.spec.whatwg.org/#default-reader-prototype says threw me for a loop:

await reader.cancel([ reason ])
If the reader is active, behaves the same as stream.cancel(reason).

Because stream.cancel() rejects if the stream is locked, I incorrectly assumed I would need to

reader.releaseLock()
await reader.cancel()

However, reader.cancel() does reject if the lock has been released; reading the spec, I see that reader.cancel()actually doesn't throw if the stream is locked, unlike stream.cancel(), so the two don't behave the same at all.

It would be closer to the truth to say reader.cancel([ reason ]) behaves like reader.releaseLock() followed by stream.cancel(reason), since that wouldn't reject; but, even this is inaccurate, since according to the spec reader.cancel doesn't release the lock, it just bypasses the IsReadableStreamLocked check altogether.

@jedwards1211 jedwards1211 changed the title reader.cancel([ reason ]) "behaves the same as stream.cancel(reason)" is inaccurate and confusing reader.cancel([ reason ]) "behaves the same as stream.cancel(reason)" is confusing Jul 7, 2023
@MattiasBuelens
Copy link
Collaborator

I suppose it would be more accurate to say that stream.cancel() behaves like const reader = stream.getReader(); reader.cancel(); reader.releaseLock(), where reader is a temporary reader. But that still wouldn't be a good explanation.

In essence, you use stream.cancel() to cancel a stream if you haven't locked it. If you have, you should use reader.cancel() instead, which requires that your reader still has the active lock on the stream.

@domenic domenic added the clarification Standard could be clearer label Nov 27, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
clarification Standard could be clearer
Development

No branches or pull requests

3 participants