diff --git a/imports.md b/imports.md index 6828e93..dd0c4f2 100644 --- a/imports.md +++ b/imports.md @@ -2,33 +2,31 @@
wasi:io/error@0.2.0
wasi:io/poll@0.2.0
wasi:io/streams@0.2.0
wasi:io/error@0.2.0
wasi:io/poll@0.2.0
wasi:io/streams@0.2.0
resource error
resource error
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>
.
wasi:filesystem/types/filesystem-error-code
, which takes a borrow<error>
+parameter and returns an option<wasi:filesystem/types/error-code>
.
error
into a more
concrete type is open.[method]error.to-debug-string: func
[method]error.to-debug-string: func
Returns a string that is suitable to assist humans in debugging this error.
WARNING: The returned string should not be consumed mechanically! @@ -37,41 +35,41 @@ details. Parsing this string is a major platform-compatibility hazard.
A poll API intended to let users wait for I/O events on multiple handles at once.
resource pollable
resource pollable
pollable
represents a single I/O event which may be ready, or not.[method]pollable.ready: 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.
[method]pollable.block: func
[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.
poll: func
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.
@@ -90,42 +88,42 @@ the pollables has an error, it is indicated by marking the source as being ready 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; when it does, they are expected to subsume this API.
type error
type error
-#### `type pollable` +#### `type pollable` [`pollable`](#pollable)
-#### `variant stream-error` +#### `variant stream-error`
An error for input-stream and output-stream operations.
last-operation-failed
: own<error
>
last-operation-failed
: own<error
>
The last operation (a write or flush) failed before completion.
More information is available in the error
payload.
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.
resource input-stream
resource input-stream
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
@@ -133,7 +131,7 @@ 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
.
resource output-stream
resource output-stream
An output bytestream.
output-stream
s are non-blocking to the extent practical on
underlying platforms. Except where specified otherwise, I/O operations also
@@ -142,7 +140,7 @@ 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
.[method]input-stream.read: func
[method]input-stream.read: func
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
@@ -166,51 +164,51 @@ 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.
self
: borrow<input-stream
>len
: u64
self
: borrow<input-stream
>len
: u64
u8
>, stream-error
>u8
>, stream-error
>[method]input-stream.blocking-read: func
[method]input-stream.blocking-read: func
Read bytes from a stream, after blocking until at least one byte can
be read. Except for blocking, behavior is identical to read
.
self
: borrow<input-stream
>len
: u64
self
: borrow<input-stream
>len
: u64
u8
>, stream-error
>u8
>, stream-error
>[method]input-stream.skip: func
[method]input-stream.skip: func
Skip bytes from a stream. Returns number of bytes skipped.
Behaves identical to read
, except instead of returning a list
of bytes, returns the number of bytes consumed from the stream.
self
: borrow<input-stream
>len
: u64
self
: borrow<input-stream
>len
: u64
u64
, stream-error
>u64
, stream-error
>[method]input-stream.blocking-skip: func
[method]input-stream.blocking-skip: func
Skip bytes from a stream, after blocking until at least one byte
can be skipped. Except for blocking behavior, identical to skip
.
self
: borrow<input-stream
>len
: u64
self
: borrow<input-stream
>len
: u64
u64
, stream-error
>u64
, stream-error
>[method]input-stream.subscribe: func
[method]input-stream.subscribe: func
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
closed.
@@ -219,13 +217,13 @@ Implementations may trap if the input-stream
pollable
s created with this function are dropped.
self
: borrow<input-stream
>self
: borrow<input-stream
>[method]output-stream.check-write: func
[method]output-stream.check-write: func
Check readiness for writing. This function never blocks.
Returns the number of bytes permitted for the next call to write
,
or an error. Calling write
with more bytes than this function has
@@ -235,13 +233,13 @@ become ready when this function will report at least 1 byte, or an
error.
self
: borrow<output-stream
>self
: borrow<output-stream
>u64
, stream-error
>u64
, stream-error
>[method]output-stream.write: func
[method]output-stream.write: func
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
@@ -254,14 +252,14 @@ length of less than or equal to n. Otherwise, this function will trap.
self
: borrow<output-stream
>contents
: list<u8
>self
: borrow<output-stream
>contents
: list<u8
>stream-error
>stream-error
>[method]output-stream.blocking-write-and-flush: func
[method]output-stream.blocking-write-and-flush: func
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.
This is a convenience wrapper around the use of check-write
,
@@ -285,14 +283,14 @@ let _ = this.check-write(); // eliding error handling
self
: borrow<output-stream
>contents
: list<u8
>self
: borrow<output-stream
>contents
: list<u8
>stream-error
>stream-error
>[method]output-stream.flush: func
[method]output-stream.flush: func
Request to flush buffered output. This function never blocks.
This tells the output-stream that the caller intends any buffered
output to be flushed. the output which is expected to be flushed
@@ -303,24 +301,24 @@ completed. The subscribe
pollable will become ready when the
flush has completed and the stream can accept more writes.
self
: borrow<output-stream
>self
: borrow<output-stream
>stream-error
>stream-error
>[method]output-stream.blocking-flush: func
[method]output-stream.blocking-flush: func
Request to flush buffered output, and block until flush completes and stream is ready for writing again.
self
: borrow<output-stream
>self
: borrow<output-stream
>stream-error
>stream-error
>[method]output-stream.subscribe: func
[method]output-stream.subscribe: func
Create a pollable
which will resolve once the output-stream
is ready for more writing, or an error has occured. When this
pollable is ready, check-write
will return ok(n)
with n>0, or an
@@ -331,13 +329,13 @@ Implementations may trap if the output-stream
s created with this function are dropped.pollable
self
: borrow<output-stream
>self
: borrow<output-stream
>[method]output-stream.write-zeroes: func
[method]output-stream.write-zeroes: func
Write zeroes to a stream.
This should be used precisely like write
with the exact same
preconditions (must use check-write first), but instead of
@@ -345,14 +343,14 @@ passing a list of bytes, you simply pass the number of zero-bytes
that should be written.
self
: borrow<output-stream
>len
: u64
self
: borrow<output-stream
>len
: u64
stream-error
>stream-error
>[method]output-stream.blocking-write-zeroes-and-flush: func
[method]output-stream.blocking-write-zeroes-and-flush: func
Perform a write of up to 4096 zeroes, and then flush the stream. Block until all of these operations are complete, or an error occurs.
@@ -376,14 +374,14 @@ let _ = this.check-write(); // eliding error handlingself
: borrow<output-stream
>len
: u64
self
: borrow<output-stream
>len
: u64
stream-error
>stream-error
>[method]output-stream.splice: func
[method]output-stream.splice: func
Read from one stream and write to another.
The behavior of splice is equivelant to:
len
.
self
: borrow<output-stream
>src
: borrow<input-stream
>len
: u64
self
: borrow<output-stream
>src
: borrow<input-stream
>len
: u64
u64
, stream-error
>u64
, stream-error
>[method]output-stream.blocking-splice: func
[method]output-stream.blocking-splice: func
Read from one stream and write to another, with blocking.
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
.
self
: borrow<output-stream
>src
: borrow<input-stream
>len
: u64
self
: borrow<output-stream
>src
: borrow<input-stream
>len
: u64
u64
, stream-error
>u64
, stream-error
>