diff --git a/imports.md b/imports.md index 1ec1fbe..0581792 100644 --- a/imports.md +++ b/imports.md @@ -17,7 +17,27 @@ at once.

resource pollable

Functions

-

poll-list: func

+

[method]pollable.ready: func

+

Return the readiness of a pollable. This function never blocks.

+

Returns true when the pollable is ready, and false otherwise.

+
Params
+ +
Return values
+ +

[method]pollable.block: func

+

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.

+
Params
+ +

poll: func

Poll for completion on a set of pollables.

This function takes a list of pollables, which identify I/O sources of interest, and waits until one or more of the events is ready for I/O.

@@ -33,19 +53,11 @@ the pollables has an error, it is indicated by marking the source as being reaedy for I/O.

Params
Return values
-

poll-one: func

-

Poll for completion on a single pollable.

-

This function is similar to poll-list, but operates on only a single -pollable. When it returns, the handle is ready for I/O.

-
Params
-

Import interface wasi:clocks/monotonic-clock

WASI Monotonic Clock is a clock API intended to let users measure elapsed diff --git a/wit/deps.lock b/wit/deps.lock index e73913b..472b87f 100644 --- a/wit/deps.lock +++ b/wit/deps.lock @@ -1,4 +1,4 @@ [io] url = "https://github.com/WebAssembly/wasi-io/archive/main.tar.gz" -sha256 = "a00c29dd57dc224e8ce28b793b19c1b1001dcdbdc229ed451c3df1db91841b34" -sha512 = "8558085eeb5689209101cdfbc9782953d559ad14ce77260fe2f7cc472482d568f65cad9e6a688d40c634c6c54c608f27e27e481633446114d6fdead93d4e34c5" +sha256 = "fb76f4449eea54d06b56fc6a7ca988da51bd84a54d2021cf18da67b5e2c7ebcf" +sha512 = "c005e2a91522958a9537827a49ae344e1cb39d66e85492901a86bcc7e322ba8d0a7f1a02c9b9f840c123b4ad97e297355fac98d4822536d1426d1096dd1d73ac" diff --git a/wit/deps/io/poll.wit b/wit/deps/io/poll.wit index 254f534..0829a7d 100644 --- a/wit/deps/io/poll.wit +++ b/wit/deps/io/poll.wit @@ -3,8 +3,21 @@ package wasi:io; /// A poll API intended to let users wait for I/O events on multiple handles /// at once. interface poll { - /// A "pollable" handle. - resource pollable; + /// `pollable` epresents a single I/O event which may be ready, or not. + resource pollable { + + /// Return the readiness of a pollable. This function never blocks. + /// + /// Returns `true` when the pollable is ready, and `false` otherwise. + 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. + block: func(); + } /// Poll for completion on a set of pollables. /// @@ -24,11 +37,5 @@ 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 reaedy for I/O. - poll-list: func(in: list>) -> list; - - /// Poll for completion on a single pollable. - /// - /// This function is similar to `poll-list`, but operates on only a single - /// pollable. When it returns, the handle is ready for I/O. - poll-one: func(in: borrow); + poll: func(in: list>) -> list; } diff --git a/wit/deps/io/streams.wit b/wit/deps/io/streams.wit index cfeab0d..8999b28 100644 --- a/wit/deps/io/streams.wit +++ b/wit/deps/io/streams.wit @@ -8,20 +8,36 @@ package wasi:io; interface streams { use poll.{pollable}; - /// Streams provide a sequence of data and then end; once they end, they - /// no longer provide any further data. + /// An error for input-stream and output-stream operations. + variant stream-error { + /// The last operation (a write or flush) failed before completion. + /// + /// More information is available in the `error` payload. + last-operation-failed(error), + /// The stream is closed: no more input will be accepted by the + /// stream. A closed output-stream will return this error on all + /// future operations. + closed + } + + /// Contextual error information about the last failure that happened on + /// a read, write, or flush from an `input-stream` or `output-stream`. + /// + /// This type is returned through the `stream-error` type whenever an + /// operation on a stream directly fails or an error is discovered + /// after-the-fact, for example when a write's failure shows up through a + /// later `flush` or `check-write`. /// - /// For example, a stream reading from a file ends when the stream reaches - /// the end of the file. For another example, a stream reading from a - /// socket ends when the socket is closed. - enum stream-status { - /// The stream is open and may produce further data. - open, - /// When reading, this indicates that the stream will not produce - /// further data. - /// When writing, this indicates that the stream will no longer be read. - /// Further writes are still permitted. - ended, + /// Interfaces such as `wasi:filesystem/types` provide functionality to + /// further "downcast" this error into interface-specific error information. + resource error { + /// Returns a string that's suitable to assist humans in debugging this + /// error. + /// + /// The returned string will change across platforms and hosts which + /// means that parsing it, for example, would be a + /// platform-compatibility hazard. + to-debug-string: func() -> string; } /// An input bytestream. @@ -35,21 +51,20 @@ interface streams { resource input-stream { /// Perform a non-blocking read from the stream. /// - /// This function returns a list of bytes containing the data that was - /// read, along with a `stream-status` which, indicates whether further - /// reads are expected to produce data. The returned list will contain up to - /// `len` bytes; it may return fewer than requested, but not more. An - /// empty list and `stream-status:open` indicates no more data is - /// available at this time, and that the pollable given by `subscribe` - /// will be ready when more data is available. + /// 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 + /// empty when no bytes are available for reading at this time. The + /// pollable given by `subscribe` will be ready when more bytes are + /// available. /// - /// Once a stream has reached the end, subsequent calls to `read` or - /// `skip` will always report `stream-status:ended` rather than producing more - /// data. + /// This function fails with a `stream-error` when the operation + /// encounters an error, giving `last-operation-failed`, or when the + /// stream is closed, giving `closed`. /// - /// When the caller gives a `len` of 0, it represents a request to read 0 - /// bytes. This read should always succeed and return an empty list and - /// the current `stream-status`. + /// When the caller gives a `len` of 0, it represents a request to + /// read 0 bytes. If the stream is still open, this call should + /// succeed and return an empty list, or otherwise fail with `closed`. /// /// The `len` parameter is a `u64`, which could represent a list of u8 which /// is not possible to allocate in wasm32, or not desirable to allocate as @@ -58,38 +73,30 @@ interface streams { read: func( /// The maximum number of bytes to read len: u64 - ) -> result, stream-status>>; + ) -> result, stream-error>; /// Read bytes from a stream, after blocking until at least one byte can - /// be read. Except for blocking, identical to `read`. + /// be read. Except for blocking, behavior is identical to `read`. blocking-read: func( /// The maximum number of bytes to read len: u64 - ) -> result, stream-status>>; + ) -> result, stream-error>; - /// Skip bytes from a stream. + /// Skip bytes from a stream. Returns number of bytes skipped. /// - /// This is similar to the `read` function, but avoids copying the - /// bytes into the instance. - /// - /// Once a stream has reached the end, subsequent calls to read or - /// `skip` will always report end-of-stream rather than producing more - /// data. - /// - /// This function returns the number of bytes skipped, along with a - /// `stream-status` indicating whether the end of the stream was - /// reached. The returned value will be at most `len`; it may be less. + /// Behaves identical to `read`, except instead of returning a list + /// of bytes, returns the number of bytes consumed from the stream. skip: func( /// The maximum number of bytes to skip. len: u64, - ) -> result>; + ) -> result; /// Skip bytes from a stream, after blocking until at least one byte /// can be skipped. Except for blocking behavior, identical to `skip`. blocking-skip: func( /// The maximum number of bytes to skip. len: u64, - ) -> result>; + ) -> result; /// Create a `pollable` which will resolve once either the specified stream /// has bytes available to read or the other end of the stream has been @@ -100,18 +107,6 @@ interface streams { subscribe: func() -> pollable; } - /// An error for output-stream operations. - /// - /// Contrary to input-streams, a closed output-stream is reported using - /// an error. - enum write-error { - /// The last operation (a write or flush) failed before completion. - last-operation-failed, - /// The stream is closed: no more input will be accepted by the - /// stream. A closed output-stream will return this error on all - /// future operations. - closed - } /// An output bytestream. /// @@ -131,7 +126,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. - check-write: func() -> result; + check-write: func() -> result; /// Perform a write. This function never blocks. /// @@ -142,7 +137,7 @@ interface streams { /// the last call to check-write provided a permit. write: func( contents: list - ) -> result<_, write-error>; + ) -> result<_, stream-error>; /// Perform a write of up to 4096 bytes, and then flush the stream. Block /// until all of these operations are complete, or an error occurs. @@ -170,7 +165,7 @@ interface streams { /// ``` blocking-write-and-flush: func( contents: list - ) -> result<_, write-error>; + ) -> result<_, stream-error>; /// Request to flush buffered output. This function never blocks. /// @@ -182,11 +177,11 @@ 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. - flush: func() -> result<_, write-error>; + flush: func() -> result<_, stream-error>; /// Request to flush buffered output, and block until flush completes /// and stream is ready for writing again. - blocking-flush: func() -> result<_, write-error>; + 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 @@ -209,7 +204,7 @@ interface streams { write-zeroes: func( /// The number of zero-bytes to write len: u64 - ) -> result<_, write-error>; + ) -> result<_, stream-error>; /// Perform a write of up to 4096 zeroes, and then flush the stream. /// Block until all of these operations are complete, or an error @@ -238,48 +233,38 @@ interface streams { blocking-write-zeroes-and-flush: func( /// The number of zero-bytes to write len: u64 - ) -> result<_, write-error>; + ) -> result<_, stream-error>; /// Read from one stream and write to another. /// + /// The behavior of splice is equivelant 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` + /// 3. calling `write` on the `output-stream` with that read data. + /// + /// Any error reported by the call to `check-write`, `read`, or + /// `write` ends the splice and reports that error. + /// /// This function returns the number of bytes transferred; it may be less /// than `len`. - /// - /// Unlike other I/O functions, this function blocks until all the data - /// read from the input stream has been written to the output stream. splice: func( /// The stream to read from - src: input-stream, + src: borrow, /// The number of bytes to splice len: u64, - ) -> result>; + ) -> result; /// Read from one stream and write to another, with blocking. /// - /// This is similar to `splice`, except that it blocks until at least - /// one byte can be read. + /// 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`. blocking-splice: func( /// The stream to read from - src: input-stream, + src: borrow, /// The number of bytes to splice len: u64, - ) -> result>; - - /// Forward the entire contents of an input stream to an output stream. - /// - /// This function repeatedly reads from the input stream and writes - /// the data to the output stream, until the end of the input stream - /// is reached, or an error is encountered. - /// - /// Unlike other I/O functions, this function blocks until the end - /// of the input stream is seen and all the data has been written to - /// the output stream. - /// - /// This function returns the number of bytes transferred, and the status of - /// the output stream. - forward: func( - /// The stream to read from - src: input-stream - ) -> result>; + ) -> result; } }