Add 'async' hint to functions

Author: lukewagner

design/mvp/Async.md

@@ -153,7 +153,40 @@ component-level function that has been [lifted] from Core WebAssembly with the
 function that does not have the `async` option set (which is the default and
 only option prior to Preview 3). Thus, the sync/async distinction appears
 only independently in how a component-level function is *implemented* or
-*called*.
+*called*. This lack of distinction helps to avoid the classic ["What Color Is
+Your Function?"][Color] problem.
+
+Functions *may* however be annotated (in both WIT and component binaries) with
+`async` as a *hint*. This hint is intended to inform the default language
+bindings generation, indicating whether to use a source-level `async` function
+or not in languages that have such a distinction (e.g., JS, Python, C# and
+Rust). In the absence of such a hint, a bindings generator would be forced to
+make a uniform decision for what to do by default for all functions or require
+manual programmer directives. However, because `async` is just a hint, there is
+no prohibition against non-`async`-exported functions calling imported `async`
+functions. This does mean that non-`async` functions may end up blocking
+their caller, but (1) any loss in performance is the callee's "fault", (2) the
+caller can still lower `async` if they want to (overriding the default hint),
+(3) any *transitive* caller an lower `async` to avoid blocking.
+
+For example, given this interface:
+```wit
+interface filesystem {
+  resource file {
+    constructor();
+    is-closed: func() -> bool;
+    read: async func(num-bytes: u32) -> result<list<u8>>;
+    from-bytes: static func(bytes: list<u8>) -> file;
+    from-stream: static async func(bytes: stream<u8>) -> file;
+  }
+}
+```
+a bindings generator in a language with `async` would only emit `async`
+functions for `read` and `fetch`. Since in many languages `new` expressions
+cannot be async, there is no `async constructor`. Use cases requiring
+asynchronous construction can instead use `static async` functions, similar to
+`from-stream` in this example.
+
 
 ### Task
 
@@ -708,11 +741,9 @@ time as applications are built with more components.
 ## TODO
 
 Native async support is being proposed incrementally. The following features
-will be added in future chunks roughly in the order list to complete the full
+will be added in future chunks roughly in the order listed to complete the full
 "async" story, with a TBD cutoff between what's in [WASI Preview 3] and what
 comes after:
-* `nonblocking` function type attribute: allow a function to declare in its
-  type that it will not transitively do anything blocking
 * `subtask.cancel`: allow a supertask to signal to a subtask that its result is
   no longer wanted and to please wrap it up promptly
 * zero-copy forwarding/splicing

design/mvp/Explainer.md

@@ -2209,9 +2209,12 @@ importname    ::= <exportname>
                 | <urlname>
                 | <hashname>
 plainname     ::= <label>
+                | '[async]' <label> 🔀
                 | '[constructor]' <label>
                 | '[method]' <label> '.' <label>
+                | '[async method]' <label> '.' <label> 🔀
                 | '[static]' <label> '.' <label>
+                | '[async static]' <label> '.' <label> 🔀
 label         ::= <fragment>
                 | <label> '-' <fragment>
 fragment      ::= <word>
@@ -2325,16 +2328,24 @@ The `plainname` production captures several language-neutral syntactic hints
 that allow bindings generators to produce more idiomatic bindings in their
 target language. At the top-level, a `plainname` allows functions to be
 annotated as being a constructor, method or static function of a preceding
-resource. In each of these cases, the first `label` is the name of the resource
-and the second `label` is the logical field name of the function. This
-additional nesting information allows bindings generators to insert the
-function into the nested scope of a class, abstract data type, object,
-namespace, package, module or whatever resources get bound to. For example, a
-function named `[method]C.foo` could be bound in C++ to a member function `foo`
-in a class `C`. The JS API [below](#JS-API) describes how the native JavaScript
-bindings could look. Validation described in [Binary.md](Binary.md) inspects
-the contents of `plainname` and ensures that the function has a compatible
-signature.
+resource and/or being asynchronous.
+
+When a function is annotated with `constructor`, `method` or `static`, the
+first `label` is the name of the resource and the second `label` is the logical
+field name of the function. This additional nesting information allows bindings
+generators to insert the function into the nested scope of a class, abstract
+data type, object, namespace, package, module or whatever resources get bound
+to. For example, a function named `[method]C.foo` could be bound in C++ to a
+member function `foo` in a class `C`. The JS API [below](#JS-API) describes how
+the native JavaScript bindings could look. Validation described in
+[Binary.md](Binary.md) inspects the contents of `plainname` and ensures that
+the function has a compatible signature.
+
+When a function is annotated with `async`, bindings generators are expected to
+emit whatever asynchronous language construct is appropriate (such as an
+`async` function in JS, Python or Rust). Note the absence of
+`[async constructor]`. See the [async
+explainer](Async.md#sync-and-async-functions) for more details.
 
 The `label` production used inside `plainname` as well as the labels of
 `record` and `variant` types are required to have [kebab case]. The reason for

design/mvp/WIT.md

@@ -862,6 +862,7 @@ keywords is still in flux at this time but the current set is:
 
 ```ebnf
 keyword ::= 'as'
+          | 'async'
           | 'bool'
           | 'borrow'
           | 'char'
@@ -1299,7 +1300,7 @@ typedef-item ::= resource-item
 
 func-item ::= id ':' func-type ';'
 
-func-type ::= 'func' param-list result-list
+func-type ::= 'async'? 'func' param-list result-list
 
 param-list ::= '(' named-type-list ')'
 
@@ -1312,6 +1313,17 @@ named-type-list ::= ϵ
 named-type ::= id ':' ty
 ```
 
+The optional `async` hint in a WIT function type indicates that the callee
+is expected to block and thus the caller should emit whatever asynchronous
+language bindings are appropriate (e.g., in JS, Python, C# or Rust, an `async`
+WIT function would emit an `async` JS/Python/C#/Rust function). Because `async`
+is just a hint and not enforced by the runtime, it is technically possible for
+a non-`async` callee to block. In that case, though, it is the *callee's* fault
+for any resultant loss of concurrency, not the caller's. Thus, `async` is
+primarily intended to document expectations in a way that can be taken
+advantage of by bindings generators. (For more details, see the [async
+explainer](Async.md#sync-and-async-functions).)
+
 
 ## Item: `use`
 
@@ -1528,10 +1540,13 @@ Specifically, the syntax for a `resource` definition is:
 resource-item ::= 'resource' id ';'
                 | 'resource' id '{' resource-method* '}'
 resource-method ::= func-item
-                  | id ':' 'static' func-type ';'
+                  | id ':' 'static' 'async'? func-type ';'
                   | 'constructor' param-list ';'
 ```
 
+The optional `async` hint on `static` functions has the same meaning as
+in a non-`static` `func-item`.
+
 The syntax for handle types is presented [below](#handles).
 
 ## Types