diff --git a/imports.md b/imports.md index 75e4834..3f38661 100644 --- a/imports.md +++ b/imports.md @@ -13,7 +13,7 @@ at once.

Types

resource pollable

-

A "pollable" handle.

+

Functions

poll-list: func

Poll for completion on a set of pollables.

@@ -56,14 +56,6 @@ when it does, they are expected to subsume this API.

pollable

#### `resource error` -

Contextual error information about the last failure that happened on -a read, write, or flush from an input-stream or output-stream.

-

This type is returned through the stream-error type whenever an -operation on a stream directly fails or an error is discovered -after-the-fact, for example when a write's failure shows up through a -later flush or check-write.

-

Interfaces such as wasi:filesystem/types provide functionality to -further "downcast" this error into interface-specific error information.

variant stream-error

An error for input-stream and output-stream operations.

Variant Cases
@@ -81,21 +73,8 @@ future operations.

resource input-stream

-

An input bytestream.

-

input-streams are non-blocking to the extent practical on underlying -platforms. I/O operations always return promptly; if fewer bytes are -promptly available than requested, they return the number of bytes promptly -available, which could even be zero. To wait for data to be available, -use the subscribe function to obtain a pollable which can be polled -for using wasi:io/poll.

resource output-stream

-

An output bytestream.

-

output-streams are non-blocking to the extent practical on -underlying platforms. Except where specified otherwise, I/O operations also -always return promptly, after the number of bytes that can be written -promptly, which could even be zero. To wait for the stream to be ready to -accept data, the subscribe function to obtain a pollable which can be -polled for using wasi:io/poll.

+

Functions

[method]error.to-debug-string: func

Returns a string that's suitable to assist humans in debugging this @@ -345,14 +324,21 @@ let _ = this.check-write(); // eliding error handling

[method]output-stream.splice: func

Read from one stream and write to another.

+

The behavior of splice is equivelant to:

+
    +
  1. calling check-write on the output-stream
    2. +
  2. calling read on the input-stream with the smaller of the +check-write permitted length and the len provided to splice
    3. +
  3. calling write on the output-stream with that read data.
    4. +
+

Any error reported by the call to check-write, read, or +write ends the splice and reports that error.

This function returns the number of bytes transferred; it may be less than len.

-

Unlike other I/O functions, this function blocks until all the data -read from the input stream has been written to the output stream.

Params
Return values
@@ -361,34 +347,16 @@ read from the input stream has been written to the output stream.

[method]output-stream.blocking-splice: func

Read from one stream and write to another, with blocking.

-

This is similar to splice, except that it blocks until at least -one byte can be read.

+

This is similar to splice, except that it blocks until the +output-stream is ready for writing, and the input-stream +is ready for reading, before performing the splice.

Params
Return values
-

[method]output-stream.forward: func

-

Forward the entire contents of an input stream to an output stream.

-

This function repeatedly reads from the input stream and writes -the data to the output stream, until the end of the input stream -is reached, or an error is encountered.

-

Unlike other I/O functions, this function blocks until the end -of the input stream is seen and all the data has been written to -the output stream.

-

This function returns the number of bytes transferred, and the status of -the output stream.

-
Params
- -
Return values
- diff --git a/wit/streams.wit b/wit/streams.wit index da87d67..8999b28 100644 --- a/wit/streams.wit +++ b/wit/streams.wit @@ -237,44 +237,34 @@ interface streams { /// Read from one stream and write to another. /// + /// The behavior of splice is equivelant to: + /// 1. calling `check-write` on the `output-stream` + /// 2. calling `read` on the `input-stream` with the smaller of the + /// `check-write` permitted length and the `len` provided to `splice` + /// 3. calling `write` on the `output-stream` with that read data. + /// + /// Any error reported by the call to `check-write`, `read`, or + /// `write` ends the splice and reports that error. + /// /// This function returns the number of bytes transferred; it may be less /// than `len`. - /// - /// Unlike other I/O functions, this function blocks until all the data - /// read from the input stream has been written to the output stream. splice: func( /// The stream to read from - src: input-stream, + src: borrow, /// The number of bytes to splice len: u64, ) -> result; /// Read from one stream and write to another, with blocking. /// - /// This is similar to `splice`, except that it blocks until at least - /// one byte can be read. + /// This is similar to `splice`, except that it blocks until the + /// `output-stream` is ready for writing, and the `input-stream` + /// is ready for reading, before performing the `splice`. blocking-splice: func( /// The stream to read from - src: input-stream, + src: borrow, /// The number of bytes to splice len: u64, ) -> result; - - /// Forward the entire contents of an input stream to an output stream. - /// - /// This function repeatedly reads from the input stream and writes - /// the data to the output stream, until the end of the input stream - /// is reached, or an error is encountered. - /// - /// Unlike other I/O functions, this function blocks until the end - /// of the input stream is seen and all the data has been written to - /// the output stream. - /// - /// This function returns the number of bytes transferred, and the status of - /// the output stream. - forward: func( - /// The stream to read from - src: input-stream - ) -> result; } }