Document per-item versions using @since gates

.github/workflows/main.yml

@@ -11,4 +11,4 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
-    - uses: WebAssembly/wit-abi-up-to-date@v17
+    - uses: WebAssembly/wit-abi-up-to-date@v21

wit/error.wit

@@ -1,6 +1,6 @@
 package wasi:[email protected];
 
-
+@since(version = 0.2.0)
 interface error {
     /// A resource which represents some error information.
     ///
@@ -19,6 +19,7 @@ interface error {
     ///
     /// 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.
@@ -27,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/poll.wit

@@ -2,20 +2,24 @@ package wasi:[email protected];
 
 /// 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();
     }
 
@@ -37,5 +41,6 @@ interface poll {
     /// 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 ready for I/O.
+    @since(version = 0.2.0)
     poll: func(in: list<borrow<pollable>>) -> list<u32>;
 }

wit/streams.wit

@@ -5,11 +5,15 @@ package wasi:[email protected];
 ///
 /// 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,7 @@ 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`.
+    @since(version = 0.2.0)
     resource output-stream {
         /// Check readiness for writing. This function never blocks.
         ///
@@ -112,6 +123,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 +139,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 +168,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,10 +183,12 @@ 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
@@ -193,6 +209,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 +239,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
@@ -240,6 +258,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 +271,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/world.wit

@@ -1,6 +1,10 @@
 package wasi:[email protected];
 
+@since(version = 0.2.0)
 world imports {
+    @since(version = 0.2.0)
     import streams;
+
+    @since(version = 0.2.0)
     import poll;
 }