Skip to content

Commit

Permalink
Fix error conventions for optional features (gpuweb#2420)
Browse files Browse the repository at this point in the history
* Fix error conventions for optional features

* relax claim
  • Loading branch information
kainino0x authored Dec 16, 2021
1 parent f700cd7 commit 73da268
Show file tree
Hide file tree
Showing 2 changed files with 36 additions and 16 deletions.
39 changes: 26 additions & 13 deletions design/ErrorConventions.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,26 +54,39 @@ passed into `o.f`.
* This is explicitly made more strict than the usual WebIDL dictionary
binding rules.

* If any object in `A` is missing a required key (given current features): Error **must** be synchronous.
* If any object in `A` contains any key that is not known to the browser (is not
present in its WebIDL code): No error.
* This is how WebIDL works.
* If possible browsers could choose to issue warnings for unrecognized keys.

* If any object in `A` sets any key that is known to the browser, but part of a
non-enabled feature, is set to any value other than its default:
Must be an error and the error **must not** be synchronous.

* If any object in `A` is missing a required key: Error **must** be synchronous
(per WebIDL).
* Dictionary members added to existing dictionaries by optional device
features **must** be optional.

* Validation which affects content-timeline behavior:
Error **should** be synchronous. E.g.:
* Two arrays must match in length, but don't.
* Offset/size parameters into a `ArrayBuffer`/`TypedArray` are
out of bounds. (Avoids copying the whole ArrayBuffer across processes.)

* Validation which depends only on individual primitives (e.g. `Number`s) in
`A`, `device.limits`, and `device.features`:
Error **should (but may not)** be synchronous.
E.g.:
Error **should not** be synchronous. E.g.:
* A `Number` exceeds the associated entry in `limits`.
* Two arrays must match in length, but don't.
* A bitflag has two incompatible bits.

* Validation which depends on state which *can be tracked* on the client-side:
Error **may (but usually won't)** be synchronous.
E.g.:
Error **may (but usually won't)** be synchronous. E.g.:
* `queue.signalFence(fence, 3); queue.signalFence(fence, 2);`
* Building an invalid command buffers (e.g. resource used in conflicting
ways inside a pass): Probably will not be synchronous.
* Building an invalid command buffer (e.g. resource used in conflicting
ways inside a pass): Not synchronous.

* Validation which depends on state which is *not synchronously known* on the client-side:
Error **must not** be synchronous.
E.g.:
* A WebGPU interface object argument is internally null.
* Validation which depends on state which is *not synchronously known* on the
client-side: Error **must not** be synchronous. E.g.:
* A WebGPU interface object argument is invalid (due to validation or OOM).
* The device is lost.
* There is an out-of-memory condition.
13 changes: 10 additions & 3 deletions spec/index.bs
Original file line number Diff line number Diff line change
Expand Up @@ -1048,9 +1048,16 @@ on all implementations, typically due to hardware or system software constraints
Each {{GPUAdapter}} exposes a set of available features.
Only those features may be requested in {{GPUAdapter/requestDevice()}}.

Functionality that is part of an feature may only be used if the feature
was requested at device creation. See the [[#feature-index|Feature Index]]
for a description of the functionality each feature enables.
Functionality that is part of an feature may only be used if the feature was requested at device
creation.
Dictionary members added to existing dictionaries by optional features are always optional at the
WebIDL level; if the feature is not enabled, such members must not be set to non-default values.

Note: Though enabling a feature won't add new IDL-required fields, it may not necessarily be
backward-compatible with existing code.
An optional feature can enable new validation which invalidates previously-valid code.

See the [[#feature-index|Feature Index]] for a description of the functionality each feature enables.

### Limits ### {#limits}

Expand Down

0 comments on commit 73da268

Please sign in to comment.