diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index e5a9585..52a7b9e 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -19,3 +19,5 @@ jobs: git add -N wit/deps git diff --exit-code - uses: WebAssembly/wit-abi-up-to-date@v21 + with: + wit-bindgen: '0.28.0' diff --git a/imports.md b/imports.md index f3e9b7b..cede769 100644 --- a/imports.md +++ b/imports.md @@ -2,16 +2,16 @@ -

Import interface wasi:io/error@0.2.0

+

Import interface wasi:io/error@0.2.1

Types

resource error

@@ -21,13 +21,11 @@ which provides some human-readable information about the error.

In the wasi:io package, this resource is returned through the wasi:io/streams/stream-error type.

To provide more specific error information, other interfaces may -provide functions to further "downcast" this error into more specific -error information. For example, errors returned in streams derived -from filesystem types to be described using the filesystem's own -error-code type, using the function -wasi:filesystem/types/filesystem-error-code, which takes a parameter -borrow<error> and returns -option<wasi:filesystem/types/error-code>.

+offer functions to "downcast" this error into more specific types. For example, +errors returned from streams derived from filesystem types can be described using +the filesystem's own error-code type. This is done using the function +wasi:filesystem/types/filesystem-error-code, which takes a borrow<error> +parameter and returns an option<wasi:filesystem/types/error-code>.

The set of functions which can "downcast" an error into a more concrete type is open.

Functions

@@ -46,7 +44,7 @@ hazard.

-

Import interface wasi:io/poll@0.2.0

+

Import interface wasi:io/poll@0.2.1

A poll API intended to let users wait for I/O events on multiple handles at once.

@@ -80,14 +78,17 @@ containing only this pollable.

interest, and waits until one or more of the events is ready for I/O.

The result list<u32> contains one or more indices of handles in the argument list that is ready for I/O.

-

If the list contains more elements than can be indexed with a u32 -value, this function traps.

+

This function traps if either:

+

A timeout can be implemented by adding a pollable from the wasi-clocks API to the list.

This function does not return a result; polling in itself does not do any I/O so it doesn't fail. If any of the I/O sources identified by the pollables has an error, it is indicated by marking the source as -being reaedy for I/O.

+being ready for I/O.

Params

[method]output-stream.subscribe: func

Create a pollable which will resolve once the output-stream -is ready for more writing, or an error has occured. When this +is ready for more writing, or an error has occurred. When this pollable is ready, check-write will return ok(n) with n>0, or an error.

If the stream is closed, this pollable is always ready immediately.

@@ -385,7 +389,7 @@ let _ = this.check-write(); // eliding error handling

[method]output-stream.splice: func

Read from one stream and write to another.

-

The behavior of splice is equivelant to:

+

