Debian Codegraph @

wasi/p2/wit/deps/wasi-io-0.2.0/package.wit

raw
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 }