Add explainer document for BufferOperations

[Kangz]

This follows discussions on #138

PTAL all! @kainino0x @kvark @jdashg @litherum @RafaelCintron

[kainino0x]

Rendered

[kainino0x]

It's great to finally have terminology for this distinction - it's been getting confusing.
Multiqueue is going to change a lot though.

[Kangz]

Yep but I expect to have a similar concept of ordering (just as a general DAG instead of a line) for multi-queue.

[RafaelCintron]

Consider calling this state "invalid" instead of "invalidated". I've always associated the term 'invalidated' with a display region that needs to be repainted or that something was invalid in the past. 'Invalid', on the other hand, implies something about the current state of the object. Since invalid WebGPUMappedMemory objects can never go from the invalid state to any other state, this also lends a degree of finalness to the name.

[Kangz]

PTAL again at the "Buffer mapping" section that changed heavily to use Promise<ArrayBuffer> instead of WebGPUMappedMemory after a discussion I had with @beaufortfrancois. To be clear, there is still value in being able to poll the promise, but this can be shimmed.

The "examples" section is new too.

[kainino0x]

On the topic of promises, I'm pretty sure that having only a regular promise (even without polling api) should be technically okay for the main thread as long as it doesn't impact latency. We already have a restriction that the mapping "can only change state on task boundary", so I don't think it would impact latency, and the following code is equivalent to what we would do internally to the browser anyway:

function pollableMapWriteAsync(buffer, offset, size) {  // [edited]
  const mapping = { pointer: null };
  buffer.mapWriteAsync(offset, size).then(ab => { mapping.pointer = ab; });
  // edit: probably add .catch(e => { mapping.error = e; }); or something
  return mapping;
}

(pending = mapping.pointer == null; available = mapping.pointer.length > 0; invalid = mapping.pointer.length == 0)

I think it only becomes a problem on Workers if we lift the "can only change state on task boundary" restriction (i.e. allow spin polling). Although with the nested event loop thing I was prototyping, it's not technically necessary because promises can resolve "synchronously" (latency could be higher though, I'm not sure).

[Kangz]

@kainino0x I think you meant pollableMapWriteAsync (instead of Sync). +1 on your analysis otherwise.

[grorg]

This was discussed at the 14 Jan 2019 Teleconference

[Kangz]

PTAL again @RafaelCintron @litherum @kvark, squashed and rebased after the WebGPU -> GPU change.

[kvark]

why are we promising the buffer here? We could allow the user to start recording some operations on the buffer at this point

[Kangz]

It is a bit less elegant but could be useful. Do you have a usecase in mind?

[kvark]

I suppose there aren't that many use-cases that wouldn't be happy with either sync or async version of this call, so I'm fine with it.

[kainino0x]

Just to link these discussions, this is the same as the question with tryCreate* (#197) and createReady* (#184). Should you be able to start using something that's not ready, in prep to (maybe) use it later?

[Kangz]

We agreed on the general approach at the F2F and only minor comments on this PR. If there are no big concerns, I think we should merge this and iterate with issues / PR.

[kvark]

No big concerns from me, other than the ones I explained at F2F 🤐

[Kangz]

There hasn't been any comment on this for a week, I'll land it and we can iterate more in follow-up pull requests.