Skip to content

Latest commit

 

History

History
158 lines (115 loc) · 4.96 KB

WitInWasi.md

File metadata and controls

158 lines (115 loc) · 4.96 KB
Raw

Wit in WASI

Starting in Preview2, WASI APIs are defined using the Wit IDL.

To set up a git repository, start by cloning the wasi-proposal-template, renaming the wit file, and adding content and new files as needed.

Conventions

Getters

TODO: Should we have a recommendation for whether to say get- or not? Or maybe even build a concept of getters into wit itself?

Temporary workarounds

The component model specification and implementations are still in development, so at this time some features or planned features in the component model are not ready for use in WASI APIs. Here's a list of those features and what to use for now in their place.

Resources

Resources are expected to be available in time for Preview2, but at this time still in development.

As a temporary workaround, WASI proposals are using u32 types, which represent indices into an implied global table of handles. Since it is implied and global, this table doesn't provide any isolation between components; it intended to be a temporary workaround to support prototyping.

In place of a resource like this:

/// An example resource.
///
/// A description of the example resource.
resource resource-name {
   /// An example function.
   ///
   /// A description of the example function.
   function-name: func()
}

Define a u32 type alias, an explicit drop function, and change all functions inside the resource to have an explicit this argument, like this:

    /// An example resource.
    ///
    /// A description of the example resource.
    ///
    /// This [represents a resource](https://github.com/WebAssembly/WASI/blob/main/docs/WitInWasi.md#Resources).
    type resource-name = 32

    /// An example function.
    ///
    /// A description of the example function.
    function-name: func(this: resource-name)

    /// Dispose of the specified `resource-name`, after which it may no longer
    /// be used.
    drop-resource-name: func(this: resource-name)

Streams

Streams are expected to be available in the Preview 3 timeframe, as part of the Component Model async proposal.

As a temporary workaround for use cases that need byte streams, use the input-stream and output-stream types defined in wasi-io.

use io.streams.{input-stream, output-stream}

For use cases that need typed streams, another option is to define a resource with a function returning option<T> or result<option<T>, E> for returning the elements with none indicating the end of the stream.

This resource-based workaround can be used for asynchronous I/O by using wasi-poll to poll for multiple streams, however it doesn't support composing asynchronous work across multiple components, and it has some scaling limitations. These limitations will be fixed when built in stream types are available.

Value Imports

As a temporary workaround for the lack of value imports, link-time authority functions may be used.

In place of a value import like this:

    /// An example value import.
    /// 
    /// A description of the value import.
    values: list<i32>

Define an instance function, like this:

    /// An example value import.
    /// 
    /// A description of the value import.
    /// 
    /// This [represents a value import](https://github.com/WebAssembly/WASI/blob/main/docs/WitInWasi.md#Value_Imports).
    instance-values: func() -> list<u32>

If the value type contains any handles, for now specify that calling the function more than once creates new handles each time.

It is often desirable to put these functions in their own interface, so that worlds may chose to include or exclude them independently of the rest of the APIs they're associated with.

Star Imports

TODO: Are there specific patterns we should recommend for working around star imports?

And add this comment:

    /// This [represents a star import](https://github.com/WebAssembly/WASI/blob/main/WasiWitdocs/WitInWasi.md#Star_Imports).

To avoid trouble when migrating to star imports in the future, also avoid depending on dynamic keys.

Dependencies

To use types from one package in another, use a use declaration:

use io.streams.{input-stream, output-stream}

For now, the tooling requires the wit files defining types to be colocated with the wit files using them. The convention for now is to have a "deps" directory underneath the top-level "wit" directory containing copies of any needed wit files.

In the future, wit is expected to support an identifier syntax for naming types in other packages.