Skip to content

Commit 424aa10

Browse files
committed
docs(design/wit): add stream<T>, future<T>, async func reference entries
Extend the WIT Reference with the three primitives that the Component Model added for WASI 0.3: stream<T> and future<T> as new built-in types after Tuples, and async func as a new subsection of Functions. Each entry covers the WIT syntax with worked examples, notes the value-not-resource property of the new types, and cross-links to design/async.md for the underlying motivation. Signed-off-by: Eric Gregory <eric@cosmonic.com>
1 parent 35629a7 commit 424aa10

1 file changed

Lines changed: 64 additions & 0 deletions

File tree

  • component-model/src/design

‎component-model/src/design/wit.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -196,6 +196,54 @@ tuple<u64, string, u64> // An integer, then a string, then an integer
196196

197197
This 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

201249
New 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
393441
A function can be declared inside an [interface](#interfaces),
394442
or 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

398462
An interface is a named set of types and functions,

0 commit comments

Comments
 (0)