Warn about async processing of written/transformed chunks

[domenic]

See WICG/serial#165.

@reillyeon, WDYT? It's a bit tricky because this section is aimed at web developers, who don't really have access to "in parallel" constructs that modify the byte data. So it doesn't directly talk about how C++ implementers should behave. Do you think this is good enough? Or maybe we should add something to https://streams.spec.whatwg.org/#other-specs-ws-creation too?

---

Preview | Diff

[reillyeon]

I think this is good enough in that respect because in the Chromium implementation of the Web Serial API the copying of bytes from the chunk happens on the same platform thread where JavaScript is executed so it isn't really "in parallel" but still raises the same concerns about asynchronous processing since JavaScript execution can be interleaved with the copying. This is behavior that a JavaScript implementation of an underlying sink could also encounter.

A couple remaining concerns,

1. Does recommending that the underlying sink make a copy of the data help when the data could also have been modified between the call to WritableStreamDefaultWriter.write() and when write() is called on the underlying sink? Asking callers to wait for the Promise returned by write() to resolve before reusing the buffer solves the problem whether or not the chunk was queued.
2. Ignoring (1), transferring the chunk would fix the problem but also is a breaking API change so it's not something a library could easily do to fix the problem after the fact.

[domenic]

1. Does recommending that the underlying sink make a copy of the data help when the data could also have been modified between the call to WritableStreamDefaultWriter.write() and when write() is called on the underlying sink?

This is a great point. Such modifications do not break the run-to-completion nature of JavaScript, like reading "in parallel" would. But they do make the code harder to reason about. I was trying to subsume the sub-problem of "parallel modifications" into the larger issue of "async modifications", but I agree that the advice in this PR doesn't really solve the async modifications problem at all.

So, I think I will change the advice here. I will have producer-focused advice, to not reuse the buffer until the promise is settled (as you suggest). And then I will have spec-writer focused advice, to not use our special spec-writer/browser-engineer powers to perform parallel reads (and thus expose ourselves to parallel modifications).

Revision coming right up.

[reillyeon]

This looks good to me.