Struct wasmcloud_runtime::capability::wrpc::wasi::io::streams::OutputStream
source · pub struct OutputStream(/* private fields */);
Expand description
An output bytestream.
output-stream
s 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§
source§impl OutputStream
impl OutputStream
sourcepub fn check_write<'a, C: Invoke>(
wrpc__: &'a C,
cx__: C::Context,
self_: &'a ResourceBorrow<OutputStream>,
) -> impl Future<Output = Result<Result<u64, StreamError>>> + Send + 'a
pub fn check_write<'a, C: Invoke>( wrpc__: &'a C, cx__: C::Context, self_: &'a ResourceBorrow<OutputStream>, ) -> impl Future<Output = Result<Result<u64, StreamError>>> + Send + 'a
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.
source§impl OutputStream
impl OutputStream
sourcepub fn write<'a, C: Invoke>(
wrpc__: &'a C,
cx__: C::Context,
self_: &'a ResourceBorrow<OutputStream>,
contents: &'a Bytes,
) -> impl Future<Output = Result<Result<(), StreamError>>> + Send + 'a
pub fn write<'a, C: Invoke>( wrpc__: &'a C, cx__: C::Context, self_: &'a ResourceBorrow<OutputStream>, contents: &'a Bytes, ) -> impl Future<Output = Result<Result<(), StreamError>>> + Send + 'a
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.
source§impl OutputStream
impl OutputStream
sourcepub fn blocking_write_and_flush<'a, C: Invoke>(
wrpc__: &'a C,
cx__: C::Context,
self_: &'a ResourceBorrow<OutputStream>,
contents: &'a Bytes,
) -> impl Future<Output = Result<Result<(), StreamError>>> + Send + 'a
pub fn blocking_write_and_flush<'a, C: Invoke>( wrpc__: &'a C, cx__: C::Context, self_: &'a ResourceBorrow<OutputStream>, contents: &'a Bytes, ) -> impl Future<Output = Result<Result<(), StreamError>>> + Send + 'a
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§impl OutputStream
impl OutputStream
sourcepub fn flush<'a, C: Invoke>(
wrpc__: &'a C,
cx__: C::Context,
self_: &'a ResourceBorrow<OutputStream>,
) -> impl Future<Output = Result<Result<(), StreamError>>> + Send + 'a
pub fn flush<'a, C: Invoke>( wrpc__: &'a C, cx__: C::Context, self_: &'a ResourceBorrow<OutputStream>, ) -> impl Future<Output = Result<Result<(), StreamError>>> + Send + 'a
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.
source§impl OutputStream
impl OutputStream
sourcepub fn blocking_flush<'a, C: Invoke>(
wrpc__: &'a C,
cx__: C::Context,
self_: &'a ResourceBorrow<OutputStream>,
) -> impl Future<Output = Result<Result<(), StreamError>>> + Send + 'a
pub fn blocking_flush<'a, C: Invoke>( wrpc__: &'a C, cx__: C::Context, self_: &'a ResourceBorrow<OutputStream>, ) -> impl Future<Output = Result<Result<(), StreamError>>> + Send + 'a
Request to flush buffered output, and block until flush completes and stream is ready for writing again.
source§impl OutputStream
impl OutputStream
sourcepub fn subscribe<'a, C: Invoke>(
wrpc__: &'a C,
cx__: C::Context,
self_: &'a ResourceBorrow<OutputStream>,
) -> impl Future<Output = Result<ResourceOwn<Pollable>>> + Send + 'a
pub fn subscribe<'a, C: Invoke>( wrpc__: &'a C, cx__: C::Context, self_: &'a ResourceBorrow<OutputStream>, ) -> impl Future<Output = Result<ResourceOwn<Pollable>>> + Send + 'a
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 pollable
s created with this function are dropped.
source§impl OutputStream
impl OutputStream
sourcepub fn write_zeroes<'a, C: Invoke>(
wrpc__: &'a C,
cx__: C::Context,
self_: &'a ResourceBorrow<OutputStream>,
len: u64,
) -> impl Future<Output = Result<Result<(), StreamError>>> + Send + 'a
pub fn write_zeroes<'a, C: Invoke>( wrpc__: &'a C, cx__: C::Context, self_: &'a ResourceBorrow<OutputStream>, len: u64, ) -> impl Future<Output = Result<Result<(), StreamError>>> + Send + 'a
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.
source§impl OutputStream
impl OutputStream
sourcepub fn blocking_write_zeroes_and_flush<'a, C: Invoke>(
wrpc__: &'a C,
cx__: C::Context,
self_: &'a ResourceBorrow<OutputStream>,
len: u64,
) -> impl Future<Output = Result<Result<(), StreamError>>> + Send + 'a
pub fn blocking_write_zeroes_and_flush<'a, C: Invoke>( wrpc__: &'a C, cx__: C::Context, self_: &'a ResourceBorrow<OutputStream>, len: u64, ) -> impl Future<Output = Result<Result<(), StreamError>>> + Send + 'a
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§impl OutputStream
impl OutputStream
sourcepub fn splice<'a, C: Invoke>(
wrpc__: &'a C,
cx__: C::Context,
self_: &'a ResourceBorrow<OutputStream>,
src: &'a ResourceBorrow<InputStream>,
len: u64,
) -> impl Future<Output = Result<Result<u64, StreamError>>> + Send + 'a
pub fn splice<'a, C: Invoke>( wrpc__: &'a C, cx__: C::Context, self_: &'a ResourceBorrow<OutputStream>, src: &'a ResourceBorrow<InputStream>, len: u64, ) -> impl Future<Output = Result<Result<u64, StreamError>>> + Send + 'a
Read from one stream and write to another.
The behavior of splice is equivelant to:
- calling
check-write
on theoutput-stream
- calling
read
on theinput-stream
with the smaller of thecheck-write
permitted length and thelen
provided tosplice
- calling
write
on theoutput-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
.
source§impl OutputStream
impl OutputStream
sourcepub fn blocking_splice<'a, C: Invoke>(
wrpc__: &'a C,
cx__: C::Context,
self_: &'a ResourceBorrow<OutputStream>,
src: &'a ResourceBorrow<InputStream>,
len: u64,
) -> impl Future<Output = Result<Result<u64, StreamError>>> + Send + 'a
pub fn blocking_splice<'a, C: Invoke>( wrpc__: &'a C, cx__: C::Context, self_: &'a ResourceBorrow<OutputStream>, src: &'a ResourceBorrow<InputStream>, len: u64, ) -> impl Future<Output = Result<Result<u64, StreamError>>> + Send + 'a
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
.
Auto Trait Implementations§
impl Freeze for OutputStream
impl RefUnwindSafe for OutputStream
impl Send for OutputStream
impl Sync for OutputStream
impl Unpin for OutputStream
impl UnwindSafe for OutputStream
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> GetSetFdFlags for T
impl<T> GetSetFdFlags for T
source§fn get_fd_flags(&self) -> Result<FdFlags, Error>where
T: AsFilelike,
fn get_fd_flags(&self) -> Result<FdFlags, Error>where
T: AsFilelike,
self
file descriptor.source§fn new_set_fd_flags(&self, fd_flags: FdFlags) -> Result<SetFdFlags<T>, Error>where
T: AsFilelike,
fn new_set_fd_flags(&self, fd_flags: FdFlags) -> Result<SetFdFlags<T>, Error>where
T: AsFilelike,
source§fn set_fd_flags(&mut self, set_fd_flags: SetFdFlags<T>) -> Result<(), Error>where
T: AsFilelike,
fn set_fd_flags(&mut self, set_fd_flags: SetFdFlags<T>) -> Result<(), Error>where
T: AsFilelike,
self
file descriptor. Read moresource§impl<T> Instrument for T
impl<T> Instrument for T
source§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
source§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
source§impl<T> IntoEither for T
impl<T> IntoEither for T
source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
self
into a Left
variant of Either<Self, Self>
if into_left
is true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read moresource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
self
into a Left
variant of Either<Self, Self>
if into_left(&self)
returns true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read more