Skip to content

Commit

Permalink
wit-deps update (#54)
Browse files Browse the repository at this point in the history 
* wit-deps update

* generate markdown
  • Loading branch information
@pchickey
pchickey authored Nov 1, 2023
1 parent 920b60d commit b1169d7
Show file tree
Hide file tree
Showing 4 changed files with 113 additions and 109 deletions.
34 changes: 23 additions & 11 deletions imports.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,27 @@ at once.</p>
<h4><a name="pollable"><code>resource pollable</code></a></h4>
<hr />
<h3>Functions</h3>
<h4><a name="poll_list"><code>poll-list: func</code></a></h4>
<h4><a name="method_pollable.ready"><code>[method]pollable.ready: func</code></a></h4>
<p>Return the readiness of a pollable. This function never blocks.</p>
<p>Returns <code>true</code> when the pollable is ready, and <code>false</code> otherwise.</p>
<h5>Params</h5>
<ul>
<li><a name="method_pollable.ready.self"><code>self</code></a>: borrow&lt;<a href="#pollable"><a href="#pollable"><code>pollable</code></a></a>&gt;</li>
</ul>
<h5>Return values</h5>
<ul>
<li><a name="method_pollable.ready.0"></a> <code>bool</code></li>
</ul>
<h4><a name="method_pollable.block"><code>[method]pollable.block: func</code></a></h4>
<p><code>block</code> returns immediately if the pollable is ready, and otherwise
blocks until ready.</p>
<p>This function is equivalent to calling <code>poll.poll</code> on a list
containing only this pollable.</p>
<h5>Params</h5>
<ul>
<li><a name="method_pollable.block.self"><code>self</code></a>: borrow&lt;<a href="#pollable"><a href="#pollable"><code>pollable</code></a></a>&gt;</li>
</ul>
<h4><a name="poll"><code>poll: func</code></a></h4>
<p>Poll for completion on a set of pollables.</p>
<p>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.</p>
Expand All @@ -33,19 +53,11 @@ the pollables has an error, it is indicated by marking the source as
being reaedy for I/O.</p>
<h5>Params</h5>
<ul>
<li><a name="poll_list.in"><code>in</code></a>: list&lt;borrow&lt;<a href="#pollable"><a href="#pollable"><code>pollable</code></a></a>&gt;&gt;</li>
<li><a name="poll.in"><code>in</code></a>: list&lt;borrow&lt;<a href="#pollable"><a href="#pollable"><code>pollable</code></a></a>&gt;&gt;</li>
</ul>
<h5>Return values</h5>
<ul>
<li><a name="poll_list.0"></a> list&lt;<code>u32</code>&gt;</li>
</ul>
<h4><a name="poll_one"><code>poll-one: func</code></a></h4>
<p>Poll for completion on a single pollable.</p>
<p>This function is similar to <a href="#poll_list"><code>poll-list</code></a>, but operates on only a single
pollable. When it returns, the handle is ready for I/O.</p>
<h5>Params</h5>
<ul>
<li><a name="poll_one.in"><code>in</code></a>: borrow&lt;<a href="#pollable"><a href="#pollable"><code>pollable</code></a></a>&gt;</li>
<li><a name="poll.0"></a> list&lt;<code>u32</code>&gt;</li>
</ul>
<h2><a name="wasi:clocks_monotonic_clock">Import interface wasi:clocks/monotonic-clock</a></h2>
<p>WASI Monotonic Clock is a clock API intended to let users measure elapsed
Expand Down
4 changes: 2 additions & 2 deletions wit/deps.lock
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
[io]
url = "https://github.com/WebAssembly/wasi-io/archive/main.tar.gz"
sha256 = "a00c29dd57dc224e8ce28b793b19c1b1001dcdbdc229ed451c3df1db91841b34"
sha512 = "8558085eeb5689209101cdfbc9782953d559ad14ce77260fe2f7cc472482d568f65cad9e6a688d40c634c6c54c608f27e27e481633446114d6fdead93d4e34c5"
sha256 = "fb76f4449eea54d06b56fc6a7ca988da51bd84a54d2021cf18da67b5e2c7ebcf"
sha512 = "c005e2a91522958a9537827a49ae344e1cb39d66e85492901a86bcc7e322ba8d0a7f1a02c9b9f840c123b4ad97e297355fac98d4822536d1426d1096dd1d73ac"
25 changes: 16 additions & 9 deletions wit/deps/io/poll.wit
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
///
Expand All @@ -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<borrow<pollable>>) -> list<u32>;

/// 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<pollable>);
poll: func(in: list<borrow<pollable>>) -> list<u32>;
}
159 changes: 72 additions & 87 deletions wit/deps/io/streams.wit
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand All @@ -58,38 +73,30 @@ interface streams {
read: func(
/// The maximum number of bytes to read
len: u64
) -> result<tuple<list<u8>, stream-status>>;
) -> result<list<u8>, 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<tuple<list<u8>, stream-status>>;
) -> result<list<u8>, 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<tuple<u64, stream-status>>;
) -> 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`.
blocking-skip: func(
/// The maximum number of bytes to skip.
len: u64,
) -> result<tuple<u64, stream-status>>;
) -> result<u64, stream-error>;

/// 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
Expand All @@ -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.
///
Expand All @@ -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<u64, write-error>;
check-write: func() -> result<u64, stream-error>;

/// Perform a write. This function never blocks.
///
Expand All @@ -142,7 +137,7 @@ interface streams {
/// the last call to check-write provided a permit.
write: func(
contents: list<u8>
) -> 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.
Expand Down Expand Up @@ -170,7 +165,7 @@ interface streams {
/// ```
blocking-write-and-flush: func(
contents: list<u8>
) -> result<_, write-error>;
) -> result<_, stream-error>;

/// Request to flush buffered output. This function never blocks.
///
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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<input-stream>,
/// The number of bytes to splice
len: u64,
) -> result<tuple<u64, stream-status>>;
) -> result<u64, stream-error>;

/// 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<input-stream>,
/// The number of bytes to splice
len: u64,
) -> result<tuple<u64, stream-status>>;

/// 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<tuple<u64, stream-status>>;
) -> result<u64, stream-error>;
}
}

0 comments on commit b1169d7

Please sign in to comment.