Add 'Readiness' section to Async.md

Author: lukewagner

design/mvp/Async.md

@@ -19,6 +19,7 @@ summary of the motivation and animated sketch of the design in action.
   * [Structured concurrency](#structured-concurrency)
   * [Streams and Futures](#streams-and-futures)
   * [Waiting](#waiting)
+  * [Readiness](#readiness)
   * [Backpressure](#backpressure)
   * [Returning](#returning)
   * [Borrows](#borrows)
@@ -459,6 +460,60 @@ tasks to be scheduled before continuing execution of the current task. A task
 can yield by either calling [`yield`] or, when using a `callback`, by returning
 the Canonical-ABI-defined "yield" code to the event loop.
 
+### Readiness
+
+When passed a non-zero-length buffer, the `stream.read` and `stream.write`
+built-ins are "completion-based" (in the style of, e.g., [Overlapped I/O] or
+[`io_uring`]) in that they complete only once one or more values have been
+copied to or from the memory buffer passed into the operation. Completion-based
+I/O avoids intermediate copies and enables a greater degree of concurrency in a
+number of cases and thus language producer toolchains should attempt to pass
+non-zero-length buffers whenever possible.
+
+Given completion-based `stream.{read,write}` built-ins, "readiness-based" APIs
+(e.g., [`select`] or [`epoll`]) can be implemented (e.g., by [wasi-libc]) by
+passing an intermedaite non-zero-length memory buffer to `stream.{read,write}`
+and signalling readiness once the operation completes. However, this approach
+incurs extra copying overhead. To avoid this overhead in a best-effort mannner,
+`stream.{read,write}` additionally allow the given buffer length to be zero in
+which case "completion" of the `stream.{read,write}` is allowed (but not
+required) to wait to complete until the other end is "ready". As the "but not
+required" caveat suggests, after a zero-length read or write succeeds, there is
+no guarantee that the next non-zero-length `stream.{read,write}` will complete
+without blocking (due to any number of practical externalities or because
+readiness was simply not possible to implement given an underlying host API).
+Thus, a robust implementation of a guest readiness-based API using zero-length
+`stream.{read,write}` must fall back to non-zero-length buffering.
+
+TODO...
+
+As an example, `select()` could be implemented in wasi-libc with the following
+rough implementation strategy
+* When `select()`ing a file descriptor, a zero-length read or write is started
+  (if one is not already pending) and the stream is added to the waitable set
+  waited on by `select()`.
+* When the zero-length read or write completes, `select()` marks the stream's
+  file descriptor as "ready" and remembers that zero-length read/write said so.
+
+ Based on this rule, to implement a traditional
+`O_NONBLOCK` `write()` or `sendmsg()` API, a writer can use a buffering scheme
+in which, after `select()` (or a similar API) signals a file descriptor is
+ready to write, the next `O_NONBLOCK` `write()`/`sendmsg()` on that file
+descriptor copies to an internal buffer and suceeds, issuing an `async`
+`stream.write` in the background and waiting for completion before signalling
+readiness again. Note that buffering only occurs when streaming between two
+components using non-blocking I/O; if either side is the host or a component
+using blocking or completion-based I/O, no buffering is necessary. This
+buffering is analogous to the buffering performed in kernel memory by a
+`pipe()`.
+
+
+* why not *require* readiness... constraints host, necessary for c2c
+* specifically c2c both-readiness case
+* trouble, but mostly only wasi-libc
+* only overhead in some cases
+
+
 ### Backpressure
 
 Once a component exports functions using the async ABI, multiple concurrent
@@ -1134,6 +1189,10 @@ comes after:
 [FS or GS Segment Base Address]: https://docs.kernel.org/arch/x86/x86_64/fsgs.html
 [Cooperative]: https://en.wikipedia.org/wiki/Cooperative_multitasking
 [Multithreading]: https://en.wikipedia.org/wiki/Multithreading_(computer_architecture)
+[Overlapped I/O]: https://en.wikipedia.org/wiki/Overlapped_I/O
+[`io_uring`]: https://en.wikipedia.org/wiki/Io_uring
+[`select`]: https://pubs.opengroup.org/onlinepubs/007908799/xsh/select.html
+[`epoll`]: https://en.wikipedia.org/wiki/Epoll
 
 [AST Explainer]: Explainer.md
 [Lift and Lower Definitions]: Explainer.md#canonical-definitions
@@ -1190,6 +1249,7 @@ comes after:
 [shared-everything-threads]: https://github.com/webAssembly/shared-everything-threads
 [memory64]: https://github.com/webAssembly/memory64
 [wasm-gc]: https://github.com/WebAssembly/gc/blob/main/proposals/gc/MVP.md
+[wasi-libc]: https://github.com/WebAssembly/wasi-libc
 
 [WASI Preview 3]: https://github.com/WebAssembly/WASI/tree/main/wasip2#looking-forward-to-preview-3
 [`wasi:http/handler.handle`]: https://github.com/WebAssembly/wasi-http/blob/main/wit-0.3.0-draft/handler.wit

design/mvp/CanonicalABI.md

@@ -1411,17 +1411,8 @@ was first, the zero-length `write` always completes, leaving the zero-length
 *must* (eventually) follow a completed zero-length `write` with a
 non-zero-length `write` that is allowed to block. This will break the loop,
 notifying the reader end and allowing it to rendezvous with a non-zero-length
-`read` and make progress. Based on this rule, to implement a traditional
-`O_NONBLOCK` `write()` or `sendmsg()` API, a writer can use a buffering scheme
-in which, after `select()` (or a similar API) signals a file descriptor is
-ready to write, the next `O_NONBLOCK` `write()`/`sendmsg()` on that file
-descriptor copies to an internal buffer and suceeds, issuing an `async`
-`stream.write` in the background and waiting for completion before signalling
-readiness again. Note that buffering only occurs when streaming between two
-components using non-blocking I/O; if either side is the host or a component
-using blocking or completion-based I/O, no buffering is necessary. This
-buffering is analogous to the buffering performed in kernel memory by a
-`pipe()`.
+`read` and make progress. See the [Readiness] section in the async explainer
+for more background on purpose of zero-length reads and writes.
 
 The two ends of a stream are stored as separate elements in the component
 instance's table and each end has a separate `CopyState` that reflects what
@@ -4486,6 +4477,7 @@ def canon_thread_available_parallelism():
 [Readable or Writable End]: Async.md#streams-and-futures
 [Context-Local Storage]: Async.md#context-local-storage
 [Subtask State Machine]: Async.md#cancellation
+[Readiness]: Async.md#readiness
 [Lazy Lowering]: https://github.com/WebAssembly/component-model/issues/383
 
 [Core WebAssembly Embedding]: https://webassembly.github.io/spec/core/appendix/embedding.html