Struct wasm_streams::readable::ReadableStreamBYOBReader

pub struct ReadableStreamBYOBReader<'stream> { /* private fields */ }

A ReadableStreamBYOBReader that can be used to read chunks from a ReadableStream.

This is returned by the get_byob_reader method.

When the reader is dropped, it automatically releases its lock.

Implementations

impl<'stream> ReadableStreamBYOBReader<'stream>

pub fn as_raw(&self) -> &ReadableStreamBYOBReader

Acquires a reference to the underlying JavaScript reader.

pub async fn closed(&self) -> Result<(), JsValue>

Waits for the stream to become closed.

This returns an error if the stream ever errors, or if the reader’s lock is released before the stream finishes closing.

pub async fn cancel(&mut self) -> Result<(), JsValue>

Cancels the stream, signaling a loss of interest in the stream by a consumer.

Equivalent to ReadableStream.cancel.

pub async fn cancel_with_reason(
    &mut self,
    reason: &JsValue
) -> Result<(), JsValue>

Cancels the stream, signaling a loss of interest in the stream by a consumer.

Equivalent to ReadableStream.cancel_with_reason.

pub async fn read(&mut self, dst: &mut [u8]) -> Result<usize, JsValue>

Reads the next chunk from the stream’s internal queue into dst, and returns the number of bytes read.

• If some bytes were read into dst, this returns Ok(bytes_read).
• If the stream closes and no more bytes are available, this returns Ok(0).
• If the stream cancels, this returns Ok(0).
• If the stream encounters an error, this returns Err(error).

This always allocated a new temporary Uint8Array with the same size as dst to hold the result before copying to dst. We cannot pass a view on the backing WebAssembly memory directly, because:

• reader.read(view) needs to transfer view.buffer, but WebAssembly.Memory buffers are non-transferable.
• view.buffer can be invalidated if the WebAssembly memory grows while read(view) is still in progress.

Therefore, it is necessary to use a separate buffer living in the JavaScript heap. To avoid repeated allocations for repeated reads, use read_with_buffer.

pub async fn read_with_buffer(
    &mut self,
    dst: &mut [u8],
    buffer: Uint8Array
) -> Result<(usize, Option<Uint8Array>), JsValue>

Reads the next chunk from the stream’s internal queue into dst, and returns the number of bytes read.

The given buffer is used to store the bytes before they are copied to dst. This buffer is returned back together with the result, so it can be re-used for subsequent reads without extra allocations. Note that the underlying ArrayBuffer is transferred in the process, so any other views on the original buffer will become unusable.

• If some bytes were read into dst, this returns Ok((bytes_read, Some(buffer))).
• If the stream closes and no more bytes are available, this returns Ok((0, Some(buffer))).
• If the stream cancels, this returns Ok((0, None)). In this case, the given buffer is not returned.
• If the stream encounters an error, this returns Err(error).

pub fn release_lock(self)

Releases this reader’s lock on the corresponding stream.

As of January 2022, the Streams standard allows the lock to be released even when there are still pending read requests. Such requests will automatically become rejected, and this function will always succeed.

However, if the Streams implementation is not yet up-to-date with this change, then releasing the lock while there are pending read requests will panic. For a non-panicking variant, use try_release_lock.

pub fn try_release_lock(self) -> Result<(), (Error, Self)>

Try to release this reader’s lock on the corresponding stream.

As of January 2022, the Streams standard allows the lock to be released even when there are still pending read requests. Such requests will automatically become rejected, and this function will always return Ok(()).

However, if the Streams implementation is not yet up-to-date with this change, then the lock cannot be released while there are pending read requests. Attempting to do so will return an error and leave the reader locked to the stream.

pub fn into_async_read(self) -> IntoAsyncRead<'stream>

Converts this ReadableStreamBYOBReader into an AsyncRead.

This is similar to ReadableStream.into_async_read, except that after the returned AsyncRead is dropped, the original ReadableStream is still usable. This allows reading only a few bytes from the AsyncRead, while still allowing another reader to read the remaining bytes later on.

Trait Implementations

impl<'stream> Debug for ReadableStreamBYOBReader<'stream>

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

Formats the value using the given formatter.

impl Drop for ReadableStreamBYOBReader<'_>

fn drop(&mut self)

Executes the destructor for this type.