Class JsonRpcEnumerableExtensions

Namespace

Nerdbank.JsonRpc

Assembly

Nerdbank.JsonRpc.dll

Extension methods that control how an IAsyncEnumerable<T> is transmitted over a JSON-RPC connection.

public static class JsonRpcEnumerableExtensions

Inheritance

object

JsonRpcEnumerableExtensions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Methods

AsAsyncEnumerable<T>(IEnumerable<T>)

Exposes an existing collection as an IAsyncEnumerable<T> so that transmitting it over JSON-RPC streams the values on demand instead of sending the whole collection in one message.

public static IAsyncEnumerable<T> AsAsyncEnumerable<T>(this IEnumerable<T> enumerable)

Parameters

enumerable IEnumerable<T>

The collection to expose.

Returns

IAsyncEnumerable<T>

An async sequence over enumerable.

Type Parameters

T

The type of value in the collection.

RequestEnumerable<T>(IJsonRpcClient, string, JsonRpcValue, ITypeShape<IAsyncEnumerable<T>>, CancellationToken)

Issues a JSON-RPC request whose result is an IAsyncEnumerable<T> and exposes the sequence without waiting for the response.

public static IAsyncEnumerable<T> RequestEnumerable<T>(IJsonRpcClient client, string method, JsonRpcValue arguments, ITypeShape<IAsyncEnumerable<T>> resultShape, CancellationToken cancellationToken)

Parameters

client IJsonRpcClient

The client to send the request over.

method string

The remote method name.

arguments JsonRpcValue

The encoded arguments.

resultShape ITypeShape<IAsyncEnumerable<T>>

The shape of the IAsyncEnumerable<T> result type.

cancellationToken CancellationToken

A token to cancel the request and the enumeration.

Returns

IAsyncEnumerable<T>

A sequence that may be enumerated exactly once.

Type Parameters

T

The type of value produced by the sequence.

Remarks

This method is intended for use by generated proxies. The request is sent immediately so that it participates correctly in a JsonRpcBatch; only the response is awaited lazily.

WithJsonRpcSettings<T>(IAsyncEnumerable<T>, JsonRpcEnumerableSettings)

Applies JSON-RPC transmission settings to a sequence that is about to be sent to a remote party.

public static IAsyncEnumerable<T> WithJsonRpcSettings<T>(this IAsyncEnumerable<T> enumerable, JsonRpcEnumerableSettings settings)

Parameters

enumerable IAsyncEnumerable<T>

The sequence to decorate.

settings JsonRpcEnumerableSettings

The settings to apply.

Returns

IAsyncEnumerable<T>

A decorated sequence to use as the RPC argument or return value.

Type Parameters

T

The type of value produced by the sequence.

Examples

public IAsyncEnumerable<int> GetNumbersAsync(CancellationToken cancellationToken)
    => this.GetNumbersCoreAsync(cancellationToken)
           .WithJsonRpcSettings(new JsonRpcEnumerableSettings { MinBatchSize = 10 });

Remarks

Settings are only honored by the party that sends the sequence, and are ignored if applied by the receiver. The returned sequence behaves identically to enumerable when enumerated locally.

WithPrefetchAsync<T>(IAsyncEnumerable<T>, int, CancellationToken)

Produces the first several values of a sequence immediately so they can be included in the very message that carries the sequence to the remote party, sparing the receiver a round-trip.

public static ValueTask<IAsyncEnumerable<T>> WithPrefetchAsync<T>(this IAsyncEnumerable<T> enumerable, int count, CancellationToken cancellationToken = default)

Parameters

enumerable IAsyncEnumerable<T>

The sequence to prefetch values from.

count int

The maximum number of values to produce up front.

cancellationToken CancellationToken

A token to cancel value production.

Returns

ValueTask<IAsyncEnumerable<T>>

A decorated sequence carrying the prefetched values.

Type Parameters

T

The type of value produced by the sequence.

Remarks

Use this for a sequence passed as an RPC argument or nested within an object graph. For a sequence returned directly from an RPC method, prefer Prefetch so the RPC method itself need not be asynchronous.