Class JsonRpcEnumerableSettings

Namespace

Nerdbank.JsonRpc

Assembly

Nerdbank.JsonRpc.dll

Tunes how an IAsyncEnumerable<T> is transmitted across a JSON-RPC connection.

public record JsonRpcEnumerableSettings : IEquatable<JsonRpcEnumerableSettings>

Inheritance

object

JsonRpcEnumerableSettings

Implements

IEquatable<JsonRpcEnumerableSettings>

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

The default values reproduce the behavior of a local IAsyncEnumerable<T>: exactly one value is produced and transmitted at a time, and only when the consumer asks for it.

These settings are only honored by the generator (the party that sends the enumerable). They are ignored when applied by the consumer. Apply them with WithJsonRpcSettings<T>(IAsyncEnumerable<T>, JsonRpcEnumerableSettings).

Properties

Default

Gets the default settings, which transmit one value per round-trip with no read ahead or prefetch.

public static JsonRpcEnumerableSettings Default { get; }

Property Value

JsonRpcEnumerableSettings

MaxReadAhead

Gets the maximum number of values to produce and cache from the generator in anticipation of the consumer asking for them.

public int MaxReadAhead { get; init; }

Property Value

int

Defaults to 0, meaning the generator produces values only while responding to a consumer request.

Remarks

Raising this improves throughput when producing each value is slow, because the generator can be working on later values while earlier ones are in transit or being processed by the consumer.

Exceptions

ArgumentOutOfRangeException

Thrown when set to a negative value.

MinBatchSize

Gets the minimum number of values the generator collects before responding to a consumer's request for more values.

public int MinBatchSize { get; init; }

Property Value

int

Defaults to 1.

Remarks

Raising this reduces the number of round-trips the consumer makes while enumerating, which improves performance when network latency is significant. The generator always sends fewer than this number of values when the sequence ends first.

Exceptions

ArgumentOutOfRangeException

Thrown when set to a value less than 1.

Prefetch

Gets the number of values to produce up front and include in the message that carries the enumerable itself, sparing the consumer a round-trip for the first values.

public int Prefetch { get; init; }

Property Value

int

Defaults to 0.

Remarks

This is only applied to an IAsyncEnumerable<T> returned directly from an RPC method.

To prefetch values for an enumerable used as an RPC method argument, or nested within an object graph, use WithPrefetchAsync<T>(IAsyncEnumerable<T>, int, CancellationToken) instead and leave this at 0.

Exceptions

ArgumentOutOfRangeException

Thrown when set to a negative value.