@@ -8,20 +8,36 @@ package wasi:io;
88interface streams {
99 use poll . {pollable };
1010
11- /// Streams provide a sequence of data and then end; once they end, they
12- /// no longer provide any further data.
11+ /// An error for input-stream and output-stream operations.
12+ variant stream-error {
13+ /// The last operation (a write or flush) failed before completion.
14+ ///
15+ /// More information is available in the `error` payload.
16+ last-operation-failed (error ),
17+ /// The stream is closed: no more input will be accepted by the
18+ /// stream. A closed output-stream will return this error on all
19+ /// future operations.
20+ closed
21+ }
22+
23+ /// Contextual error information about the last failure that happened on
24+ /// a read, write, or flush from an `input-stream` or `output-stream` .
25+ ///
26+ /// This type is returned through the `stream-error` type whenever an
27+ /// operation on a stream directly fails or an error is discovered
28+ /// after-the-fact, for example when a write's failure shows up through a
29+ /// later `flush` or `check-write` .
1330 ///
14- /// For example, a stream reading from a file ends when the stream reaches
15- /// the end of the file. For another example, a stream reading from a
16- /// socket ends when the socket is closed.
17- enum stream-status {
18- /// The stream is open and may produce further data.
19- open ,
20- /// When reading, this indicates that the stream will not produce
21- /// further data.
22- /// When writing, this indicates that the stream will no longer be read.
23- /// Further writes are still permitted.
24- ended ,
31+ /// Interfaces such as `wasi:filesystem/types` provide functionality to
32+ /// further "downcast" this error into interface-specific error information.
33+ resource error {
34+ /// Returns a string that's suitable to assist humans in debugging this
35+ /// error.
36+ ///
37+ /// The returned string will change across platforms and hosts which
38+ /// means that parsing it, for example, would be a
39+ /// platform-compatibility hazard.
40+ to-debug-string : func () -> string ;
2541 }
2642
2743 /// An input bytestream.
@@ -35,21 +51,20 @@ interface streams {
3551 resource input-stream {
3652 /// Perform a non-blocking read from the stream.
3753 ///
38- /// This function returns a list of bytes containing the data that was
39- /// read, along with a `stream-status` which, indicates whether further
40- /// reads are expected to produce data. The returned list will contain up to
41- /// `len` bytes; it may return fewer than requested, but not more. An
42- /// empty list and `stream-status:open` indicates no more data is
43- /// available at this time, and that the pollable given by `subscribe`
44- /// will be ready when more data is available.
54+ /// This function returns a list of bytes containing the read data,
55+ /// when successful. The returned list will contain up to `len` bytes;
56+ /// it may return fewer than requested, but not more. The list is
57+ /// empty when no bytes are available for reading at this time. The
58+ /// pollable given by `subscribe` will be ready when more bytes are
59+ /// available.
4560 ///
46- /// Once a stream has reached the end, subsequent calls to `read` or
47- /// `skip` will always report `stream-status:ended` rather than producing more
48- /// data .
61+ /// This function fails with a `stream-error` when the operation
62+ /// encounters an error, giving `last-operation-failed` , or when the
63+ /// stream is closed, giving `closed` .
4964 ///
50- /// When the caller gives a `len` of 0, it represents a request to read 0
51- /// bytes. This read should always succeed and return an empty list and
52- /// the current `stream-status `
65+ /// When the caller gives a `len` of 0, it represents a request to
66+ /// read 0 bytes. If the stream is still open, this call should
67+ /// succeed and return an empty list, or otherwise fail with `closed `
5368 ///
5469 /// The `len` parameter is a `u64` , which could represent a list of u8 which
5570 /// is not possible to allocate in wasm32, or not desirable to allocate as
@@ -58,38 +73,30 @@ interface streams {
5873 read : func (
5974 /// The maximum number of bytes to read
6075 len : u64
61- ) -> result <tuple < list <u8 >, stream-status > >;
76+ ) -> result <list <u8 >, stream-error >;
6277
6378 /// Read bytes from a stream, after blocking until at least one byte can
64- /// be read. Except for blocking, identical to `read` .
79+ /// be read. Except for blocking, behavior is identical to `read` .
6580 blocking-read : func (
6681 /// The maximum number of bytes to read
6782 len : u64
68- ) -> result <tuple < list <u8 >, stream-status > >;
83+ ) -> result <list <u8 >, stream-error >;
6984
70- /// Skip bytes from a stream.
85+ /// Skip bytes from a stream. Returns number of bytes skipped.
7186 ///
72- /// This is similar to the `read` function, but avoids copying the
73- /// bytes into the instance.
74- ///
75- /// Once a stream has reached the end, subsequent calls to read or
76- /// `skip` will always report end-of-stream rather than producing more
77- /// data.
78- ///
79- /// This function returns the number of bytes skipped, along with a
80- /// `stream-status` indicating whether the end of the stream was
81- /// reached. The returned value will be at most `len` ; it may be less.
87+ /// Behaves identical to `read` , except instead of returning a list
88+ /// of bytes, returns the number of bytes consumed from the stream.
8289 skip : func (
8390 /// The maximum number of bytes to skip.
8491 len : u64 ,
85- ) -> result <tuple < u64 , stream-status > >;
92+ ) -> result <u64 , stream-error >;
8693
8794 /// Skip bytes from a stream, after blocking until at least one byte
8895 /// can be skipped. Except for blocking behavior, identical to `skip` .
8996 blocking-skip : func (
9097 /// The maximum number of bytes to skip.
9198 len : u64 ,
92- ) -> result <tuple < u64 , stream-status > >;
99+ ) -> result <u64 , stream-error >;
93100
94101 /// Create a `pollable` which will resolve once either the specified stream
95102 /// has bytes available to read or the other end of the stream has been
@@ -100,18 +107,6 @@ interface streams {
100107 subscribe : func () -> pollable ;
101108 }
102109
103- /// An error for output-stream operations.
104- ///
105- /// Contrary to input-streams, a closed output-stream is reported using
106- /// an error.
107- enum write-error {
108- /// The last operation (a write or flush) failed before completion.
109- last-operation-failed ,
110- /// The stream is closed: no more input will be accepted by the
111- /// stream. A closed output-stream will return this error on all
112- /// future operations.
113- closed
114- }
115110
116111 /// An output bytestream.
117112 ///
@@ -131,7 +126,7 @@ interface streams {
131126 /// When this function returns 0 bytes, the `subscribe` pollable will
132127 /// become ready when this function will report at least 1 byte, or an
133128 /// error.
134- check-write : func () -> result <u64 , write -error
129+ check-write : func () -> result <u64 , stream -error
135130
136131 /// Perform a write. This function never blocks.
137132 ///
@@ -142,7 +137,7 @@ interface streams {
142137 /// the last call to check-write provided a permit.
143138 write : func (
144139 contents : list <u8 >
145- ) -> result <_ , write -error
140+ ) -> result <_ , stream -error
146141
147142 /// Perform a write of up to 4096 bytes, and then flush the stream. Block
148143 /// until all of these operations are complete, or an error occurs.
@@ -170,7 +165,7 @@ interface streams {
170165 /// `` `
171166 blocking-write-and-flush : func (
172167 contents : list <u8 >
173- ) -> result <_ , write -error
168+ ) -> result <_ , stream -error
174169
175170 /// Request to flush buffered output. This function never blocks.
176171 ///
@@ -182,11 +177,11 @@ interface streams {
182177 /// writes (`check-write` will return `ok(0)` ) until the flush has
183178 /// completed. The `subscribe` pollable will become ready when the
184179 /// flush has completed and the stream can accept more writes.
185- flush : func () -> result <_ , write -error
180+ flush : func () -> result <_ , stream -error
186181
187182 /// Request to flush buffered output, and block until flush completes
188183 /// and stream is ready for writing again.
189- blocking-flush : func () -> result <_ , write -error
184+ blocking-flush : func () -> result <_ , stream -error
190185
191186 /// Create a `pollable` which will resolve once the output-stream
192187 /// is ready for more writing, or an error has occured. When this
@@ -209,7 +204,7 @@ interface streams {
209204 write-zeroes : func (
210205 /// The number of zero-bytes to write
211206 len : u64
212- ) -> result <_ , write -error
207+ ) -> result <_ , stream -error
213208
214209 /// Perform a write of up to 4096 zeroes, and then flush the stream.
215210 /// Block until all of these operations are complete, or an error
@@ -238,48 +233,38 @@ interface streams {
238233 blocking-write-zeroes-and-flush : func (
239234 /// The number of zero-bytes to write
240235 len : u64
241- ) -> result <_ , write -error
236+ ) -> result <_ , stream -error
242237
243238 /// Read from one stream and write to another.
244239 ///
240+ /// The behavior of splice is equivelant to:
241+ /// 1. calling `check-write` on the `output-stream`
242+ /// 2. calling `read` on the `input-stream` with the smaller of the
243+ /// `check-write` permitted length and the `len` provided to `splice`
244+ /// 3. calling `write` on the `output-stream` with that read data.
245+ ///
246+ /// Any error reported by the call to `check-write` , `read` , or
247+ /// `write` ends the splice and reports that error.
248+ ///
245249 /// This function returns the number of bytes transferred; it may be less
246250 /// than `len` .
247- ///
248- /// Unlike other I/O functions, this function blocks until all the data
249- /// read from the input stream has been written to the output stream.
250251 splice : func (
251252 /// The stream to read from
252- src : input-stream ,
253+ src : borrow < input-stream > ,
253254 /// The number of bytes to splice
254255 len : u64 ,
255- ) -> result <tuple < u64 , stream-status > >;
256+ ) -> result <u64 , stream-error >;
256257
257258 /// Read from one stream and write to another, with blocking.
258259 ///
259- /// This is similar to `splice` , except that it blocks until at least
260- /// one byte can be read.
260+ /// This is similar to `splice` , except that it blocks until the
261+ /// `output-stream` is ready for writing, and the `input-stream`
262+ /// is ready for reading, before performing the `splice` .
261263 blocking-splice : func (
262264 /// The stream to read from
263- src : input-stream ,
265+ src : borrow < input-stream > ,
264266 /// The number of bytes to splice
265267 len : u64 ,
266- ) -> result <tuple <u64 , stream-status >>;
267-
268- /// Forward the entire contents of an input stream to an output stream.
269- ///
270- /// This function repeatedly reads from the input stream and writes
271- /// the data to the output stream, until the end of the input stream
272- /// is reached, or an error is encountered.
273- ///
274- /// Unlike other I/O functions, this function blocks until the end
275- /// of the input stream is seen and all the data has been written to
276- /// the output stream.
277- ///
278- /// This function returns the number of bytes transferred, and the status of
279- /// the output stream.
280- forward : func (
281- /// The stream to read from
282- src : input-stream
283- ) -> result <tuple <u64 , stream-status >>;
268+ ) -> result <u64 , stream-error >;
284269 }
285270}
0 commit comments