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