diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index af3c079..5ca5ba1 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -18,4 +18,4 @@ jobs:
./wit-deps lock
git add -N wit/deps
git diff --exit-code
- - uses: WebAssembly/wit-abi-up-to-date@v16
+ - uses: WebAssembly/wit-abi-up-to-date@v17
diff --git a/imports.md b/imports.md
index a0210f0..78acb2f 100644
--- a/imports.md
+++ b/imports.md
@@ -2,20 +2,34 @@
-
+
Types
-
+A resource which represents some error information.
+The only method provided by this resource is to-debug-string
,
+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, 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>
.
+The set of functions which can "downcast" an error
into a more
+concrete type is open.
Functions
Returns a string that is suitable to assist humans in debugging
@@ -32,13 +46,13 @@ hazard.
-
+
A poll API intended to let users wait for I/O events on multiple handles
at once.
Types
-
+pollable
represents a single I/O event which may be ready, or not.
Functions
Return the readiness of a pollable. This function never blocks.
@@ -82,7 +96,7 @@ being reaedy for I/O.
-
+
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;
@@ -112,11 +126,28 @@ future operations.
+An input bytestream.
+input-stream
s are non-blocking to the extent practical on underlying
+platforms. I/O operations always return promptly; if fewer bytes are
+promptly available than requested, they return the number of bytes promptly
+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
.
-
+An output bytestream.
+output-stream
s are non-blocking to the extent practical on
+underlying platforms. Except where specified otherwise, I/O operations also
+always return promptly, after the number of bytes that can be written
+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
.
Functions
Perform a non-blocking read from the stream.
+When the source of a read
is binary data, the bytes from the source
+are returned verbatim. When the source of a read
is known to the
+implementation to be text, bytes containing the UTF-8 encoding of the
+text are returned.
This function returns a list of bytes containing the read data,
when successful. The returned list will contain up to len
bytes;
it may return fewer than requested, but not more. The list is
@@ -212,6 +243,11 @@ error.
Perform a write. This function never blocks.
+When the destination of a write
is binary data, the bytes from
+contents
are written verbatim. When the destination of a write
is
+known to the implementation to be text, the bytes of contents
are
+transcoded from UTF-8 into the encoding of the destination and then
+written.
Precondition: check-write gave permit of Ok(n) and contents has a
length of less than or equal to n. Otherwise, this function will trap.
returns Err(closed) without writing if the stream has closed since
@@ -234,7 +270,7 @@ following pseudo-code:
let pollable = this.subscribe();
while !contents.is_empty() {
// Wait for the stream to become writable
- poll-one(pollable);
+ pollable.block();
let Ok(n) = this.check-write(); // eliding error handling
let len = min(n, contents.len());
let (chunk, rest) = contents.split_at(len);
@@ -243,7 +279,7 @@ while !contents.is_empty() {
}
this.flush();
// Wait for completion of `flush`
-poll-one(pollable);
+pollable.block();
// Check for any errors that arose during `flush`
let _ = this.check-write(); // eliding error handling
@@ -303,7 +339,7 @@ all derived pollable
s created with this fun
Write zeroes to a stream.
-this should be used precisely like write
with the exact same
+
This should be used precisely like write
with the exact same
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.
@@ -326,7 +362,7 @@ the following pseudo-code:
let pollable = this.subscribe();
while num_zeroes != 0 {
// Wait for the stream to become writable
- poll-one(pollable);
+ pollable.block();
let Ok(n) = this.check-write(); // eliding error handling
let len = min(n, num_zeroes);
this.write-zeroes(len); // eliding error handling
@@ -334,7 +370,7 @@ while num_zeroes != 0 {
}
this.flush();
// Wait for completion of `flush`
-poll-one(pollable);
+pollable.block();
// Check for any errors that arose during `flush`
let _ = this.check-write(); // eliding error handling
@@ -385,7 +421,7 @@ is ready for reading, before performing the splice
.
-
+
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.
@@ -426,7 +462,7 @@ also known as Unix Time.
-
+
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.
@@ -856,8 +892,11 @@ not reuse it thereafter.
+A descriptor is a reference to a filesystem object, which may be a file,
+directory, named pipe, special file, or other object on which filesystem
+calls may be made.
-
+A stream of directory entries.
Functions
Return a stream for reading from a file, if available.
@@ -1303,7 +1342,7 @@ errors are filesystem-related errors.
-
+
Types
diff --git a/wit/deps.lock b/wit/deps.lock
index be53c76..64c71e7 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 = "89da8eca4cd195516574c89c5b3c24a7b5af3ff2565c16753d20d3bdbc5fc60f"
-sha512 = "244079b3f592d58478a97adbd0bee8d49ae9dd1a3e435651ee40997b50da9fe62cfaba7e3ec7f7406d7d0288d278a43a3a0bc5150226ba40ce0f8ac6d33f7ddb"
+sha256 = "468b4d12892fe926b8eb5d398dbf579d566c93231fa44f415440572c695b7613"
+sha512 = "e6b53a07221f1413953c9797c68f08b815fdaebf66419bbc1ea3e8b7dece73731062693634731f311a03957b268cf9cc509c518bd15e513c318aa04a8459b93a"
[io]
url = "https://github.com/WebAssembly/wasi-io/archive/main.tar.gz"
-sha256 = "f2e6127b235c37c06be675a904d6acf08db953ea688d78c42892c6ad3bd194e4"
-sha512 = "32feefbc115c34bf6968cb6e9dc15e755698ee90648e5a5d84448917c36a318bd61b401195eb64330e2475e1d098bfb8dee1440d594a68e0797748762bd84ae5"
+sha256 = "7210e5653539a15478f894d4da24cc69d61924cbcba21d2804d69314a88e5a4c"
+sha512 = "49184a1b0945a889abd52d25271172ed3dc2db6968fcdddb1bab7ee0081f4a3eeee0977ad2291126a37631c0d86eeea75d822fa8af224c422134500bf9f0f2bb"
diff --git a/wit/deps/clocks/monotonic-clock.wit b/wit/deps/clocks/monotonic-clock.wit
index 09ef32c..4e4dc3a 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-rc-2023-11-10;
+package wasi:clocks@0.2.0;
/// WASI Monotonic Clock is a clock API intended to let users measure elapsed
/// time.
///
@@ -10,7 +10,7 @@ package wasi:clocks@0.2.0-rc-2023-11-10;
///
/// It is intended for measuring elapsed time.
interface monotonic-clock {
- use wasi:io/poll@0.2.0-rc-2023-11-10.{pollable};
+ use wasi:io/poll@0.2.0.{pollable};
/// An instant in time, in nanoseconds. An instant is relative to an
/// unspecified initial value, and can only be compared to instances from
diff --git a/wit/deps/clocks/wall-clock.wit b/wit/deps/clocks/wall-clock.wit
index 8abb9a0..440ca0f 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-rc-2023-11-10;
+package wasi:clocks@0.2.0;
/// 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.
diff --git a/wit/deps/clocks/world.wit b/wit/deps/clocks/world.wit
index 8fa080f..c022457 100644
--- a/wit/deps/clocks/world.wit
+++ b/wit/deps/clocks/world.wit
@@ -1,4 +1,4 @@
-package wasi:clocks@0.2.0-rc-2023-11-10;
+package wasi:clocks@0.2.0;
world imports {
import monotonic-clock;
diff --git a/wit/deps/io/error.wit b/wit/deps/io/error.wit
index 31918ac..22e5b64 100644
--- a/wit/deps/io/error.wit
+++ b/wit/deps/io/error.wit
@@ -1,4 +1,4 @@
-package wasi:io@0.2.0-rc-2023-11-10;
+package wasi:io@0.2.0;
interface error {
diff --git a/wit/deps/io/poll.wit b/wit/deps/io/poll.wit
index bddde3c..ddc67f8 100644
--- a/wit/deps/io/poll.wit
+++ b/wit/deps/io/poll.wit
@@ -1,9 +1,9 @@
-package wasi:io@0.2.0-rc-2023-11-10;
+package wasi:io@0.2.0;
/// A poll API intended to let users wait for I/O events on multiple handles
/// at once.
interface poll {
- /// `pollable` epresents a single I/O event which may be ready, or not.
+ /// `pollable` represents a single I/O event which may be ready, or not.
resource pollable {
/// Return the readiness of a pollable. This function never blocks.
diff --git a/wit/deps/io/streams.wit b/wit/deps/io/streams.wit
index e7e1b68..6d2f871 100644
--- a/wit/deps/io/streams.wit
+++ b/wit/deps/io/streams.wit
@@ -1,4 +1,4 @@
-package wasi:io@0.2.0-rc-2023-11-10;
+package wasi:io@0.2.0;
/// WASI I/O is an I/O abstraction API which is currently focused on providing
/// stream types.
@@ -32,6 +32,11 @@ interface streams {
resource input-stream {
/// Perform a non-blocking read from the stream.
///
+ /// When the source of a `read` is binary data, the bytes from the source
+ /// are returned verbatim. When the source of a `read` is known to the
+ /// implementation to be text, bytes containing the UTF-8 encoding of the
+ /// text are returned.
+ ///
/// This function returns a list of bytes containing the read data,
/// when successful. The returned list will contain up to `len` bytes;
/// it may return fewer than requested, but not more. The list is
@@ -111,6 +116,12 @@ interface streams {
/// Perform a write. This function never blocks.
///
+ /// When the destination of a `write` is binary data, the bytes from
+ /// `contents` are written verbatim. When the destination of a `write` is
+ /// known to the implementation to be text, the bytes of `contents` are
+ /// transcoded from UTF-8 into the encoding of the destination and then
+ /// written.
+ ///
/// Precondition: check-write gave permit of Ok(n) and contents has a
/// length of less than or equal to n. Otherwise, this function will trap.
///
@@ -131,7 +142,7 @@ interface streams {
/// let pollable = this.subscribe();
/// while !contents.is_empty() {
/// // Wait for the stream to become writable
- /// poll-one(pollable);
+ /// pollable.block();
/// let Ok(n) = this.check-write(); // eliding error handling
/// let len = min(n, contents.len());
/// let (chunk, rest) = contents.split_at(len);
@@ -140,7 +151,7 @@ interface streams {
/// }
/// this.flush();
/// // Wait for completion of `flush`
- /// poll-one(pollable);
+ /// pollable.block();
/// // Check for any errors that arose during `flush`
/// let _ = this.check-write(); // eliding error handling
/// ```
@@ -178,7 +189,7 @@ interface streams {
/// Write zeroes to a stream.
///
- /// this should be used precisely like `write` with the exact same
+ /// This should be used precisely like `write` with the exact same
/// 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.
@@ -199,7 +210,7 @@ interface streams {
/// let pollable = this.subscribe();
/// while num_zeroes != 0 {
/// // Wait for the stream to become writable
- /// poll-one(pollable);
+ /// pollable.block();
/// let Ok(n) = this.check-write(); // eliding error handling
/// let len = min(n, num_zeroes);
/// this.write-zeroes(len); // eliding error handling
@@ -207,7 +218,7 @@ interface streams {
/// }
/// this.flush();
/// // Wait for completion of `flush`
- /// poll-one(pollable);
+ /// pollable.block();
/// // Check for any errors that arose during `flush`
/// let _ = this.check-write(); // eliding error handling
/// ```
diff --git a/wit/deps/io/world.wit b/wit/deps/io/world.wit
index 8243da2..5f0b43f 100644
--- a/wit/deps/io/world.wit
+++ b/wit/deps/io/world.wit
@@ -1,4 +1,4 @@
-package wasi:io@0.2.0-rc-2023-11-10;
+package wasi:io@0.2.0;
world imports {
import streams;
diff --git a/wit/preopens.wit b/wit/preopens.wit
index 95ec678..da801f6 100644
--- a/wit/preopens.wit
+++ b/wit/preopens.wit
@@ -1,4 +1,4 @@
-package wasi:filesystem@0.2.0-rc-2023-11-10;
+package wasi:filesystem@0.2.0;
interface preopens {
use types.{descriptor};
diff --git a/wit/types.wit b/wit/types.wit
index 059722a..11108fc 100644
--- a/wit/types.wit
+++ b/wit/types.wit
@@ -1,4 +1,4 @@
-package wasi:filesystem@0.2.0-rc-2023-11-10;
+package wasi:filesystem@0.2.0;
/// 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.
@@ -24,8 +24,8 @@ package wasi:filesystem@0.2.0-rc-2023-11-10;
///
/// [WASI filesystem path resolution]: https://github.com/WebAssembly/wasi-filesystem/blob/main/path-resolution.md
interface types {
- use wasi:io/streams@0.2.0-rc-2023-11-10.{input-stream, output-stream, error};
- use wasi:clocks/wall-clock@0.2.0-rc-2023-11-10.{datetime};
+ use wasi:io/streams@0.2.0.{input-stream, output-stream, error};
+ use wasi:clocks/wall-clock@0.2.0.{datetime};
/// File size or length of a region within a file.
type filesize = u64;
diff --git a/wit/world.wit b/wit/world.wit
index 285e0ba..663f579 100644
--- a/wit/world.wit
+++ b/wit/world.wit
@@ -1,4 +1,4 @@
-package wasi:filesystem@0.2.0-rc-2023-11-10;
+package wasi:filesystem@0.2.0;
world imports {
import types;