Make 'async' part of the function type, not a hint

Author: lukewagner

design/mvp/Binary.md

@@ -216,6 +216,7 @@ valtype       ::= i:<typeidx>                             => i
 resourcetype  ::= 0x3f 0x7f f?:<funcidx>?                 => (resource (rep i32) (dtor f)?)
                 | 0x3e 0x7f f:<funcidx> cb?:<funcidx>?    => (resource (rep i32) (dtor async f (callback cb)?)) 🚝
 functype      ::= 0x40 ps:<paramlist> rs:<resultlist>     => (func ps rs)
+                | 0x43 ps:<paramlist> rs:<resultlist>     => (func async ps rs)
 paramlist     ::= lt*:vec(<labelvaltype>)                 => (param lt)*
 resultlist    ::= 0x00 t:<valtype>                        => (result t)
                 | 0x01 0x00                               =>
@@ -288,7 +289,6 @@ canon    ::= 0x00 0x00 f:<core:funcidx> opts:<opts> ft:<typeidx> => (canon lift
            | 0x01 0x00 f:<funcidx> opts:<opts>                   => (canon lower f opts (core func))
            | 0x02 rt:<typeidx>                                   => (canon resource.new rt (core func))
            | 0x03 rt:<typeidx>                                   => (canon resource.drop rt (core func))
-           | 0x07 rt:<typeidx>                                   => (canon resource.drop rt async (core func)) 🚝
            | 0x04 rt:<typeidx>                                   => (canon resource.rep rt (core func))
            | 0x08                                                => (canon backpressure.set (core func)) 🔀✕
            | 0x24                                                => (canon backpressure.inc (core func)) 🔀
@@ -515,7 +515,8 @@ named once.
 
 * The opcodes (for types, canon built-ins, etc) should be re-sorted
 * The two `depname` cases should be merged into one (`dep=<...>`)
-* The two `list` type codes should be merged into one with an optional immediate.
+* The two `list` type codes should be merged into one with an optional immediate
+  and similarly for `func`.
 * The `0x00` variant of `importname'` and `exportname'` will be removed. Any
   remaining variant(s) will be renumbered or the prefix byte will be removed or
   repurposed.

design/mvp/CanonicalABI.md

@@ -71,6 +71,7 @@ the same way that they already bind to various OS's concurrent I/O APIs (such
 as `select`, `epoll`, `io_uring`, `kqueue` and Overlapped I/O) making the
 Component Model "just another OS" from the language toolchain's perspective.
 
+TODO
 The new async ABI can be used alongside or instead of the existing Preview 2
 "sync ABI" to call or implement *any* WIT function type, not just functions
 with specific signatures. This allows *all* function types to be called or
@@ -83,6 +84,7 @@ pairings have well-defined, composable behavior for both inter-component and
 intra-component calls, so that functions and components are not forced to pick
 a "[color]".
 
+TODO
 Although Component Model function *types* are colorless, it can still be
 beneficial, especially in languages with `async`/`await`-style concurrency, to
 give the bindings generator a *hint* as to whether or not a particular function
@@ -159,6 +161,7 @@ any more until I let some of them complete". Thus, the Component Model provides
 a built-in way for a component instance to apply and release backpressure that
 callers must always be prepared to handle.
 
+TODO: ("through an `async` function type so that blocking doesn't trap")
 With this backpressure mechanism in place, there is a natural way for sync and
 async code to interoperate:
 1. If an async component calls a sync component and the sync component blocks,
@@ -558,6 +561,9 @@ attempting to `thread.resume-later` a thread waiting on `waitable-set.wait` or
 a synchronous import call will trap. Thus, language runtimes and compilers have
 to be careful when using a mix of explicit and implicit suspension/resumption.
 
