@@ -196,6 +196,54 @@ tuple<u64, string, u64> // An integer, then a string, then an integer
196196
197197This is similar to tuples in Rust or OCaml.
198198
199+ ### Streams
200+
201+ ` stream<T> ` for any type ` T ` denotes an asynchronous, ordered sequence of values of type ` T ` .
202+ Unlike a ` list<T> ` , which contains all of its values at once,
203+ a ` stream<T> ` delivers values incrementally:
204+ the producer pushes elements as they become available,
205+ and the consumer receives them as they arrive.
206+
207+ ``` wit
208+ stream<u8> // a stream of bytes
209+ stream<log-entry> // a stream of records
210+ ```
211+
212+ A ` stream<T> ` is a Canonical ABI value, not a resource:
213+ it can be returned from a function, accepted as a parameter,
214+ and passed across component boundaries the same way a primitive type is.
215+ A middle component can also hand a stream along without consuming it.
216+
217+ Streams were added for WASI 0.3 and are most often paired with a [ ` future ` ] ( #futures )
218+ that signals when the stream has terminated;
219+ the stream-plus-future tuple shape appears throughout
220+ [ ` wasi:filesystem ` ] ( https://github.com/WebAssembly/WASI/tree/main/proposals/filesystem ) ,
221+ [ ` wasi:cli ` ] ( https://github.com/WebAssembly/WASI/tree/main/proposals/cli ) ,
222+ and [ ` wasi:sockets ` ] ( https://github.com/WebAssembly/WASI/tree/main/proposals/sockets ) .
223+
224+ For the underlying motivation, see [ Async, Streams, and Futures] ( ./async.md ) .
225+
226+ ### Futures
227+
228+ ` future<T> ` for any type ` T ` is a typed handle for a single value of type ` T `
229+ that will become available later.
230+ A function returning a ` future<T> ` does not block on the value being produced;
231+ the caller awaits the future when it needs the value.
232+
233+ ``` wit
234+ future<u32> // a future that will resolve to a u32
235+ future<result<response, error-code>> // a future that will resolve to either a response or an error
236+ ```
237+
238+ Like ` stream<T> ` , ` future<T> ` is a Canonical ABI value rather than a resource,
239+ so it travels across component boundaries the same way primitives do.
240+
241+ Futures were added for WASI 0.3.
242+ They are similar to a [ ` Promise ` ] ( https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise ) in JavaScript
243+ or a [ ` std::future::Future ` ] ( https://doc.rust-lang.org/std/future/trait.Future.html ) in Rust.
244+
245+ For the underlying motivation, see [ Async, Streams, and Futures] ( ./async.md ) .
246+
199247## User-defined types
200248
201249New domain-specific types can be defined within an ` interface ` or ` world ` .
@@ -393,6 +441,22 @@ get-customers-paged: func(cont: continuation-token) -> tuple<list<customer>, con
393441A function can be declared inside an [ interface] ( #interfaces ) ,
394442or can be declared as an import or export in a [ world] ( #worlds ) .
395443
444+ ### Asynchronous functions
445+
446+ A function can be declared ` async ` , indicating that the call may suspend before producing its result:
447+
448+ ``` wit
449+ // An async function returning a result
450+ handle: async func(request: request) -> result<response, error-code>;
451+ ```
452+
453+ The runtime owns the scheduling; from the WIT perspective, the call looks like an ordinary function.
454+ Bindings generators emit each side in the host language's natural async idiom:
455+ an ` async fn ` in Rust, a ` Promise ` -returning function in JavaScript, and so on.
456+
457+ Asynchronous functions were added for WASI 0.3, alongside [ ` stream<T> ` ] ( #streams ) and [ ` future<T> ` ] ( #futures ) .
458+ For the underlying motivation, see [ Async, Streams, and Futures] ( ./async.md ) .
459+
396460## Interfaces
397461
398462An interface is a named set of types and functions,
0 commit comments