Naming convention for sync and async APIs

[gyagp]

WebNN WG initiated a discussion with W3C TAG about naming convention for sync and async APIs (w3ctag/design-reviews#771). Some proposal from TAG is "if the main usage is sync, then x() and xAsync() seems preferable. If the main usage is async, then x() and xSync() seems preferable." (w3ctag/design-principles#402).

Most of WebGPU APIs are sync, but we still have some async APIs as below. Some of async APIs are suffixed with "Async", while most of them are not.
GPU.requestAdapter()
GPUAdapter.requestDevice()
GPUAdapter.requestAdapterInfo()
GPUDevice.createComputePipelineAsync()
GPUDevice.createRenderPipelineAsync()
GPUBuffer.mapAsync()
GPUShaderModule.compilationInfo()
GPUQueue.onSubmittedWorkDone()
GPUDevice.lost
GPUDevice.popErrorScope()

o we need to be consistent here, to put a suffix "Async" to all async APIs？

[kainino0x]

"if the main usage is sync, then x() and xAsync() seems preferable. If the main usage is async, then x() and xSync() seems preferable."

It sounds like this only applies to entry points which have both an async and sync version. Most of our entry points only have one version; only pipeline creation has two versions, and it is already named using the x/xAsync convention.

(Aside: we did previously discuss the slight possibility for confusion, because none of our entry points are actually synchronous, regardless of whether they return a Promise. In particular, the existence of xAsync implies that x is sync, but even non-"Async" pipeline creation is still asynchronous relative to the calling thread.)

[kainino0x]

It came up in the meeting that, if we added a sync version of map, then we'd have mapSync and mapAsync. We'd want to nudge people toward using the async version. So according to this guidance, we'd probably want map and mapSync. However, we didn't think it was worth renaming mapAsync to map at this time, even if it's technically slightly more consistent.

[gyagp]

Thanks for the discussion, and I'm fine to keep them as they are. Close the issue.

[kdashg]

GPU Web meeting 2022-11-16 non-APAC-timed

• KN: think this is basically editorial. Think we don't need to change anything. WebNN advice was that if you have both sync&async versions, you should have convention - but we only have this for createPipeline, and we already have a convention. So nothing to change here.
• KG: agree. Guidance doesn't say whether you're predominantly sync/async on an API level. It's per-method.
• KG: do we have methods marked "async" which don't have async counterparts?
• KN: yes. Just mapAsync. That's the main one. Others are oddities. popErrorScope - a meta-level thing. requestDevice, requestAdapter. CompilationInfo's not labeled. These all have to be async though. No possibility of having a sync version.
• KN: mapAsync's an oddity - if had async version, wouldn't call it "map".
• KG: consider calling mapAsync "map"?
• KN: don't think it's worth it. We can comment here about that.
• BJ: fwiw, it's a common pattern to use "requestX"
  • WebXR, WebBluetooth, WebUSB, and others all use this pattern for async APIs that are requesting some interface, often in a situation where failure is semi-likely.
• KN: and those don't have sync versions, and they aren't named "async".