Trait wasmtime_wasi::HostOutputStream

source · 
pub trait HostOutputStream: Subscribe {
    // Required methods
    fn write(&mut self, bytes: Bytes) -> StreamResult<()>;
    fn flush(&mut self) -> StreamResult<()>;
    fn check_write(&mut self) -> StreamResult<usize>;

    // Provided methods
    fn blocking_write_and_flush<'life0, 'async_trait>(
        &'life0 mut self,
        bytes: Bytes,
    ) -> Pin<Box<dyn Future<Output = StreamResult<()>> + Send + 'async_trait>>
       where Self: Send + 'async_trait,
             'life0: 'async_trait { ... }
    fn write_zeroes(&mut self, nelem: usize) -> StreamResult<()> { ... }
    fn blocking_write_zeroes_and_flush<'life0, 'async_trait>(
        &'life0 mut self,
        nelem: usize,
    ) -> Pin<Box<dyn Future<Output = StreamResult<()>> + Send + 'async_trait>>
       where Self: Send + 'async_trait,
             'life0: 'async_trait { ... }
    fn write_ready<'life0, 'async_trait>(
        &'life0 mut self,
    ) -> Pin<Box<dyn Future<Output = StreamResult<usize>> + Send + 'async_trait>>
       where Self: Send + 'async_trait,
             'life0: 'async_trait { ... }
    fn cancel<'life0, 'async_trait>(
        &'life0 mut self,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: Send + 'async_trait,
             'life0: 'async_trait { ... }
}
Expand description

Host trait for implementing the wasi:io/streams.output-stream resource: A bytestream which can be written to.

Required Methods§

source

fn write(&mut self, bytes: Bytes) -> StreamResult<()>

Write bytes after obtaining a permit to write those bytes

Prior to calling write the caller must call check_write, which resolves to a non-zero permit

This method must never block. The check_write permit indicates the maximum amount of bytes that are permitted to be written in a single write following the check_write resolution.

§Errors

Returns a StreamError if:

  • stream is closed
  • prior operation (write or flush) failed
  • caller performed an illegal operation (e.g. wrote more bytes than were permitted)
source

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

Trigger a flush of any bytes buffered in this stream implementation.

This method may be called at any time and must never block.

After this method is called, check_write must pend until flush is complete.

When check_write becomes ready after a flush, that guarantees that all prior writes have been flushed from the implementation successfully, or that any error associated with those writes is reported in the return value of flush or check_write

§Errors

Returns a StreamError if:

  • stream is closed
  • prior operation (write or flush) failed
  • caller performed an illegal operation (e.g. wrote more bytes than were permitted)
source

fn check_write(&mut self) -> StreamResult<usize>

Returns the number of bytes that are ready to be written to this stream.

Zero bytes indicates that this stream is not currently ready for writing and ready() must be awaited first.

Note that this method does not block.

§Errors

Returns an StreamError if:

  • stream is closed
  • prior operation (write or flush) failed

Provided Methods§

source

fn blocking_write_and_flush<'life0, 'async_trait>( &'life0 mut self, bytes: Bytes, ) -> Pin<Box<dyn Future<Output = StreamResult<()>> + Send + 'async_trait>>
where Self: Send + 'async_trait, 'life0: 'async_trait,

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
source

fn write_zeroes(&mut self, nelem: usize) -> StreamResult<()>

Repeatedly write a byte to a stream. Important: this write must be non-blocking! Returning an Err which downcasts to a StreamError will be reported to Wasm as the empty error result. Otherwise, errors will trap.

source

fn blocking_write_zeroes_and_flush<'life0, 'async_trait>( &'life0 mut self, nelem: usize, ) -> Pin<Box<dyn Future<Output = StreamResult<()>> + Send + 'async_trait>>
where Self: Send + 'async_trait, 'life0: 'async_trait,

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
source

fn write_ready<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = StreamResult<usize>> + Send + 'async_trait>>
where Self: Send + 'async_trait, 'life0: 'async_trait,

Simultaneously waits for this stream to be writable and then returns how much may be written or the last error that happened.

source

fn cancel<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: Send + 'async_trait, 'life0: 'async_trait,

Cancel any asynchronous work and wait for it to wrap up.

Trait Implementations§

source§

impl Subscribe for Box<dyn HostOutputStream>

source§

fn ready<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

An asynchronous function which resolves when this object’s readiness operation is ready. Read more

Implementors§