Struct wasi::io::streams::OutputStream

pub struct OutputStream { /* private fields */ }

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.

Implementations

impl OutputStream

pub fn check_write(&self) -> Result<u64, StreamError>

Check readiness for writing. This function never blocks.

Returns the number of bytes permitted for the next call to write, or an error. Calling write with more bytes than this function has permitted will trap.

When this function returns 0 bytes, the subscribe pollable will become ready when this function will report at least 1 byte, or an error.

impl OutputStream

pub fn write(&self, contents: &[u8]) -> Result<(), StreamError>

Perform a write. This function never blocks.

When the destination of a write is binary data, the bytes from contents are written verbatim. When the destination of a write is known to the implementation to be text, the bytes of contents are transcoded from UTF-8 into the encoding of the destination and then written.

Precondition: check-write gave permit of Ok(n) and contents has a length of less than or equal to n. Otherwise, this function will trap.

returns Err(closed) without writing if the stream has closed since the last call to check-write provided a permit.

impl OutputStream

pub fn blocking_write_and_flush( &self, contents: &[u8] ) -> Result<(), StreamError>

Perform a write of up to 4096 bytes, and then flush the stream. Block until all of these operations are complete, or an error occurs.

This is a convenience wrapper around the use of check-write, subscribe, write, and flush, and is implemented with the following pseudo-code:

let pollable = this.subscribe();
while !contents.is_empty() {
// Wait for the stream to become writable
pollable.block();
let Ok(n) = this.check-write(); // eliding error handling
let len = min(n, contents.len());
let (chunk, rest) = contents.split_at(len);
this.write(chunk  );            // eliding error handling
contents = rest;
}
this.flush();
// Wait for completion of `flush`
pollable.block();
// Check for any errors that arose during `flush`
let _ = this.check-write();         // eliding error handling

Examples found in repository

examples/hello-world-no_std.rs (line 3)

fn main() {
    let stdout = wasi::cli::stdout::get_stdout();
    stdout.blocking_write_and_flush(b"Hello, world!\n").unwrap();
}

examples/cli-command-no_std.rs (line 8)

    fn run() -> Result<(), ()> {
        let stdout = wasi::cli::stdout::get_stdout();
        stdout.blocking_write_and_flush(b"Hello, WASI!").unwrap();
        Ok(())
    }

examples/http-proxy-no_std.rs (line 17)

    fn handle(_request: IncomingRequest, response_out: ResponseOutparam) {
        let resp = OutgoingResponse::new(Fields::new());
        let body = resp.body().unwrap();

        ResponseOutparam::set(response_out, Ok(resp));

        let out = body.write().unwrap();
        out.blocking_write_and_flush(b"Hello, WASI!").unwrap();
        drop(out);

        OutgoingBody::finish(body, None).unwrap();
    }

impl OutputStream

pub fn flush(&self) -> Result<(), StreamError>

Request to flush buffered output. This function never blocks.

This tells the output-stream that the caller intends any buffered output to be flushed. the output which is expected to be flushed is all that has been passed to write prior to this call.

Upon calling this function, the output-stream will not accept any writes (check-write will return ok(0)) until the flush has completed. The subscribe pollable will become ready when the flush has completed and the stream can accept more writes.

Examples found in repository

examples/hello-world.rs (line 6)

fn main() {
    let mut stdout = wasi::cli::stdout::get_stdout();
    stdout.write_all(b"Hello, world!\n").unwrap();
    stdout.flush().unwrap();
}

examples/cli-command.rs (line 11)

    fn run() -> Result<(), ()> {
        let mut stdout = wasi::cli::stdout::get_stdout();
        stdout.write_all(b"Hello, WASI!").unwrap();
        stdout.flush().unwrap();
        Ok(())
    }

examples/http-proxy.rs (line 20)

    fn handle(_request: IncomingRequest, response_out: ResponseOutparam) {
        let resp = OutgoingResponse::new(Fields::new());
        let body = resp.body().unwrap();

        ResponseOutparam::set(response_out, Ok(resp));

        let mut out = body.write().unwrap();
        out.write_all(b"Hello, WASI!").unwrap();
        out.flush().unwrap();
        drop(out);

        OutgoingBody::finish(body, None).unwrap();
    }

impl OutputStream

pub fn blocking_flush(&self) -> Result<(), StreamError>

Request to flush buffered output, and block until flush completes and stream is ready for writing again.

impl OutputStream

pub fn subscribe(&self) -> Pollable

Create a pollable which will resolve once the output-stream is ready for more writing, or an error has occured. When this pollable is ready, check-write will return ok(n) with n>0, or an error.

If the stream is closed, this pollable is always ready immediately.

The created pollable is a child resource of the output-stream. Implementations may trap if the output-stream is dropped before all derived pollables created with this function are dropped.

impl OutputStream

pub fn write_zeroes(&self, len: u64) -> Result<(), StreamError>

Write zeroes to a stream.

This should be used precisely like write with the exact same preconditions (must use check-write first), but instead of passing a list of bytes, you simply pass the number of zero-bytes that should be written.

impl OutputStream

pub fn blocking_write_zeroes_and_flush( &self, len: u64 ) -> Result<(), StreamError>

Perform a write of up to 4096 zeroes, and then flush the stream. Block until all of these operations are complete, or an error occurs.

This is a convenience wrapper around the use of check-write, subscribe, write-zeroes, and flush, and is implemented with the following pseudo-code:

let pollable = this.subscribe();
while num_zeroes != 0 {
// Wait for the stream to become writable
pollable.block();
let Ok(n) = this.check-write(); // eliding error handling
let len = min(n, num_zeroes);
this.write-zeroes(len);         // eliding error handling
num_zeroes -= len;
}
this.flush();
// Wait for completion of `flush`
pollable.block();
// Check for any errors that arose during `flush`
let _ = this.check-write();         // eliding error handling

impl OutputStream

pub fn splice(&self, src: &InputStream, len: u64) -> Result<u64, StreamError>

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.

impl OutputStream

pub fn blocking_splice( &self, src: &InputStream, len: u64 ) -> Result<u64, StreamError>

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

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.

Trait Implementations

impl Debug for OutputStream

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Write for OutputStream

fn write(&mut self, buf: &[u8]) -> Result<usize>

Write a buffer into this writer, returning how many bytes were written.

fn flush(&mut self) -> Result<()>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.