Class Sequence<T>

Namespace

MarymoorStudios.Core.Rpc

Assembly

MarymoorStudios.Core.Rpc.dll

Provides iterators for Sequence<T>.

public sealed class Sequence<T> : IPromiseDisposable, IDisposable, IPromiseEnumerable<T>

Type Parameters

T

Inheritance

object

Sequence<T>

Implements

IPromiseDisposable

IDisposable

IPromiseEnumerable<T>

Inherited Members

object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Properties

BatchSize

The batch size suggested by the reader.

public int BatchSize { get; set; }

Property Value

int

Capacity

The desired capacity of the reader.

public int Capacity { get; set; }

Property Value

int

Methods

Cancel(Exception?)

Attempts to perform a graceful early termination by the sequence with a diagnostic error for the Writer.

public void Cancel(Exception? error = null)

Parameters

error Exception

An optional diagnostic error. If no error is provided then OperationCanceledException will be sent.

Remarks

The Read() method will eventually return EOS (or error) after Cancel(Exception?) has been called, either because cancellation is successfully propagated to the Writer or because the underlying channel is aborted before cancellation can be propagated.

Cancellation is pr

Create(Func<Writer, Promise>, int, int)

Constructs a new Pipe<T>

public static Sequence<T> Create(Func<Sequence<T>.Writer, Promise> body, int capacity = 100, int batchSize = 20)

Parameters

body Func<Sequence<T>.Writer, Promise>

A function that will generate the contents of the sequence.

capacity int

The maximum number of items before backpressure is applied.

batchSize int

The reader suggested batch size.

Returns

Sequence<T>

Remarks

REQUIRES: capacity > 0

REQUIRES: 1 <= batchSize <= capacity

The batchSize is used to decrease ping-ponging by delaying waking the producer until there are more items in the window. There is a tradeoff between added latency and buffering costs on the writer side versus signalling costs. The default value is 1 causing the producer to be signalled whenever there is at least one slot available.

Create(int, int)

Constructs a new Pipe<T>

public static (Sequence<T> reader, Sequence<T>.Writer writer) Create(int capacity = 100, int batchSize = 20)

Parameters

capacity int

The maximum number of items before backpressure is applied.

batchSize int

The reader suggested batch size.

Returns

(Sequence<T> reader, Sequence<T>.Writer writer)

Remarks

REQUIRES: capacity > 0

REQUIRES: 1 <= batchSize <= capacity

The batchSize is used to decrease ping-ponging by delaying waking the producer until there are more items in the window. There is a tradeoff between added latency and buffering costs on the writer side versus signalling costs. The default value is 1 causing the producer to be signalled whenever there is at least one slot available.

Dispose()

Releases all received but unread items.

public void Dispose()

Remarks

Implies a call to Cancel(Exception?) if the sequence has not seen EOS or already been cancelled.

Any items that are received by the transport after the Reader has been disposed will be immediately released.

DisposeAsync()

Releases all received but unread items.

public Promise DisposeAsync()

Returns

Promise

A promise that resolves when all in-flight items have been exhausted from the transport.

Remarks

Implies a call to Cancel(Exception?) if the sequence has not seen EOS or already been cancelled.

Any items that are received by the transport after the Reader has been disposed will be immediately released.

ForEach(Func<T, Promise>)

Yields each of the items in the sequence to the body function.

public Promise ForEach(Func<T, Promise> body)

Parameters

body Func<T, Promise>

A function to process each item.

Returns

Promise

Resolves successfully if the entire sequence was read to the end without encountering an error, otherwise breaks with the first error encountered by the sequence.

GetAsyncEnumerator(CancellationToken)

Returns an enumerator that iterates asynchronously through the Sequence<T>.

public Sequence<T>.SequenceEnumerator GetAsyncEnumerator(CancellationToken token = default)

Parameters

token CancellationToken

Returns

Sequence<T>.SequenceEnumerator

Read()

Reads the next available item from the sequence.

public Promise<T> Read()

Returns

Promise<T>

The next item or an error.

Remarks

Returns the next item in the sequence. If there are no items available immediately, then the return resolves when the next item arrives.

On a successful return ownership for the item returned is transferred to the caller who is responsible for disposing it.

If the end of the sequence (EOS) is reached (i.e. a finite sequence) then reading after the EOS will yield an EndOfSequenceException error.

If the sequence is closed by the Writer with an error, that error will be returned in sequence order after all items successfully written before the error have been delivered.

If the sequence is aborted by the Writer or the underlying transport a read will yield an AbortedException. Some items in the sequence may have been lost in the event of an abort.