1
- package wasi : io @ 0.2.0 ;
1
+ package wasi : io @ 0.2.3 ;
2
2
3
3
/// WASI I/O is an I/O abstraction API which is currently focused on providing
4
4
/// stream types.
5
5
///
6
6
/// In the future, the component model is expected to add built-in stream types;
7
7
/// when it does, they are expected to subsume this API.
8
+ @since (version = 0.2.0 )
8
9
interface streams {
10
+ @since (version = 0.2.0 )
9
11
use error . {error };
12
+ @since (version = 0.2.0 )
10
13
use poll . {pollable };
11
14
12
15
/// An error for input-stream and output-stream operations.
16
+ @since (version = 0.2.0 )
13
17
variant stream-error {
14
18
/// The last operation (a write or flush) failed before completion.
15
19
///
16
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` .
17
24
last-operation-failed (error ),
18
25
/// The stream is closed: no more input will be accepted by the
19
26
/// stream. A closed output-stream will return this error on all
@@ -29,6 +36,7 @@ interface streams {
29
36
/// available, which could even be zero. To wait for data to be available,
30
37
/// use the `subscribe` function to obtain a `pollable` which can be polled
31
38
/// for using `wasi:io/poll` .
39
+ @since (version = 0.2.0 )
32
40
resource input-stream {
33
41
/// Perform a non-blocking read from the stream.
34
42
///
@@ -56,13 +64,15 @@ interface streams {
56
64
/// is not possible to allocate in wasm32, or not desirable to allocate as
57
65
/// as a return value by the callee. The callee may return a list of bytes
58
66
/// less than `len` in size while more bytes are available for reading.
67
+ @since (version = 0.2.0 )
59
68
read : func (
60
69
/// The maximum number of bytes to read
61
70
len : u64
62
71
) -> result <list <u8 >, stream-error >;
63
72
64
73
/// Read bytes from a stream, after blocking until at least one byte can
65
74
/// be read. Except for blocking, behavior is identical to `read` .
75
+ @since (version = 0.2.0 )
66
76
blocking-read : func (
67
77
/// The maximum number of bytes to read
68
78
len : u64
@@ -72,13 +82,15 @@ interface streams {
72
82
///
73
83
/// Behaves identical to `read` , except instead of returning a list
74
84
/// of bytes, returns the number of bytes consumed from the stream.
85
+ @since (version = 0.2.0 )
75
86
skip : func (
76
87
/// The maximum number of bytes to skip.
77
88
len : u64 ,
78
89
) -> result <u64 , stream-error >;
79
90
80
91
/// Skip bytes from a stream, after blocking until at least one byte
81
92
/// can be skipped. Except for blocking behavior, identical to `skip` .
93
+ @since (version = 0.2.0 )
82
94
blocking-skip : func (
83
95
/// The maximum number of bytes to skip.
84
96
len : u64 ,
@@ -90,6 +102,7 @@ interface streams {
90
102
/// The created `pollable` is a child resource of the `input-stream` .
91
103
/// Implementations may trap if the `input-stream` is dropped before
92
104
/// all derived `pollable` s created with this function are dropped.
105
+ @since (version = 0.2.0 )
93
106
subscribe : func () -> pollable ;
94
107
}
95
108
@@ -102,6 +115,11 @@ interface streams {
102
115
/// promptly, which could even be zero. To wait for the stream to be ready to
103
116
/// accept data, the `subscribe` function to obtain a `pollable` which can be
104
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 )
105
123
resource output-stream {
106
124
/// Check readiness for writing. This function never blocks.
107
125
///
@@ -112,6 +130,7 @@ interface streams {
112
130
/// When this function returns 0 bytes, the `subscribe` pollable will
113
131
/// become ready when this function will report at least 1 byte, or an
114
132
/// error.
133
+ @since (version = 0.2.0 )
115
134
check-write : func () -> result <u64 , stream-error >;
116
135
117
136
/// Perform a write. This function never blocks.
@@ -127,6 +146,7 @@ interface streams {
127
146
///
128
147
/// returns Err(closed) without writing if the stream has closed since
129
148
/// the last call to check-write provided a permit.
149
+ @since (version = 0.2.0 )
130
150
write : func (
131
151
contents : list <u8 >
132
152
) -> result <_ , stream-error >;
@@ -155,6 +175,7 @@ interface streams {
155
175
/// // Check for any errors that arose during `flush`
156
176
/// let _ = this.check-write(); // eliding error handling
157
177
/// `` `
178
+ @since (version = 0.2.0 )
158
179
blocking-write-and-flush : func (
159
180
contents : list <u8 >
160
181
) -> result <_ , stream-error >;
@@ -169,14 +190,16 @@ interface streams {
169
190
/// writes (`check-write` will return `ok(0)` ) until the flush has
170
191
/// completed. The `subscribe` pollable will become ready when the
171
192
/// flush has completed and the stream can accept more writes.
193
+ @since (version = 0.2.0 )
172
194
flush : func () -> result <_ , stream-error >;
173
195
174
196
/// Request to flush buffered output, and block until flush completes
175
197
/// and stream is ready for writing again.
198
+ @since (version = 0.2.0 )
176
199
blocking-flush : func () -> result <_ , stream-error >;
177
200
178
201
/// Create a `pollable` which will resolve once the output-stream
179
- /// is ready for more writing, or an error has occured . When this
202
+ /// is ready for more writing, or an error has occurred . When this
180
203
/// pollable is ready, `check-write` will return `ok(n)` with n>0, or an
181
204
/// error.
182
205
///
@@ -185,6 +208,7 @@ interface streams {
185
208
/// The created `pollable` is a child resource of the `output-stream` .
186
209
/// Implementations may trap if the `output-stream` is dropped before
187
210
/// all derived `pollable` s created with this function are dropped.
211
+ @since (version = 0.2.0 )
188
212
subscribe : func () -> pollable ;
189
213
190
214
/// Write zeroes to a stream.
@@ -193,6 +217,7 @@ interface streams {
193
217
/// preconditions (must use check-write first), but instead of
194
218
/// passing a list of bytes, you simply pass the number of zero-bytes
195
219
/// that should be written.
220
+ @since (version = 0.2.0 )
196
221
write-zeroes : func (
197
222
/// The number of zero-bytes to write
198
223
len : u64
@@ -222,14 +247,15 @@ interface streams {
222
247
/// // Check for any errors that arose during `flush`
223
248
/// let _ = this.check-write(); // eliding error handling
224
249
/// `` `
250
+ @since (version = 0.2.0 )
225
251
blocking-write-zeroes-and-flush : func (
226
252
/// The number of zero-bytes to write
227
253
len : u64
228
254
) -> result <_ , stream-error >;
229
255
230
256
/// Read from one stream and write to another.
231
257
///
232
- /// The behavior of splice is equivelant to:
258
+ /// The behavior of splice is equivalent to:
233
259
/// 1. calling `check-write` on the `output-stream`
234
260
/// 2. calling `read` on the `input-stream` with the smaller of the
235
261
/// `check-write` permitted length and the `len` provided to `splice`
@@ -240,6 +266,7 @@ interface streams {
240
266
///
241
267
/// This function returns the number of bytes transferred; it may be less
242
268
/// than `len` .
269
+ @since (version = 0.2.0 )
243
270
splice : func (
244
271
/// The stream to read from
245
272
src : borrow <input-stream >,
@@ -252,6 +279,7 @@ interface streams {
252
279
/// This is similar to `splice` , except that it blocks until the
253
280
/// `output-stream` is ready for writing, and the `input-stream`
254
281
/// is ready for reading, before performing the `splice` .
282
+ @since (version = 0.2.0 )
255
283
blocking-splice : func (
256
284
/// The stream to read from
257
285
src : borrow <input-stream >,
0 commit comments