Class ReadableByteStreamController

Namespace

CSharpToJavaScript.APIs.JS

Assembly

CSharpToJavaScript.dll

The ReadableByteStreamController interface of the Streams API represents a controller for a readable byte stream.
It allows control of the state and internal queue of a ReadableStream with an underlying byte source, and enables efficient zero-copy transfer of data from the underlying source to a consumer when the stream's internal queue is empty.

[Value("ReadableByteStreamController")]
public class ReadableByteStreamController

Inheritance

object

ReadableByteStreamController

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 controller type is created if an underlyingSource object with the property type="bytes" is passed as an argument to the ReadableStream() constructor.
The underlyingSource object may also define start() and pull() callback functions.
These are called with the controller as a parameter, in order to set up the underlying source, and request data when needed.

The underlying source uses the controller to supply data to the stream via its byobRequest property or enqueue() method.
byobRequest is a ReadableStreamBYOBRequest object that represents a pending request from a consumer to make a zero-copy transfer of data direct to a consumer.
byobRequest must be used to copy data if it exists (do not use enqueue() in this case)!
If the underlying source needs to pass data to the stream and byobRequest is null then the source can call enqueue() to add the data to the stream's internal queues.

Note that the byobRequest is only created in "BYOB mode" when there is a request from a reader and the stream's internal queue is empty.
"BYOB mode" is enabled when using a ReadableStreamBYOBReader (typically constructed by calling GetReader(ReadableStreamGetReaderOptions) with the argument { mode: 'byob' }).
It is also enabled when using a default reader and autoAllocateChunkSize is specified in the ReadableStream() constructor.

An underlying byte source can also use the controller to close() the stream when all the data has been sent and report errors from the underlying source using error().
The controller's desiredSize property is used to apply "backpressure", informing the underlying source of the size of the internal queue (small values indicate that the queue is filling up, hinting to the underlying source that it is be desirable to pause or throttle the inflow).

Note that even though the controller is primarily used by the underlying byte source, there is no reason it cannot be stored used by other parts of the system to signal the stream.

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

See also on MDN

Constructors

ReadableByteStreamController()

public ReadableByteStreamController()

Properties

ByobRequest

The byobRequest read-only property of the ReadableByteStreamController interface returns the current BYOB request, or null if there are no pending requests.

[Value("byobRequest")]
public ReadableStreamBYOBRequest? ByobRequest { get; }

Property Value

ReadableStreamBYOBRequest

A ReadableStreamBYOBRequest object instance, or null.

Remarks

An underlying byte source should check this property, and use it to write data to the stream if it exists (rather than using Enqueue(Union223)).
This will result in an efficient zero-byte transfer of the data to the consumer.

-Using readable byte streams
-ReadableByteStreamController

See also on MDN

DesiredSize

The desiredSize read-only property of the ReadableByteStreamController interface returns the number of bytes required to fill the stream's internal queue to its "desired size".

[Value("desiredSize")]
public double? DesiredSize { get; }

Property Value

double?

An integer. Note that this can be negative if the queue is over-full.The value will be null if the stream has errored and 0 if it is closed.

Remarks

The value is used by the stream to indicate a preferred flow rate to the underlying source.
Sources that support throttling or pausing their inflow of data (not all do!) should control the inflow such that desiredSize of the stream buffer is kept positive and as close to zero as possible.

The desiredSize is used to apply backpressure from downstream consumers.

-Using readable byte streams
-ReadableByteStreamController

See also on MDN

Methods

Close()

The close() method of the ReadableByteStreamController interface closes the associated stream.

[Value("close")]
public GlobalObject.Undefined Close()

Returns

GlobalObject.Undefined

None (GlobalObject.Undefined).

Remarks

This might be called by the underlying source when its data source has been exhausted/completed.

NOTE

Readers will still be able to read any previously-enqueued chunks from the stream, but once those are read, the stream will become closed.
However if there is an outstanding and partially written ByobRequest when close() is called, the stream will be errored.

-Using readable byte streams
-ReadableByteStreamController

See also on MDN

Enqueue(Union223)

The enqueue() method of the ReadableByteStreamController interface enqueues a given chunk on the associated readable byte stream (the chunk is transferred into the stream's internal queues).

[Value("enqueue")]
public GlobalObject.Undefined Enqueue(Union223 chunk)

Parameters

chunk Union223

Returns

GlobalObject.Undefined

None (GlobalObject.Undefined).

Remarks

This should only be used to transfer data to the queue when ByobRequest is null.

-Using readable byte streams
-ReadableByteStreamController

See also on MDN

Error(dynamic)

The error() method of the ReadableByteStreamController interface causes any future interactions with the associated stream to error with the specified reason.

[Value("error")]
public GlobalObject.Undefined Error(dynamic e = null)

Parameters

e dynamic

Returns

GlobalObject.Undefined

None (GlobalObject.Undefined).

Remarks

This is commonly called by an underlying source to surface an error from the interface where it gets its data (such as a file-read or socket error).
It can also be called from elsewhere to trigger a stream error, for example if another part of the system that the stream relies on fails.

-Using readable byte streams

See also on MDN