Class ConnectionCache

Namespace

IceRpc

Assembly

IceRpc.dll

Represents an invoker that routes outgoing requests to connections it manages.

public sealed class ConnectionCache : IInvoker, IAsyncDisposable

Inheritance

object

ConnectionCache

Implements

IInvoker

IAsyncDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

InvokerExtensions.InvokeBidiStreamingAsync<TInput, TOutput>(IInvoker, ServiceAddress, string, IAsyncEnumerable<TInput>, MessageParser<TOutput>, ProtobufEncodeOptions?, IFeatureCollection?, bool, CancellationToken)

InvokerExtensions.InvokeClientStreamingAsync<TInput, TOutput>(IInvoker, ServiceAddress, string, IAsyncEnumerable<TInput>, MessageParser<TOutput>, ProtobufEncodeOptions?, IFeatureCollection?, bool, CancellationToken)

InvokerExtensions.InvokeServerStreamingAsync<TOutput>(IInvoker, ServiceAddress, string, IMessage, MessageParser<TOutput>, ProtobufEncodeOptions?, IFeatureCollection?, bool, CancellationToken)

InvokerExtensions.InvokeUnaryAsync<TOutput>(IInvoker, ServiceAddress, string, IMessage, MessageParser<TOutput>, ProtobufEncodeOptions?, IFeatureCollection?, bool, CancellationToken)

Remarks

The connection cache routes requests based on the request's IServerAddressFeature feature or the server addresses of the request's target service.

The connection cache keeps at most one active connection per server address.

Constructors

ConnectionCache()

Constructs a connection cache using the default options.

public ConnectionCache()

ConnectionCache(ConnectionCacheOptions, IDuplexClientTransport?, IMultiplexedClientTransport?, ILogger?)

Constructs a connection cache.

public ConnectionCache(ConnectionCacheOptions options, IDuplexClientTransport? duplexClientTransport = null, IMultiplexedClientTransport? multiplexedClientTransport = null, ILogger? logger = null)

Parameters

options ConnectionCacheOptions

The connection cache options.

duplexClientTransport IDuplexClientTransport

The duplex client transport. null is equivalent to Default.

multiplexedClientTransport IMultiplexedClientTransport

The multiplexed client transport. null is equivalent to Default.

logger ILogger

The logger. null is equivalent to Instance.

Methods

DisposeAsync()

Releases all resources allocated by the cache. The cache disposes all the connections it created.

public ValueTask DisposeAsync()

Returns

ValueTask

A value task that completes when the disposal of all connections created by this cache has completed. This includes connections that were active when this method is called and connections whose disposal was initiated prior to this call.

Remarks

The disposal of an underlying connection of the cache aborts invocations, cancels dispatches and disposes the underlying transport connection without waiting for the peer. To wait for invocations and dispatches to complete, call ShutdownAsync(CancellationToken) first. If the configured dispatcher does not complete promptly when its cancellation token is canceled, the disposal can hang.

InvokeAsync(OutgoingRequest, CancellationToken)

Sends an outgoing request and returns the corresponding incoming response.

public Task<IncomingResponse> InvokeAsync(OutgoingRequest request, CancellationToken cancellationToken)

Parameters

request OutgoingRequest

The outgoing request being sent.

cancellationToken CancellationToken

A cancellation token that receives the cancellation requests.

Returns

Task<IncomingResponse>

The corresponding IncomingResponse.

Remarks

If the request IServerAddressFeature feature is not set, the cache sets it from the server addresses of the target service.

It then looks for an active connection. The PreferExistingConnection property influences how the cache selects this active connection. If no active connection can be found, the cache creates a new connection to one of the server addresses from the IServerAddressFeature feature.

If the connection establishment to ServerAddress fails, ServerAddress is appended at the end of AltServerAddresses and the first address from AltServerAddresses replaces ServerAddress. The cache tries again to find or establish a connection to ServerAddress. If unsuccessful, the cache repeats this process until success or until it tried all the addresses. If all the attempts fail, this method throws the exception from the last attempt.

Exceptions

InvalidOperationException

Thrown if no IServerAddressFeature feature is set and the request's service address has no server addresses.

IceRpcException

Thrown with one of the following error:

• InvocationRefusedThis error indicates that the connection cache is shutdown.
• NoConnectionThis error indicates that the request IServerAddressFeature feature has no server addresses.

.

ObjectDisposedException

Thrown if this connection cache is disposed.

ShutdownAsync(CancellationToken)

Gracefully shuts down all connections created by this cache.

public Task ShutdownAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

A cancellation token that receives the cancellation requests.

Returns

Task

A task that completes successfully once the shutdown of all connections created by this cache has completed. This includes connections that were active when this method is called and connections whose shutdown was initiated prior to this call. This task can also complete with one of the following exceptions:

• IceRpcException with error OperationAborted if the connection cache is disposed while being shut down.
• OperationCanceledException if cancellation was requested through the cancellation token.
• TimeoutException if the shutdown timed out.

Exceptions

InvalidOperationException

Thrown if this method is called more than once.

ObjectDisposedException

Thrown if the connection cache is disposed.