Debian Codegraph @

.cargo/vendor/wasip2/wit/deps/io/streams.wit

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