Class ReadableStreamBYOBReader

Namespace

CSharpToJavaScript.APIs.JS

Assembly

CSharpToJavaScript.dll

The ReadableStreamBYOBReader interface of the Streams API defines a reader for a ReadableStream that supports zero-copy reading from an underlying byte source.
It is used for efficient copying from underlying sources where the data is delivered as an "anonymous" sequence of bytes, such as files.

[Value("ReadableStreamBYOBReader")]
public class ReadableStreamBYOBReader

Inheritance

object

ReadableStreamBYOBReader

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

An instance of this reader type should usually be obtained by calling GetReader(ReadableStreamGetReaderOptions) on the stream, specifying mode: "byob" in the options parameter.
The readable stream must have an underlying byte source. In other words, it must have been constructed specifying an underlying source with type: "bytes").

Using this kind of reader, a read() request when the readable stream's internal queues are empty will result in a zero copy transfer from the underlying source (bypassing the stream's internal queues).
If the internal queues are not empty, a read() will satisfy the request from the buffered data.

Note that the methods and properties are similar to those for the default reader (ReadableStreamDefaultReader).
The read() method differs in that it provides a view into which data should be written.

-Streams API concepts
-Using readable byte stream
-ReadableStream
-Web-streams-polyfill

See also on MDN

Constructors

ReadableStreamBYOBReader()

public ReadableStreamBYOBReader()

ReadableStreamBYOBReader(ReadableStream)

The ReadableStreamBYOBReader() constructor creates and returns a ReadableStreamBYOBReader object instance.

public ReadableStreamBYOBReader(ReadableStream stream)

Parameters

stream ReadableStream

Remarks

NOTE

You generally wouldn't use this constructor manually;
instead, you'd use the GetReader(ReadableStreamGetReaderOptions) method with the argument "byob".

-ReadableStreamBYOBReader
-Using readable byte stream

See also on MDN

Methods

Read(Union223, ReadableStreamBYOBReaderReadOptions)

The read() method of the ReadableStreamBYOBReader interface is used to read data into a view on a user-supplied buffer from an associated readable byte stream.
A request for data will be satisfied from the stream's internal queues if there is any data present.
If the stream queues are empty, the request may be supplied as a zero-copy transfer from the underlying byte source.

[Value("read")]
public Task<ReadableStreamReadResult> Read(Union223 view, ReadableStreamBYOBReaderReadOptions options = null)

Parameters

view Union223

options ReadableStreamBYOBReaderReadOptions

Returns

Task<ReadableStreamReadResult>

A Promise, which fulfills/rejects with a result depending on the state of the stream. The result object contains two properties, value and done.The following are possible:

Remarks

The method takes as an argument a view on a buffer that supplied data is to be read into, and returns a Promise.
The promise fulfills with an object that has properties value and done when data comes available, or if the stream is cancelled.
If the stream is errored, the promise will be rejected with the relevant error object.

When a chunk of data is supplied, the value property will contain a new view.
This will be a view over the same buffer/backing memory (and of the same type) as the original view passed to the read() method, now populated with the new chunk of data.
Note that once the promise fulfills, the original view passed to the method will be detached and no longer usable.
The promise will fulfill with a value: undefined if the stream has been cancelled.
In this case the backing memory region of view is discarded and not returned to the caller (all previously read data in the view&apos;s buffer is lost).

The done property indicates whether or not more data is expected.
The value is set true if the stream is closed or cancelled, and false otherwise.

The method also has an optional options.min argument that can be used to specify the minimum number of elements that must be available before the promise will fulfill, while the stream is active.
The view returned in the value property will always have at least this number of elements, except when the stream is closed.

-ReadableStreamBYOBReader(ReadableStream) constructor
-Using readable byte stream

See also on MDN

ReleaseLock()

The releaseLock() method of the ReadableStreamBYOBReader interface releases the reader's lock on the stream.
After the lock is released, the reader is no longer active.

[Value("releaseLock")]
public GlobalObject.Undefined ReleaseLock()

Returns

GlobalObject.Undefined

None (GlobalObject.Undefined).

Remarks

The reader will appear errored if the associated stream is errored when the lock is released; otherwise, the reader will appear closed.

If the reader's lock is released while it still has pending read requests then the promises returned by the reader's Read(Union223, ReadableStreamBYOBReaderReadOptions) method are immediately rejected with a TypeError.
Unread chunks remain in the stream&apos;s internal queue and can be read later by acquiring a new reader.

-ReadableStreamBYOBReader(ReadableStream) constructor
-Using readable byte stream

See also on MDN