| 1 |
package wasi:[email protected]; |
| 2 |
|
| 3 |
interface error { |
| 4 |
/// A resource which represents some error information. |
| 5 |
/// |
| 6 |
/// The only method provided by this resource is `to-debug-string`, |
| 7 |
/// which provides some human-readable information about the error. |
| 8 |
/// |
| 9 |
/// In the `wasi:io` package, this resource is returned through the |
| 10 |
/// `wasi:io/streams/stream-error` type. |
| 11 |
/// |
| 12 |
/// To provide more specific error information, other interfaces may |
| 13 |
/// provide functions to further "downcast" this error into more specific |
| 14 |
/// error information. For example, `error`s returned in streams derived |
| 15 |
/// from filesystem types to be described using the filesystem's own |
| 16 |
/// error-code type, using the function |
| 17 |
/// `wasi:filesystem/types/filesystem-error-code`, which takes a parameter |
| 18 |
/// `borrow<error>` and returns |
| 19 |
/// `option<wasi:filesystem/types/error-code>`. |
| 20 |
/// |
| 21 |
/// The set of functions which can "downcast" an `error` into a more |
| 22 |
/// concrete type is open. |
| 23 |
resource error { |
| 24 |
/// Returns a string that is suitable to assist humans in debugging |
| 25 |
/// this error. |
| 26 |
/// |
| 27 |
/// WARNING: The returned string should not be consumed mechanically! |
| 28 |
/// It may change across platforms, hosts, or other implementation |
| 29 |
/// details. Parsing this string is a major platform-compatibility |
| 30 |
/// hazard. |
| 31 |
to-debug-string: func() -> string; |
| 32 |
} |
| 33 |
} |
| 34 |
|
| 35 |
/// A poll API intended to let users wait for I/O events on multiple handles |
| 36 |
/// at once. |
| 37 |
interface poll { |
| 38 |
/// `pollable` represents a single I/O event which may be ready, or not. |
| 39 |
resource pollable { |
| 40 |
/// Return the readiness of a pollable. This function never blocks. |
| 41 |
/// |
| 42 |
/// Returns `true` when the pollable is ready, and `false` otherwise. |
| 43 |
ready: func() -> bool; |
| 44 |
/// `block` returns immediately if the pollable is ready, and otherwise |
| 45 |
/// blocks until ready. |
| 46 |
/// |
| 47 |
/// This function is equivalent to calling `poll.poll` on a list |
| 48 |
/// containing only this pollable. |
| 49 |
block: func(); |
| 50 |
} |
| 51 |
|
| 52 |
/// Poll for completion on a set of pollables. |
| 53 |
/// |
| 54 |
/// This function takes a list of pollables, which identify I/O sources of |
| 55 |
/// interest, and waits until one or more of the events is ready for I/O. |
| 56 |
/// |
| 57 |
/// The result `list<u32>` contains one or more indices of handles in the |
| 58 |
/// argument list that is ready for I/O. |
| 59 |
/// |
| 60 |
/// If the list contains more elements than can be indexed with a `u32` |
| 61 |
/// value, this function traps. |
| 62 |
/// |
| 63 |
/// A timeout can be implemented by adding a pollable from the |
| 64 |
/// wasi-clocks API to the list. |
| 65 |
/// |
| 66 |
/// This function does not return a `result`; polling in itself does not |
| 67 |
/// do any I/O so it doesn't fail. If any of the I/O sources identified by |
| 68 |
/// the pollables has an error, it is indicated by marking the source as |
| 69 |
/// being reaedy for I/O. |
| 70 |
poll: func(in: list<borrow<pollable>>) -> list<u32>; |
| 71 |
} |
| 72 |
|
| 73 |
/// WASI I/O is an I/O abstraction API which is currently focused on providing |
| 74 |
/// stream types. |
| 75 |
/// |
| 76 |
/// In the future, the component model is expected to add built-in stream types; |
| 77 |
/// when it does, they are expected to subsume this API. |
| 78 |
interface streams { |
| 79 |
use error.{error}; |
| 80 |
use poll.{pollable}; |
| 81 |
|
| 82 |
/// An error for input-stream and output-stream operations. |
| 83 |
variant stream-error { |
| 84 |
/// The last operation (a write or flush) failed before completion. |
| 85 |
/// |
| 86 |
/// More information is available in the `error` payload. |
| 87 |
last-operation-failed(error), |
| 88 |
/// The stream is closed: no more input will be accepted by the |
| 89 |
/// stream. A closed output-stream will return this error on all |
| 90 |
/// future operations. |
| 91 |
closed, |
| 92 |
} |
| 93 |
|
| 94 |
/// An input bytestream. |
| 95 |
/// |
| 96 |
/// `input-stream`s are *non-blocking* to the extent practical on underlying |
| 97 |
/// platforms. I/O operations always return promptly; if fewer bytes are |
| 98 |
/// promptly available than requested, they return the number of bytes promptly |
| 99 |
/// available, which could even be zero. To wait for data to be available, |
| 100 |
/// use the `subscribe` function to obtain a `pollable` which can be polled |
| 101 |
/// for using `wasi:io/poll`. |
| 102 |
resource input-stream { |
| 103 |
/// Perform a non-blocking read from the stream. |
| 104 |
/// |
| 105 |
/// When the source of a `read` is binary data, the bytes from the source |
| 106 |
/// are returned verbatim. When the source of a `read` is known to the |
| 107 |
/// implementation to be text, bytes containing the UTF-8 encoding of the |
| 108 |
/// text are returned. |
| 109 |
/// |
| 110 |
/// This function returns a list of bytes containing the read data, |
| 111 |
/// when successful. The returned list will contain up to `len` bytes; |
| 112 |
/// it may return fewer than requested, but not more. The list is |
| 113 |
/// empty when no bytes are available for reading at this time. The |
| 114 |
/// pollable given by `subscribe` will be ready when more bytes are |
| 115 |
/// available. |
| 116 |
/// |
| 117 |
/// This function fails with a `stream-error` when the operation |
| 118 |
/// encounters an error, giving `last-operation-failed`, or when the |
| 119 |
/// stream is closed, giving `closed`. |
| 120 |
/// |
| 121 |
/// When the caller gives a `len` of 0, it represents a request to |
| 122 |
/// read 0 bytes. If the stream is still open, this call should |
| 123 |
/// succeed and return an empty list, or otherwise fail with `closed`. |
| 124 |
/// |
| 125 |
/// The `len` parameter is a `u64`, which could represent a list of u8 which |
| 126 |
/// is not possible to allocate in wasm32, or not desirable to allocate as |
| 127 |
/// as a return value by the callee. The callee may return a list of bytes |
| 128 |
/// less than `len` in size while more bytes are available for reading. |
| 129 |
read: func(len: u64) -> result<list<u8>, stream-error>; |
| 130 |
/// Read bytes from a stream, after blocking until at least one byte can |
| 131 |
/// be read. Except for blocking, behavior is identical to `read`. |
| 132 |
blocking-read: func(len: u64) -> result<list<u8>, stream-error>; |
| 133 |
/// Skip bytes from a stream. Returns number of bytes skipped. |
| 134 |
/// |
| 135 |
/// Behaves identical to `read`, except instead of returning a list |
| 136 |
/// of bytes, returns the number of bytes consumed from the stream. |
| 137 |
skip: func(len: u64) -> result<u64, stream-error>; |
| 138 |
/// Skip bytes from a stream, after blocking until at least one byte |
| 139 |
/// can be skipped. Except for blocking behavior, identical to `skip`. |
| 140 |
blocking-skip: func(len: u64) -> result<u64, stream-error>; |
| 141 |
/// Create a `pollable` which will resolve once either the specified stream |
| 142 |
/// has bytes available to read or the other end of the stream has been |
| 143 |
/// closed. |
| 144 |
/// The created `pollable` is a child resource of the `input-stream`. |
| 145 |
/// Implementations may trap if the `input-stream` is dropped before |
| 146 |
/// all derived `pollable`s created with this function are dropped. |
| 147 |
subscribe: func() -> pollable; |
| 148 |
} |
| 149 |
|
| 150 |
/// An output bytestream. |
| 151 |
/// |
| 152 |
/// `output-stream`s are *non-blocking* to the extent practical on |
| 153 |
/// underlying platforms. Except where specified otherwise, I/O operations also |
| 154 |
/// always return promptly, after the number of bytes that can be written |
| 155 |
/// promptly, which could even be zero. To wait for the stream to be ready to |
| 156 |
/// accept data, the `subscribe` function to obtain a `pollable` which can be |
| 157 |
/// polled for using `wasi:io/poll`. |
| 158 |
resource output-stream { |
| 159 |
/// Check readiness for writing. This function never blocks. |
| 160 |
/// |
| 161 |
/// Returns the number of bytes permitted for the next call to `write`, |
| 162 |
/// or an error. Calling `write` with more bytes than this function has |
| 163 |
/// permitted will trap. |
| 164 |
/// |
| 165 |
/// When this function returns 0 bytes, the `subscribe` pollable will |
| 166 |
/// become ready when this function will report at least 1 byte, or an |
| 167 |
/// error. |
| 168 |
check-write: func() -> result<u64, stream-error>; |
| 169 |
/// Perform a write. This function never blocks. |
| 170 |
/// |
| 171 |
/// When the destination of a `write` is binary data, the bytes from |
| 172 |
/// `contents` are written verbatim. When the destination of a `write` is |
| 173 |
/// known to the implementation to be text, the bytes of `contents` are |
| 174 |
/// transcoded from UTF-8 into the encoding of the destination and then |
| 175 |
/// written. |
| 176 |
/// |
| 177 |
/// Precondition: check-write gave permit of Ok(n) and contents has a |
| 178 |
/// length of less than or equal to n. Otherwise, this function will trap. |
| 179 |
/// |
| 180 |
/// returns Err(closed) without writing if the stream has closed since |
| 181 |
/// the last call to check-write provided a permit. |
| 182 |
write: func(contents: list<u8>) -> result<_, stream-error>; |
| 183 |
/// Perform a write of up to 4096 bytes, and then flush the stream. Block |
| 184 |
/// until all of these operations are complete, or an error occurs. |
| 185 |
/// |
| 186 |
/// This is a convenience wrapper around the use of `check-write`, |
| 187 |
/// `subscribe`, `write`, and `flush`, and is implemented with the |
| 188 |
/// following pseudo-code: |
| 189 |
/// |
| 190 |
/// ```text |
| 191 |
/// let pollable = this.subscribe(); |
| 192 |
/// while !contents.is_empty() { |
| 193 |
/// // Wait for the stream to become writable |
| 194 |
/// pollable.block(); |
| 195 |
/// let Ok(n) = this.check-write(); // eliding error handling |
| 196 |
/// let len = min(n, contents.len()); |
| 197 |
/// let (chunk, rest) = contents.split_at(len); |
| 198 |
/// this.write(chunk ); // eliding error handling |
| 199 |
/// contents = rest; |
| 200 |
/// } |
| 201 |
/// this.flush(); |
| 202 |
/// // Wait for completion of `flush` |
| 203 |
/// pollable.block(); |
| 204 |
/// // Check for any errors that arose during `flush` |
| 205 |
/// let _ = this.check-write(); // eliding error handling |
| 206 |
/// ``` |
| 207 |
blocking-write-and-flush: func(contents: list<u8>) -> result<_, stream-error>; |
| 208 |
/// Request to flush buffered output. This function never blocks. |
| 209 |
/// |
| 210 |
/// This tells the output-stream that the caller intends any buffered |
| 211 |
/// output to be flushed. the output which is expected to be flushed |
| 212 |
/// is all that has been passed to `write` prior to this call. |
| 213 |
/// |
| 214 |
/// Upon calling this function, the `output-stream` will not accept any |
| 215 |
/// writes (`check-write` will return `ok(0)`) until the flush has |
| 216 |
/// completed. The `subscribe` pollable will become ready when the |
| 217 |
/// flush has completed and the stream can accept more writes. |
| 218 |
flush: func() -> result<_, stream-error>; |
| 219 |
/// Request to flush buffered output, and block until flush completes |
| 220 |
/// and stream is ready for writing again. |
| 221 |
blocking-flush: func() -> result<_, stream-error>; |
| 222 |
/// Create a `pollable` which will resolve once the output-stream |
| 223 |
/// is ready for more writing, or an error has occured. When this |
| 224 |
/// pollable is ready, `check-write` will return `ok(n)` with n>0, or an |
| 225 |
/// error. |
| 226 |
/// |
| 227 |
/// If the stream is closed, this pollable is always ready immediately. |
| 228 |
/// |
| 229 |
/// The created `pollable` is a child resource of the `output-stream`. |
| 230 |
/// Implementations may trap if the `output-stream` is dropped before |
| 231 |
/// all derived `pollable`s created with this function are dropped. |
| 232 |
subscribe: func() -> pollable; |
| 233 |
/// Write zeroes to a stream. |
| 234 |
/// |
| 235 |
/// This should be used precisely like `write` with the exact same |
| 236 |
/// preconditions (must use check-write first), but instead of |
| 237 |
/// passing a list of bytes, you simply pass the number of zero-bytes |
| 238 |
/// that should be written. |
| 239 |
write-zeroes: func(len: u64) -> result<_, stream-error>; |
| 240 |
/// Perform a write of up to 4096 zeroes, and then flush the stream. |
| 241 |
/// Block until all of these operations are complete, or an error |
| 242 |
/// occurs. |
| 243 |
/// |
| 244 |
/// This is a convenience wrapper around the use of `check-write`, |
| 245 |
/// `subscribe`, `write-zeroes`, and `flush`, and is implemented with |
| 246 |
/// the following pseudo-code: |
| 247 |
/// |
| 248 |
/// ```text |
| 249 |
/// let pollable = this.subscribe(); |
| 250 |
/// while num_zeroes != 0 { |
| 251 |
/// // Wait for the stream to become writable |
| 252 |
/// pollable.block(); |
| 253 |
/// let Ok(n) = this.check-write(); // eliding error handling |
| 254 |
/// let len = min(n, num_zeroes); |
| 255 |
/// this.write-zeroes(len); // eliding error handling |
| 256 |
/// num_zeroes -= len; |
| 257 |
/// } |
| 258 |
/// this.flush(); |
| 259 |
/// // Wait for completion of `flush` |
| 260 |
/// pollable.block(); |
| 261 |
/// // Check for any errors that arose during `flush` |
| 262 |
/// let _ = this.check-write(); // eliding error handling |
| 263 |
/// ``` |
| 264 |
blocking-write-zeroes-and-flush: func(len: u64) -> result<_, stream-error>; |
| 265 |
/// Read from one stream and write to another. |
| 266 |
/// |
| 267 |
/// The behavior of splice is equivelant to: |
| 268 |
/// 1. calling `check-write` on the `output-stream` |
| 269 |
/// 2. calling `read` on the `input-stream` with the smaller of the |
| 270 |
/// `check-write` permitted length and the `len` provided to `splice` |
| 271 |
/// 3. calling `write` on the `output-stream` with that read data. |
| 272 |
/// |
| 273 |
/// Any error reported by the call to `check-write`, `read`, or |
| 274 |
/// `write` ends the splice and reports that error. |
| 275 |
/// |
| 276 |
/// This function returns the number of bytes transferred; it may be less |
| 277 |
/// than `len`. |
| 278 |
splice: func(src: borrow<input-stream>, len: u64) -> result<u64, stream-error>; |
| 279 |
/// Read from one stream and write to another, with blocking. |
| 280 |
/// |
| 281 |
/// This is similar to `splice`, except that it blocks until the |
| 282 |
/// `output-stream` is ready for writing, and the `input-stream` |
| 283 |
/// is ready for reading, before performing the `splice`. |
| 284 |
blocking-splice: func(src: borrow<input-stream>, len: u64) -> result<u64, stream-error>; |
| 285 |
} |
| 286 |
} |
| 287 |
|
| 288 |
world imports { |
| 289 |
import error; |
| 290 |
import poll; |
| 291 |
import streams; |
| 292 |
} |