+TODO: suspend before returning value from a non-`async` function traps,
+specifically: `thread.suspend`, `waitable-set.wait`. Also others
+
 Lastly, when an async function is implemented using the `callback` suboption
 (mentioned in the [summary](#summary)), instead of calling `wait`, `poll` or
 `yield`, as an optimization, the `callback` function can *return* to wait in
@@ -589,6 +595,12 @@ event, allowing a higher degree of concurrency than synchronous exports.
 Stackfull async exports ignore the lock entirely and thus achieve the highest
 degree of (cooperative) concurrency.
 
+TODO: non-`async` functions don't pile up like `async` functions and aren't
+allowed to block, and thus can and must skip backpressure. If a single
+component exports by `async` and non-`async` functions, sync functions ignore
+implicit backpressure and thus barge in like signal handlers. Codegen must
+be aware.
+
 Once a task is allowed to start according to these backpressure rules, its
 arguments are lowered into the callee's linear memory and the task is in
 the "started" state.
@@ -619,6 +631,8 @@ transitively created by that thread) must call `task.return`.
 Once `task.return` is called, the task is in the "returned" state. Calling
 `task.return` when not in the "started" state traps.
 
+TODO: once in the "returned" state, even non-`async` functions can block
+
 ### Borrows
 
 Component Model async support is careful to ensure that `borrow`ed handles work
@@ -686,13 +700,14 @@ the next cancellable wait. In the worst case, though, a component may never
 wait cancellably and thus cancellation may be silently ignored.
 
 `subtask.cancel` can be called synchronously or asynchronously. If called
-synchronously, `subtask.cancel` waits until the subtask reaches a resolved
-state and returns which state was reached. If called asynchronously, then if a
-cancellable subtask thread is resumed *and* the subtask reaches a resolved
-state before suspending itself for whatever reason `subtask.cancel` will return
-which state was reached. Otherwise, `subtask.cancel` will return a "blocked"
-sentinel value and the caller must [wait][waiting] via waitable set until the
-subtask reaches a resolved state.
+synchronously, `subtask.cancel` blocks until the subtask reaches a resolved
+state and returns which state was reached. (TODO: traps if not allowed to
+block) If called asynchronously, then if a cancellable subtask thread is
+resumed *and* the subtask reaches a resolved state before suspending itself for
+whatever reason `subtask.cancel` will return which state was reached.
+Otherwise, `subtask.cancel` will return a "blocked" sentinel value and the
+caller must [wait][waiting] via waitable set until the subtask reaches a
+resolved state.
 
 The Component Model does not provide a mechanism to force prompt termination of
 threads as this can lead to leaks and corrupt state in a still-live component
@@ -807,8 +822,10 @@ function an async-oriented core function signature that can be used instead of
 or in addition to the existing (Preview-2-defined) synchronous core function
 signature. This async-oriented core function signature is intended to be called
 or implemented by generated bindings which then map the low-level core async
-protocol to the languages' higher-level native concurrency features. Because
-the WIT-level `async` attribute is purely a *hint* (as mentioned
+protocol to the languages' higher-level native concurrency features.
+
+TODO
+Because the WIT-level `async` attribute is purely a *hint* (as mentioned
 [above](#summary)), *every* WIT function has an async core function signature;
 `async` just provides hints to the bindings generator for which to use by
 default.
@@ -818,10 +835,10 @@ default.
 Given these imported WIT functions (using the fixed-length-list feature 🔧):
 ```wit
 world w {
-  import foo: func(s: string) -> u32;
-  import bar: func(s: string) -> string;
-  import baz: func(t: list<u64; 5>) -> string;
-  import quux: func(t: list<u32; 17>) -> string;
+  import foo: async func(s: string) -> u32;
+  import bar: async func(s: string) -> string;
+  import baz: async func(t: list<u64; 5>) -> string;
+  import quux: async func(t: list<u32; 17>) -> string;
 }
 ```
 the default/synchronous lowered import function signatures are:
@@ -871,22 +888,22 @@ receiving an event indicating that the async subtask has started/returned.
 
 Other example asynchronous lowered signatures:
 
-| WIT function type                         | Async ABI             |
-| ----------------------------------------- | --------------------- |
-| `func()`                                  | `(func (result i32))` |
-| `func() -> string`                        | `(func (param $out-ptr i32) (result i32))` |
-| `func(x: f32) -> f32`                     | `(func (param $x f32) (param $out-ptr i32) (result i32))` |
-| `func(s: string, t: string)`              | `(func (param $s-ptr i32) (param $s-len i32) (result $t-ptr i32) (param $t-len i32) (result i32))` |
+| WIT function type                  | Async ABI             |
+| ---------------------------------- | --------------------- |
+| `async func()`                     | `(func (result i32))` |
+| `async func() -> string`           | `(func (param $out-ptr i32) (result i32))` |
+| `async func(x: f32) -> f32`        | `(func (param $x f32) (param $out-ptr i32) (result i32))` |
+| `async func(s: string, t: string)` | `(func (param $s-ptr i32) (param $s-len i32) (result $t-ptr i32) (param $t-len i32) (result i32))` |
 
 `future` and `stream` can appear anywhere in the parameter or result types. For example:
 ```wit
-func(s1: stream<future<string>>, s2: list<stream<string>>) -> result<stream<string>, stream<error>>
+async func(s1: stream<future<string>>, s2: list<stream<string>>) -> result<stream<string>, stream<error>>
 ```
 In *both* the sync and async ABIs, a `future` or `stream` in the WIT-level type
 translates to a single `i32` in the ABI.  This `i32` is an index into the
 current component instance's handle table. For example, for the WIT function type:
 ```wit
-func(f: future<string>) -> future<u32>
+async func(f: future<string>) -> future<u32>
 ```
 the synchronous ABI has signature:
 ```wat
@@ -911,7 +928,7 @@ Explainer]. For a complete description of how async imports work, see
 Given an exported WIT function:
 ```wit
 world w {
-  export foo: func(s: string) -> string;
+  export foo: async func(s: string) -> string;
 }
 ```
 
@@ -1004,7 +1021,7 @@ Starting with the stackful ABI, the meat of this example component is replaced
 with `...` to focus on the overall flow of function calls:
 ```wat
 (component
-  (import "fetch" (func $fetch (param "url" string) (result (list u8))))
+  (import "fetch" (func $fetch async (param "url" string) (result (list u8))))
   (core module $Libc
     (memory (export "mem") 1)
     (func (export "realloc") (param i32 i32 i32 i32) (result i32) ...)
@@ -1064,7 +1081,7 @@ with `...` to focus on the overall flow of function calls:
   ))))
   (canon lift (core func $main "summarize")
     async (memory $mem) (realloc $realloc)
-    (func $summarize (param "urls" (list string)) (result string)))
+    (func $summarize async (param "urls" (list string)) (result string)))
   (export "summarize" (func $summarize))
 )
 ```
@@ -1087,6 +1104,10 @@ call to `waitable-set.wait` blocks, the runtime will suspend its callstack
 entry point and store it in context-local storage (via `context.set`) instead
 of simply using a `global`, as in a synchronous function.
 
+Note that removing `async` from the type of `summarize` specified in the `canon
+lift` definition would cause the above component to trap when it attempted to
+call `waitable-set.wait`.
+
 ### Stackless ABI example
 
 The stackful example can be re-written to use the `callback` immediate (thereby
@@ -1102,7 +1123,7 @@ core wasm code between events, not externally-visible behavior.
 
 ```wat
 (component
-  (import "fetch" (func $fetch (param "url" string) (result (list u8))))
+  (import "fetch" (func $fetch async (param "url" string) (result (list u8))))
   (core module $Libc
     (memory (export "mem") 1)
     (func (export "realloc") (param i32 i32 i32 i32) (result i32) ...)
@@ -1169,7 +1190,7 @@ core wasm code between events, not externally-visible behavior.
   ))))
   (canon lift (core func $main "summarize")
     async (callback (core func $main "cb")) (memory $mem) (realloc $realloc)
-    (func $summarize (param "urls" (list string)) (result string)))
+    (func $summarize async (param "urls" (list string)) (result string)))
   (export "summarize" (func $summarize))
 )
 ```

design/mvp/Concurrency.md

@@ -568,7 +568,7 @@ valtype       ::= <typeidx>
                 | <defvaltype>
 resourcetype  ::= (resource (rep i32) (dtor <funcidx>)?)
                 | (resource (rep i32) (dtor async <funcidx> (callback <funcidx>)?)?) 🚝
-functype      ::= (func (param "<label>" <valtype>)* (result <valtype>)?)
+functype      ::= (func async? (param "<label>" <valtype>)* (result <valtype>)?)
 componenttype ::= (component <componentdecl>*)
 instancetype  ::= (instance <instancedecl>*)
 componentdecl ::= <importdecl>
@@ -737,11 +737,10 @@ are useful for:
 
 A `future<T>` asynchronously delivers exactly one `T` value from a source to a
 destination, unless the destination signals that it doesn't want the `T` value
-any more. Because [all imports can be called asynchronously][summary], futures
-are not necessary to express a traditional `async` function -- all functions
-are effectively `async`. Instead futures are useful in more advanced scenarios
-where a parameter or result value may not be ready at the same time as the
-other synchronous parameters or results.
+any more. When function types contain the [`async`][summary] effect, the return
+value is returned asynchronously if the call blocks (and is returned
+synchronously otherwise) and thus there is no need to *additionally* return a
+`future<T>` value unless *additional* asynchronous signalling is required.
 
 The `T` element type of `stream` and `future` is an optional `valtype`. As with
 variant-case payloads and function results, when `T` is absent, the "value(s)"
@@ -793,7 +792,10 @@ shared-nothing functions, resources, components, and component instances:
 
 The `func` type constructor describes a component-level function definition
 that takes a list of `valtype` parameters with [strongly-unique] names and
-optionally returns a `valtype`.
+optionally returns a `valtype`. The optional `async` effect type indicates that
+calling the function may block (because the function transitively calls a
+blocking built-in like `waitable-set.wait` or blocks on an imported `async`
+function).
 
 The `resource` type constructor creates a fresh type for each instance of the
 containing component (with "freshness" and its interaction with general
@@ -1413,7 +1415,6 @@ dynamically interact with Canonical ABI entities like resources,
 canon ::= ...
         | (canon resource.new <typeidx> (core func <id>?))
         | (canon resource.drop <typeidx> (core func <id>?))
-        | (canon resource.drop <typeidx> async (core func <id>?)) 🚝
         | (canon resource.rep <typeidx> (core func <id>?))
         | (canon context.get <valtype> <u32> (core func <id>?)) 🔀
         | (canon context.set <valtype> <u32> (core func <id>?)) 🔀
@@ -1482,32 +1483,16 @@ For details, see [`canon_resource_new`] in the Canonical ABI explainer.
 
 ###### `resource.drop`
 
-When the `async` immediate is false:
-
 | Synopsis                   |                                    |
 | -------------------------- | ---------------------------------- |
 | Approximate WIT signature  | `func<T>(t: T)`                    |
 | Canonical ABI signature    | `[t:i32] -> []`                    |
 
-🚝 When the `async` immediate is true:
-
-| Synopsis                   |                                    |
-| -------------------------- | ---------------------------------- |
-| Approximate WIT signature  | `func<T>(t: T) -> option<subtask>` |
-| Canonical ABI signature    | `[t:i32] -> [i32]`                 |
-
 The `resource.drop` built-in drops a resource handle `t` (with resource type
 `T`). If the dropped handle owns the resource, the resource's `dtor` is called,
 if present. Validation only allows `resource.rep T` to be used within the
 component that defined `T`.
 
-When the `async` immediate is true, the returned value indicates whether the
-drop completed eagerly, or if not, identifies the in-progress drop.
-
-In the Canonical ABI, the returned `i32` is either `0` (if the drop completed
-eagerly) or the index of the in-progress drop subtask (representing the
-in-progress `dtor` call).
-
 For details, see [`canon_resource_drop`] in the Canonical ABI explainer.
 
 ###### `resource.rep`
@@ -2521,12 +2506,9 @@ 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>
@@ -2671,10 +2653,10 @@ annotations trigger additional type-validation rules (listed in
 * Similarly, an import or export named `[method]R.foo` must be a function whose
   first parameter must be `(param "self" (borrow $R))`.
 
-When a function is annotated with `async`, bindings generators are expected to
+When a function's type is `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 [concurrency explainer] for more details.
+`async` function in JS, Python or Rust). See the [concurrency explainer] 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
@@ -2806,7 +2788,8 @@ Thus, the following names are strongly-unique:
 * `foo`, `foo-bar`, `[constructor]foo`, `[method]foo.bar`, `[method]foo.baz`
 
 but attempting to add *any* of the following names would be a validation error:
