diff --git a/imports.md b/imports.md index 1ae5b12..212cafa 100644 --- a/imports.md +++ b/imports.md @@ -132,12 +132,14 @@ use the subscribe function to obtain a po for using wasi:io/poll.

resource output-stream

An output bytestream.

-

output-streams are non-blocking to the extent practical on +

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.

+polled for using wasi:io/poll.

+

resource future-forward-result

+

Represents a future which may eventually return trailers, or an error.

Functions

[method]input-stream.read: func

Perform a non-blocking read from the stream.

@@ -418,3 +420,56 @@ is ready for reading, before performing the splice.

+

forward: func

+

Continuously read all data from the input stream and write it to the +output stream.

+

Forwarding is done on a background task. The tasks runs until either +stream closes or fails. After that, the streams are dropped and the +returned future is resolved. Dropping the future before it has been +resolved aborts the background task and drops the streams.

+

The future resolves with the reason that caused the forwarding to terminate. +In case one of the streams ended normally, this will be stream-error::closed.

+

This function requires exclusive access to the provided streams, +yet it does not change the ownership structure of them. I.e. they remain +children of their parent resources. If the parents place any lifetimes +restrictions on their children, those continue to apply.

+
Params
+ +
Return values
+ +

[method]future-forward-result.subscribe: func

+

Returns a pollable which becomes ready when either the result is +available. When this pollable is ready, the get method will return +some.

+
Params
+ +
Return values
+ +

[method]future-forward-result.get: func

+

Get the resolved value.

+

Returns:

+ +
Params
+ +
Return values
+ diff --git a/wit/streams.wit b/wit/streams.wit index 6d2f871..df894f1 100644 --- a/wit/streams.wit +++ b/wit/streams.wit @@ -259,4 +259,40 @@ interface streams { len: u64, ) -> result; } + + /// Continuously read all data from the input stream and write it to the + /// output stream. + /// + /// Forwarding is done on a background task. The tasks runs until either + /// stream closes or fails. After that, the streams are dropped and the + /// returned future is resolved. Dropping the future before it has been + /// resolved aborts the background task and drops the streams. + /// + /// The future resolves with the reason that caused the forwarding to terminate. + /// In case one of the streams ended normally, this will be `stream-error::closed`. + /// + /// This function requires exclusive access to the provided streams, + /// yet it does not change the ownership structure of them. I.e. they remain + /// children of their parent resources. If the parents place any lifetimes + /// restrictions on their children, those continue to apply. + forward: func(src: input-stream, dst: output-stream) -> future-forward-result; + + /// Represents a future which may eventually return trailers, or an error. + resource future-forward-result { + /// Returns a pollable which becomes ready when either the result is + /// available. When this pollable is ready, the `get` method will return + /// `some`. + subscribe: func() -> pollable; + + /// Get the resolved value. + /// + /// Returns: + /// - `none`: when the future hasn't resolved yet. Use `subscribe` to wait + /// for its completion. + /// - `some(error(_))`: when the future is resolved, but the result value + /// has already been taken before. + /// - `some(ok(value))`: when the future is ready with a value. This is + /// returned only once. + get: func() -> option>; + } }