The behavior of splice is equivalent to:

  1. calling check-write on the output-stream
  2. calling read on the input-stream with the smaller of the @@ -421,7 +425,7 @@ is ready for reading, before performing the splice.

    -

    Import interface wasi:clocks/wall-clock@0.2.0

    +

    Import interface wasi:clocks/wall-clock@0.2.1

    WASI Wall Clock is a clock API intended to let users query the current time. The name "wall" makes an analogy to a "clock on the wall", which is not necessarily monotonic as it may be reset.

    @@ -462,7 +466,7 @@ also known as Unix Time.
  3. datetime
    4. -

    Import interface wasi:filesystem/types@0.2.0

    +

    Import interface wasi:filesystem/types@0.2.1

    WASI filesystem is a filesystem API primarily intended to let users run WASI programs that access their files on their existing filesystems, without significant overhead.

    @@ -1342,7 +1346,7 @@ errors are filesystem-related errors.

    -

    Import interface wasi:filesystem/preopens@0.2.0

    +

    Import interface wasi:filesystem/preopens@0.2.1

    Types

    type descriptor

    diff --git a/wit/deps.lock b/wit/deps.lock index 64c71e7..2b50429 100644 --- a/wit/deps.lock +++ b/wit/deps.lock @@ -1,9 +1,9 @@ [clocks] url = "https://github.com/WebAssembly/wasi-clocks/archive/main.tar.gz" -sha256 = "468b4d12892fe926b8eb5d398dbf579d566c93231fa44f415440572c695b7613" -sha512 = "e6b53a07221f1413953c9797c68f08b815fdaebf66419bbc1ea3e8b7dece73731062693634731f311a03957b268cf9cc509c518bd15e513c318aa04a8459b93a" +sha256 = "ea9d69ee803bc176e23e5268f5e24a2ac485dd1f62a0ab4c748e9d3f901f576f" +sha512 = "5efc22927c46cd56c41e5549ec775561c7fac2ea0d365abc0b55396d9475a7c9f984077a81f84a44a726f1c008fd2fadbffffa4fa53ecd5fbfd05afd379ab428" [io] url = "https://github.com/WebAssembly/wasi-io/archive/main.tar.gz" -sha256 = "7210e5653539a15478f894d4da24cc69d61924cbcba21d2804d69314a88e5a4c" -sha512 = "49184a1b0945a889abd52d25271172ed3dc2db6968fcdddb1bab7ee0081f4a3eeee0977ad2291126a37631c0d86eeea75d822fa8af224c422134500bf9f0f2bb" +sha256 = "2a74bd811adc46b5a0f19827ddbde89870e52b17615f4d0873f06fd977250caf" +sha512 = "94624f00c66e66203592cee820f80b1ba91ecdb71f682c154f25eaf71f8d8954197dcb64503bc21e72ed5e812af7eae876df47b7eb727b02db3a74a7ce0aefca" diff --git a/wit/deps/clocks/monotonic-clock.wit b/wit/deps/clocks/monotonic-clock.wit index 4e4dc3a..3c24840 100644 --- a/wit/deps/clocks/monotonic-clock.wit +++ b/wit/deps/clocks/monotonic-clock.wit @@ -1,4 +1,4 @@ -package wasi:clocks@0.2.0; +package wasi:clocks@0.2.1; /// WASI Monotonic Clock is a clock API intended to let users measure elapsed /// time. /// @@ -7,38 +7,43 @@ package wasi:clocks@0.2.0; /// /// A monotonic clock is a clock which has an unspecified initial value, and /// successive reads of the clock will produce non-decreasing values. -/// -/// It is intended for measuring elapsed time. +@since(version = 0.2.0) interface monotonic-clock { - use wasi:io/poll@0.2.0.{pollable}; + @since(version = 0.2.0) + use wasi:io/poll@0.2.1.{pollable}; /// An instant in time, in nanoseconds. An instant is relative to an /// unspecified initial value, and can only be compared to instances from /// the same monotonic-clock. + @since(version = 0.2.0) type instant = u64; /// A duration of time, in nanoseconds. + @since(version = 0.2.0) type duration = u64; /// Read the current value of the clock. /// /// The clock is monotonic, therefore calling this function repeatedly will /// produce a sequence of non-decreasing values. + @since(version = 0.2.0) now: func() -> instant; /// Query the resolution of the clock. Returns the duration of time /// corresponding to a clock tick. + @since(version = 0.2.0) resolution: func() -> duration; /// Create a `pollable` which will resolve once the specified instant - /// occured. + /// has occurred. + @since(version = 0.2.0) subscribe-instant: func( when: instant, ) -> pollable; - /// Create a `pollable` which will resolve once the given duration has - /// elapsed, starting at the time at which this function was called. - /// occured. + /// Create a `pollable` that will resolve after the specified duration has + /// elapsed from the time this function is invoked. + @since(version = 0.2.0) subscribe-duration: func( when: duration, ) -> pollable; diff --git a/wit/deps/clocks/timezone.wit b/wit/deps/clocks/timezone.wit new file mode 100644 index 0000000..212da66 --- /dev/null +++ b/wit/deps/clocks/timezone.wit @@ -0,0 +1,55 @@ +package wasi:clocks@0.2.1; + +@unstable(feature = clocks-timezone) +interface timezone { + @unstable(feature = clocks-timezone) + use wall-clock.{datetime}; + + /// Return information needed to display the given `datetime`. This includes + /// the UTC offset, the time zone name, and a flag indicating whether + /// daylight saving time is active. + /// + /// If the timezone cannot be determined for the given `datetime`, return a + /// `timezone-display` for `UTC` with a `utc-offset` of 0 and no daylight + /// saving time. + @unstable(feature = clocks-timezone) + display: func(when: datetime) -> timezone-display; + + /// The same as `display`, but only return the UTC offset. + @unstable(feature = clocks-timezone) + utc-offset: func(when: datetime) -> s32; + + /// Information useful for displaying the timezone of a specific `datetime`. + /// + /// This information may vary within a single `timezone` to reflect daylight + /// saving time adjustments. + @unstable(feature = clocks-timezone) + record timezone-display { + /// The number of seconds difference between UTC time and the local + /// time of the timezone. + /// + /// The returned value will always be less than 86400 which is the + /// number of seconds in a day (24*60*60). + /// + /// In implementations that do not expose an actual time zone, this + /// should return 0. + utc-offset: s32, + + /// The abbreviated name of the timezone to display to a user. The name + /// `UTC` indicates Coordinated Universal Time. Otherwise, this should + /// reference local standards for the name of the time zone. + /// + /// In implementations that do not expose an actual time zone, this + /// should be the string `UTC`. + /// + /// In time zones that do not have an applicable name, a formatted + /// representation of the UTC offset may be returned, such as `-04:00`. + name: string, + + /// Whether daylight saving time is active. + /// + /// In implementations that do not expose an actual time zone, this + /// should return false. + in-daylight-saving-time: bool, + } +} diff --git a/wit/deps/clocks/wall-clock.wit b/wit/deps/clocks/wall-clock.wit index 440ca0f..6be069a 100644 --- a/wit/deps/clocks/wall-clock.wit +++ b/wit/deps/clocks/wall-clock.wit @@ -1,4 +1,4 @@ -package wasi:clocks@0.2.0; +package wasi:clocks@0.2.1; /// WASI Wall Clock is a clock API intended to let users query the current /// time. The name "wall" makes an analogy to a "clock on the wall", which /// is not necessarily monotonic as it may be reset. @@ -13,8 +13,10 @@ package wasi:clocks@0.2.0; /// monotonic, making it unsuitable for measuring elapsed time. /// /// It is intended for reporting the current date and time for humans. +@since(version = 0.2.0) interface wall-clock { /// A time and date in seconds plus nanoseconds. + @since(version = 0.2.0) record datetime { seconds: u64, nanoseconds: u32, @@ -33,10 +35,12 @@ interface wall-clock { /// /// [POSIX's Seconds Since the Epoch]: https://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_xbd_chap04.html#tag_21_04_16 /// [Unix Time]: https://en.wikipedia.org/wiki/Unix_time + @since(version = 0.2.0) now: func() -> datetime; /// Query the resolution of the clock. /// /// The nanoseconds field of the output is always less than 1000000000. + @since(version = 0.2.0) resolution: func() -> datetime; } diff --git a/wit/deps/clocks/world.wit b/wit/deps/clocks/world.wit index c022457..9251ac6 100644 --- a/wit/deps/clocks/world.wit +++ b/wit/deps/clocks/world.wit @@ -1,6 +1,11 @@ -package wasi:clocks@0.2.0; +package wasi:clocks@0.2.1; +@since(version = 0.2.0) world imports { + @since(version = 0.2.0) import monotonic-clock; + @since(version = 0.2.0) import wall-clock; + @unstable(feature = clocks-timezone) + import timezone; } diff --git a/wit/deps/io/error.wit b/wit/deps/io/error.wit index 22e5b64..4ea29c4 100644 --- a/wit/deps/io/error.wit +++ b/wit/deps/io/error.wit @@ -1,6 +1,6 @@ -package wasi:io@0.2.0; - +package wasi:io@0.2.1; +@since(version = 0.2.0) interface error { /// A resource which represents some error information. /// @@ -11,16 +11,15 @@ interface error { /// `wasi:io/streams/stream-error` type. /// /// To provide more specific error information, other interfaces may - /// provide functions to further "downcast" this error into more specific - /// error information. For example, `error`s returned in streams derived - /// from filesystem types to be described using the filesystem's own - /// error-code type, using the function - /// `wasi:filesystem/types/filesystem-error-code`, which takes a parameter - /// `borrow` and returns - /// `option`. + /// offer functions to "downcast" this error into more specific types. For example, + /// errors returned from streams derived from filesystem types can be described using + /// the filesystem's own error-code type. This is done using the function + /// `wasi:filesystem/types/filesystem-error-code`, which takes a `borrow` + /// parameter and returns an `option`. /// /// The set of functions which can "downcast" an `error` into a more /// concrete type is open. + @since(version = 0.2.0) resource error { /// Returns a string that is suitable to assist humans in debugging /// this error. @@ -29,6 +28,7 @@ interface error { /// It may change across platforms, hosts, or other implementation /// details. Parsing this string is a major platform-compatibility /// hazard. + @since(version = 0.2.0) to-debug-string: func() -> string; } } diff --git a/wit/deps/io/poll.wit b/wit/deps/io/poll.wit index ddc67f8..b25ac72 100644 --- a/wit/deps/io/poll.wit +++ b/wit/deps/io/poll.wit @@ -1,14 +1,17 @@ -package wasi:io@0.2.0; +package wasi:io@0.2.1; /// A poll API intended to let users wait for I/O events on multiple handles /// at once. +@since(version = 0.2.0) interface poll { /// `pollable` represents a single I/O event which may be ready, or not. + @since(version = 0.2.0) resource pollable { /// Return the readiness of a pollable. This function never blocks. /// /// Returns `true` when the pollable is ready, and `false` otherwise. + @since(version = 0.2.0) ready: func() -> bool; /// `block` returns immediately if the pollable is ready, and otherwise @@ -16,6 +19,7 @@ interface poll { /// /// This function is equivalent to calling `poll.poll` on a list /// containing only this pollable. + @since(version = 0.2.0) block: func(); } @@ -27,8 +31,9 @@ interface poll { /// The result `list` contains one or more indices of handles in the /// argument list that is ready for I/O. /// - /// If the list contains more elements than can be indexed with a `u32` - /// value, this function traps. + /// This function traps if either: + /// - the list is empty, or: + /// - the list contains more elements than can be indexed with a `u32` value. /// /// A timeout can be implemented by adding a pollable from the /// wasi-clocks API to the list. @@ -36,6 +41,7 @@ interface poll { /// This function does not return a `result`; polling in itself does not /// do any I/O so it doesn't fail. If any of the I/O sources identified by /// the pollables has an error, it is indicated by marking the source as - /// being reaedy for I/O. + /// being ready for I/O. + @since(version = 0.2.0) poll: func(in: list>) -> list; } diff --git a/wit/deps/io/streams.wit b/wit/deps/io/streams.wit index 6d2f871..b697e24 100644 --- a/wit/deps/io/streams.wit +++ b/wit/deps/io/streams.wit @@ -1,15 +1,19 @@ -package wasi:io@0.2.0; +package wasi:io@0.2.1; /// WASI I/O is an I/O abstraction API which is currently focused on providing /// stream types. /// /// In the future, the component model is expected to add built-in stream types; /// when it does, they are expected to subsume this API. +@since(version = 0.2.0) interface streams { + @since(version = 0.2.0) use error.{error}; + @since(version = 0.2.0) use poll.{pollable}; /// An error for input-stream and output-stream operations. + @since(version = 0.2.0) variant stream-error { /// The last operation (a write or flush) failed before completion. /// @@ -29,6 +33,7 @@ interface streams { /// available, which could even be zero. To wait for data to be available, /// use the `subscribe` function to obtain a `pollable` which can be polled /// for using `wasi:io/poll`. + @since(version = 0.2.0) resource input-stream { /// Perform a non-blocking read from the stream. /// @@ -56,6 +61,7 @@ interface streams { /// is not possible to allocate in wasm32, or not desirable to allocate as /// as a return value by the callee. The callee may return a list of bytes /// less than `len` in size while more bytes are available for reading. + @since(version = 0.2.0) read: func( /// The maximum number of bytes to read len: u64 @@ -63,6 +69,7 @@ interface streams { /// Read bytes from a stream, after blocking until at least one byte can /// be read. Except for blocking, behavior is identical to `read`. + @since(version = 0.2.0) blocking-read: func( /// The maximum number of bytes to read len: u64 @@ -72,6 +79,7 @@ interface streams { /// /// Behaves identical to `read`, except instead of returning a list /// of bytes, returns the number of bytes consumed from the stream. + @since(version = 0.2.0) skip: func( /// The maximum number of bytes to skip. len: u64, @@ -79,6 +87,7 @@ interface streams { /// Skip bytes from a stream, after blocking until at least one byte /// can be skipped. Except for blocking behavior, identical to `skip`. + @since(version = 0.2.0) blocking-skip: func( /// The maximum number of bytes to skip. len: u64, @@ -90,6 +99,7 @@ interface streams { /// The created `pollable` is a child resource of the `input-stream`. /// Implementations may trap if the `input-stream` is dropped before /// all derived `pollable`s created with this function are dropped. + @since(version = 0.2.0) subscribe: func() -> pollable; } @@ -102,6 +112,11 @@ interface streams { /// promptly, which could even be zero. To wait for the stream to be ready to /// accept data, the `subscribe` function to obtain a `pollable` which can be /// polled for using `wasi:io/poll`. + /// + /// Dropping an `output-stream` while there's still an active write in + /// progress may result in the data being lost. Before dropping the stream, + /// be sure to fully flush your writes. + @since(version = 0.2.0) resource output-stream { /// Check readiness for writing. This function never blocks. /// @@ -112,6 +127,7 @@ interface streams { /// When this function returns 0 bytes, the `subscribe` pollable will /// become ready when this function will report at least 1 byte, or an /// error. + @since(version = 0.2.0) check-write: func() -> result; /// Perform a write. This function never blocks. @@ -127,6 +143,7 @@ interface streams { /// /// returns Err(closed) without writing if the stream has closed since /// the last call to check-write provided a permit. + @since(version = 0.2.0) write: func( contents: list ) -> result<_, stream-error>; @@ -155,6 +172,7 @@ interface streams { /// // Check for any errors that arose during `flush` /// let _ = this.check-write(); // eliding error handling /// ``` + @since(version = 0.2.0) blocking-write-and-flush: func( contents: list ) -> result<_, stream-error>; @@ -169,14 +187,16 @@ interface streams { /// writes (`check-write` will return `ok(0)`) until the flush has /// completed. The `subscribe` pollable will become ready when the /// flush has completed and the stream can accept more writes. + @since(version = 0.2.0) flush: func() -> result<_, stream-error>; /// Request to flush buffered output, and block until flush completes /// and stream is ready for writing again. + @since(version = 0.2.0) blocking-flush: func() -> result<_, stream-error>; /// Create a `pollable` which will resolve once the output-stream - /// is ready for more writing, or an error has occured. When this + /// is ready for more writing, or an error has occurred. When this /// pollable is ready, `check-write` will return `ok(n)` with n>0, or an /// error. /// @@ -193,6 +213,7 @@ interface streams { /// preconditions (must use check-write first), but instead of /// passing a list of bytes, you simply pass the number of zero-bytes /// that should be written. + @since(version = 0.2.0) write-zeroes: func( /// The number of zero-bytes to write len: u64 @@ -222,6 +243,7 @@ interface streams { /// // Check for any errors that arose during `flush` /// let _ = this.check-write(); // eliding error handling /// ``` + @since(version = 0.2.0) blocking-write-zeroes-and-flush: func( /// The number of zero-bytes to write len: u64 @@ -229,7 +251,7 @@ interface streams { /// Read from one stream and write to another. /// - /// The behavior of splice is equivelant to: + /// The behavior of splice is equivalent to: /// 1. calling `check-write` on the `output-stream` /// 2. calling `read` on the `input-stream` with the smaller of the /// `check-write` permitted length and the `len` provided to `splice` @@ -240,6 +262,7 @@ interface streams { /// /// This function returns the number of bytes transferred; it may be less /// than `len`. + @since(version = 0.2.0) splice: func( /// The stream to read from src: borrow, @@ -252,6 +275,7 @@ interface streams { /// This is similar to `splice`, except that it blocks until the /// `output-stream` is ready for writing, and the `input-stream` /// is ready for reading, before performing the `splice`. + @since(version = 0.2.0) blocking-splice: func( /// The stream to read from src: borrow, diff --git a/wit/deps/io/world.wit b/wit/deps/io/world.wit index 5f0b43f..6405a4e 100644 --- a/wit/deps/io/world.wit +++ b/wit/deps/io/world.wit @@ -1,6 +1,10 @@ -package wasi:io@0.2.0; +package wasi:io@0.2.1; +@since(version = 0.2.0) world imports { + @since(version = 0.2.0) import streams; + + @since(version = 0.2.0) import poll; } diff --git a/wit/preopens.wit b/wit/preopens.wit index 08094ab..ca2f726 100644 --- a/wit/preopens.wit +++ b/wit/preopens.wit @@ -1,4 +1,4 @@ -package wasi:filesystem@0.2.0; +package wasi:filesystem@0.2.1; @since(version = 0.2.0) interface preopens { diff --git a/wit/types.wit b/wit/types.wit index d061d5f..db3d968 100644 --- a/wit/types.wit +++ b/wit/types.wit @@ -1,4 +1,4 @@ -package wasi:filesystem@0.2.0; +package wasi:filesystem@0.2.1; /// WASI filesystem is a filesystem API primarily intended to let users run WASI /// programs that access their files on their existing filesystems, without /// significant overhead. @@ -26,9 +26,9 @@ package wasi:filesystem@0.2.0; @since(version = 0.2.0) interface types { @since(version = 0.2.0) - use wasi:io/streams@0.2.0.{input-stream, output-stream, error}; + use wasi:io/streams@0.2.1.{input-stream, output-stream, error}; @since(version = 0.2.0) - use wasi:clocks/wall-clock@0.2.0.{datetime}; + use wasi:clocks/wall-clock@0.2.1.{datetime}; /// File size or length of a region within a file. @since(version = 0.2.0) diff --git a/wit/world.wit b/wit/world.wit index c8d99f5..af0146c 100644 --- a/wit/world.wit +++ b/wit/world.wit @@ -1,4 +1,4 @@ -package wasi:filesystem@0.2.0; +package wasi:filesystem@0.2.1; @since(version = 0.2.0) world imports {