-* `foo`, `foo-BAR`, `[constructor]foo-BAR`, `[method]foo.foo`, `[async]foo`, `[method]foo.BAR`
+* `foo`, `foo-BAR`, `[constructor]foo-BAR`, `[method]foo.foo`,
+  `[static]foo.foo`, `[method]foo.BAR`
 
 Note that additional validation rules involving types apply to names with
 annotations. For example, the validation rules for `[constructor]foo` require

design/mvp/Explainer.md

@@ -1450,16 +1450,11 @@ 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 [concurrency
-explainer](Concurrency.md).)
+The optional `async` prefix in a WIT function type indicates that the callee
+may block and thus the caller should emit asynchronous source-language bindings
+if appropriate (e.g., in JS, Python, C# or Rust, an `async` WIT function would
+emit an `async` JS/Python/C#/Rust function). (For more details, see the
+[concurrency explainer](Concurrency.md).)
 
 
 ## Item: `use`
@@ -1689,8 +1684,8 @@ resource-method ::= func-item
                   | 'constructor' param-list ';'
 ```
 
-The optional `async` hint on `static` functions has the same meaning as
-in a non-`static` `func-item`.
+The optional `async` on `static` functions has the same meaning as in a
+non-`static` `func-item`.
 
 The syntax for handle types is presented [below](#handles).