Update to v0.2.1

.github/workflows/main.yml

@@ -13,11 +13,12 @@ jobs:
     - uses: actions/checkout@v4
     - name: ensure `./wit/deps` are in sync
       run: |
-        curl -Lo 'wit-deps' https://github.com/bytecodealliance/wit-deps/releases/download/v0.3.3/wit-deps-x86_64-unknown-linux-musl
+        curl -Lo 'wit-deps' https://github.com/bytecodealliance/wit-deps/releases/download/v0.3.5/wit-deps-x86_64-unknown-linux-musl
         chmod +x wit-deps
         ./wit-deps lock
         git add -N wit/deps
         git diff --exit-code
     - uses: WebAssembly/wit-abi-up-to-date@v21
       with:
         features: clocks-timezone
+        wit-bindgen: '0.28.0'

README.md

@@ -21,21 +21,26 @@ WASI clocks must have at least two complete independent implementations.
 
 ## Table of Contents
 
-- [Introduction](#introduction)
-- [Goals](#goals)
-- [Non-goals](#non-goals)
-- [API walk-through](#api-walk-through)
-  - [Use case 1](#use-case-1)
-  - [Use case 2](#use-case-2)
-- [Detailed design discussion](#detailed-design-discussion)
-  - [[Tricky design choice 1]](#tricky-design-choice-1)
-  - [[Tricky design choice 2]](#tricky-design-choice-2)
-- [Considered alternatives](#considered-alternatives)
-  - [[Alternative 1]](#alternative-1)
-  - [[Alternative 2]](#alternative-2)
-- [Stakeholder Interest & Feedback](#stakeholder-interest--feedback)
-- [References & acknowledgements](#references--acknowledgements)
-- [Development](#development)
+- [WASI Clocks](#wasi-clocks)
+    - [Current Phase](#current-phase)
+    - [Champions](#champions)
+    - [Portability Criteria](#portability-criteria)
+  - [Table of Contents](#table-of-contents)
+    - [Introduction](#introduction)
+    - [Goals](#goals)
+    - [Non-goals](#non-goals)
+    - [API walk-through](#api-walk-through)
+      - [Measuring elapsed time](#measuring-elapsed-time)
+      - [Telling the current human time:](#telling-the-current-human-time)
+      - [Retrieving the timezone:](#retrieving-the-timezone)
+    - [Detailed design discussion](#detailed-design-discussion)
+    - [What should the type of a timestamp be?](#what-should-the-type-of-a-timestamp-be)
+    - [Considered alternatives](#considered-alternatives)
+      - [Per-process and per-thread clocks](#per-process-and-per-thread-clocks)
+    - [Stakeholder Interest \& Feedback](#stakeholder-interest--feedback)
+    - [References \& acknowledgements](#references--acknowledgements)
+    - [Development](#development)
+      - [Generating imports.md](#generating-importsmd)
 
 ### Introduction
 

imports.md

@@ -2,14 +2,14 @@
 <ul>
 <li>Imports:
 <ul>
-<li>interface <a href="#wasi_io_poll_0_2_0"><code>wasi:io/[email protected].0</code></a></li>
-<li>interface <a href="#wasi_clocks_monotonic_clock_0_2_0"><code>wasi:clocks/[email protected].0</code></a></li>
-<li>interface <a href="#wasi_clocks_wall_clock_0_2_0"><code>wasi:clocks/[email protected].0</code></a></li>
-<li>interface <a href="#wasi_clocks_timezone_0_2_0"><code>wasi:clocks/[email protected].0</code></a></li>
+<li>interface <a href="#wasi_io_poll_0_2_1"><code>wasi:io/[email protected].1</code></a></li>
+<li>interface <a href="#wasi_clocks_monotonic_clock_0_2_1"><code>wasi:clocks/[email protected].1</code></a></li>
+<li>interface <a href="#wasi_clocks_wall_clock_0_2_1"><code>wasi:clocks/[email protected].1</code></a></li>
+<li>interface <a href="#wasi_clocks_timezone_0_2_1"><code>wasi:clocks/[email protected].1</code></a></li>
 </ul>
 </li>
 </ul>
-<h2><a name="wasi_io_poll_0_2_0"></a>Import interface wasi:io/[email protected].0</h2>
+<h2><a name="wasi_io_poll_0_2_1"></a>Import interface wasi:io/[email protected].1</h2>
 <p>A poll API intended to let users wait for I/O events on multiple handles
 at once.</p>
 <hr />
@@ -43,14 +43,17 @@ containing only this pollable.</p>
 interest, and waits until one or more of the events is ready for I/O.</p>
 <p>The result <code>list&lt;u32&gt;</code> contains one or more indices of handles in the
 argument list that is ready for I/O.</p>
-<p>If the list contains more elements than can be indexed with a <code>u32</code>
-value, this function traps.</p>
+<p>This function traps if either:</p>
+<ul>
+<li>the list is empty, or:</li>
+<li>the list contains more elements than can be indexed with a <code>u32</code> value.</li>
+</ul>
 <p>A timeout can be implemented by adding a pollable from the
 wasi-clocks API to the list.</p>
 <p>This function does not return a <code>result</code>; 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.</p>
+being ready for I/O.</p>
 <h5>Params</h5>
 <ul>
 <li><a name="poll.in"></a><code>in</code>: list&lt;borrow&lt;<a href="#pollable"><a href="#pollable"><code>pollable</code></a></a>&gt;&gt;</li>
@@ -59,7 +62,7 @@ being reaedy for I/O.</p>
 <ul>
 <li><a name="poll.0"></a> list&lt;<code>u32</code>&gt;</li>
 </ul>
-<h2><a name="wasi_clocks_monotonic_clock_0_2_0"></a>Import interface wasi:clocks/[email protected].0</h2>
+<h2><a name="wasi_clocks_monotonic_clock_0_2_1"></a>Import interface wasi:clocks/[email protected].1</h2>
 <p>WASI Monotonic Clock is a clock API intended to let users measure elapsed
 time.</p>
 <p>It is intended to be portable at least between Unix-family platforms and
@@ -118,7 +121,7 @@ elapsed from the time this function is invoked.</p>
 <ul>
 <li><a name="subscribe_duration.0"></a> own&lt;<a href="#pollable"><a href="#pollable"><code>pollable</code></a></a>&gt;</li>
 </ul>
-<h2><a name="wasi_clocks_wall_clock_0_2_0"></a>Import interface wasi:clocks/[email protected].0</h2>
+<h2><a name="wasi_clocks_wall_clock_0_2_1"></a>Import interface wasi:clocks/[email protected].1</h2>
 <p>WASI Wall Clock is a clock API intended to let users query the current
 time. The name &quot;wall&quot; makes an analogy to a &quot;clock on the wall&quot;, which
 is not necessarily monotonic as it may be reset.</p>
@@ -159,7 +162,7 @@ also known as <a href="https://en.wikipedia.org/wiki/Unix_time">Unix Time</a>.</
 <ul>
 <li><a name="resolution.0"></a> <a href="#datetime"><a href="#datetime"><code>datetime</code></a></a></li>
 </ul>
-<h2><a name="wasi_clocks_timezone_0_2_0"></a>Import interface wasi:clocks/[email protected].0</h2>
+<h2><a name="wasi_clocks_timezone_0_2_1"></a>Import interface wasi:clocks/[email protected].1</h2>
 <hr />
 <h3>Types</h3>
 <h4><a name="datetime"></a><code>type datetime</code></h4>

wit/deps.lock

@@ -1,4 +1,4 @@
 [io]
 url = "https://github.com/WebAssembly/wasi-io/archive/main.tar.gz"
-sha256 = "7210e5653539a15478f894d4da24cc69d61924cbcba21d2804d69314a88e5a4c"
-sha512 = "49184a1b0945a889abd52d25271172ed3dc2db6968fcdddb1bab7ee0081f4a3eeee0977ad2291126a37631c0d86eeea75d822fa8af224c422134500bf9f0f2bb"
+sha256 = "2a74bd811adc46b5a0f19827ddbde89870e52b17615f4d0873f06fd977250caf"
+sha512 = "94624f00c66e66203592cee820f80b1ba91ecdb71f682c154f25eaf71f8d8954197dcb64503bc21e72ed5e812af7eae876df47b7eb727b02db3a74a7ce0aefca"

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<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.
+    @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;
     }
 }

wit/deps/io/poll.wit

@@ -1,21 +1,25 @@
-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
       /// blocks until ready.
       ///
       /// This function is equivalent to calling `poll.poll` on a list
       /// containing only this pollable.
+      @since(version = 0.2.0)
       block: func();
     }
 
@@ -27,15 +31,17 @@ interface poll {
     /// 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:
+    /// - 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.
     ///
     /// 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<borrow<pollable>>) -> list<u32>;
 }

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,13 +61,15 @@ 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
         ) -> result<list<u8>, stream-error>;
 
         /// 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,13 +79,15 @@ 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,
         ) -> result<u64, stream-error>;
 
         /// 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<u64, stream-error>;
 
         /// 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<u8>
         ) -> 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<u8>
         ) -> 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,14 +243,15 @@ 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
         ) -> result<_, stream-error>;
 
         /// 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<input-stream>,
@@ -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<input-stream>,

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;
 }